Merge pull request #971 from bgilbert/migrating

doc/migrating-configs: update for 3.1.0

doc/migrating-configs.md

@@ -2,9 +2,147 @@
 
 Occasionally, there are changes made to Ignition's configuration that break backward compatibility. While this is not a concern for running machines (since Ignition only runs one time during first boot), it is a concern for those who maintain configuration files. This document serves to detail each of the breaking changes and tries to provide some reasoning for the change. This does not cover all of the changes to the spec - just those that need to be considered when migrating from one version to the next.
 
-## From 2.x.0 to 2.3.0
+## From Version 3.0.0 to 3.1.0
+
+There are not any breaking changes between versions 3.0.0 and 3.1.0 of the configuration specification. Any valid 3.0.0 configuration can be updated to a 3.1.0 configuration by simply changing the version string in the config.
+
+The following is a list of notable new features, deprecations, and changes.
+
+### SHA-256 resource verification
+
+All `verification.hash` fields now support the `sha256` hash type.
+
+```json ignition
+{
+  "ignition": { "version": "3.1.0" },
+  "storage": {
+    "files": [{
+      "path": "/etc/hosts",
+      "mode": 420,
+      "contents": {
+        "source": "https://example.com/etc/hosts",
+        "verification": {
+          "hash": "sha256-e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+        }
+      }
+    }]
+  }
+}
+```
+
+### Compression support for certificate authorities and merged configs
+
+The config `merge` and `replace` sections and the `certificateAuthorities` section now support gzip-compressed resources via the `compression` field. `gzip` compression is supported for all URL schemes except `s3`.
+
+```json ignition
+{
+  "ignition": {
+    "version": "3.1.0",
+    "config": {
+      "merge": [{
+        "source": "https://secure.example.com/example.ign.gz",
+        "compression": "gzip"
+      }]
+    },
+    "security": {
+      "tls": {
+        "certificateAuthorities": [{
+          "source": "https://example.com/ca.pem.gz",
+          "compression": "gzip"
+        }]
+      }
+    }
+  }
+}
+```
+
+### Filesystem mount options
+
+The `filesystems` section gained a new `mountOptions` field. It is a list of options Ignition should pass to `mount -o` when mounting the specified filesystem. This is useful for mounting btrfs subvolumes. This field only affects mounting performed by Ignition while it is running; it does not affect mounting of the filesystem by the provisioned system.
+
+```json ignition
+{
+  "ignition": { "version": "3.1.0" },
+  "storage": {
+    "filesystems": [{
+      "path": "/var/data",
+      "device": "/dev/vdb1",
+      "wipeFilesystem": false,
+      "format": "btrfs",
+      "mountOptions": [
+        "subvolid=5"
+      ]
+    }]
+  }
+}
+```
+
+### Custom HTTP headers
+
+The sections which allow fetching a remote URL — config `merge` and `replace`, `certificateAuthorities`, and file `contents` and `append` — gained a new field called `httpHeaders`. This field can be set to an array of HTTP headers which will be added to an HTTP or HTTPS request. Custom headers can override Ignition's default headers, and will not be retained across HTTP redirects.
+
+During config merging, if a child config specifies a header `name` but not a corresponding `value`, any header with that `name` in the parent config will be removed.
+
+```json ignition
+{
+  "ignition": { "version": "3.1.0" },
+  "storage": {
+    "files": [{
+      "path": "/etc/hosts",
+      "mode": 420,
+      "contents": {
+        "source": "https://example.com/etc/hosts",
+        "httpHeaders": [
+          {
+            "name": "Authorization",
+            "value": "Basic YWxhZGRpbjpvcGVuc2VzYW1l"
+          },
+          {
+            "name": "User-Agent",
+            "value": "Mozilla/5.0 (compatible; MSIE 6.0; Windows NT 5.1)"
+          }
+        ]
+      }
+    }]
+  }
+}
+```
+
+### HTTP proxies
 
-Refer to [this doc in the `spec2x`](https://github.com/coreos/ignition/tree/spec2x/doc/migrating-configs.md) branch of this repository.
+The `ignition` section gained a new field called `proxy`. It allows configuring proxies for HTTP and HTTPS requests, as well as exempting certain hosts from proxying.
+
+The `httpsProxy` field specifies the proxy URL for HTTPS requests. The `httpProxy` field specifies the proxy URL for HTTP requests, and also for HTTPS requests if `httpsProxy` is not specified. The `noProxy` field lists specifiers of hosts that should not be proxied, in any of several formats:
+
+- An IP address prefix (`1.2.3.4`)
+- An IP address prefix in CIDR notation (`1.2.3.4/8`)
+- A domain name, matching the domain and its subdomains (`example.com`)
+- A domain name, matching subdomains only (`.example.com`)
+- A wildcard matching all hosts (`*`)
+
+IP addresses and domain names can also include a port number (`1.2.3.4:80`).
+
+```json ignition
+{
+  "ignition": {
+    "version": "3.1.0",
+    "proxy": {
+      "httpProxy": "https://proxy.example.net/",
+      "httpsProxy": "https://secure.proxy.example.net/",
+      "noProxy": ["www.example.net"]
+    }
+  },
+  "storage": {
+    "files": [{
+      "path": "/etc/hosts",
+      "mode": 420,
+      "contents": {
+        "source": "https://example.com/etc/hosts"
+      }
+    }]
+  }
+}
+```
 
 ## From Version 2.3.0 to 3.0.0
 
@@ -127,5 +265,9 @@ Files now have a list of contents to append instead of multiple entries with `ap
 
 The networkd section has been removed. Use the files section instead. Refer to the [networkd documentation][networkd-docs] for more information.
 
+## From 2.x.0 to 2.3.0
+
+Refer to [this doc in the `spec2x`](https://github.com/coreos/ignition/tree/spec2x/doc/migrating-configs.md) branch of this repository. That doc also describes specification version 2.4.0, a parallel development which shares some enhancements with spec 3.1.0.
+
 [networkd-docs]: https://www.freedesktop.org/software/systemd/man/systemd-networkd.html#
 [operator-notes]: operator-notes.md