Upgrading Configs

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 Version 3.3.0 to 3.4.0
From Version 3.2.0 to 3.3.0
1. Kernel arguments
2. New filesystem format none
From Version 3.1.0 to 3.2.0
From Version 3.0.0 to 3.1.0
From Version 2.3.0 to 3.0.0
From 2.x.0 to 2.3.0

From Version 3.3.0 to 3.4.0

There are not any breaking changes between versions 3.3.0 and 3.4.0 of the configuration specification. Any valid 3.3.0 configuration can be updated to a 3.4.0 configuration by simply changing the version string in the config.

The following is a list of notable new features, deprecations, and changes.

Offline Tang provisioning

The tang section gained a new advertisement field. If specified, Ignition will use it to provision the Tang server binding rather than fetching the advertisement from the server at runtime. This allows the server to be unavailable at provisioning time. The advertisement can be obtained from the server with curl http://tang.example.com/adv.

{
  "ignition": { "version": "3.4.0" },
  "storage": {
    "luks": [{
      "name": "luks-tang",
      "device": "/dev/sdb",
      "clevis": {
        "tang": [{
          "url": "https://tang.example.com",
          "thumbprint": "REPLACE-THIS-WITH-YOUR-TANG-THUMBPRINT",
          "advertisement": "{\"payload\": \"...\", \"protected\": \"...\", \"signature\": \"...\"}"
        }]
      }
    }]
  }
}

LUKS discard

The luks section gained a new discard field. If specified and true, the LUKS volume will issue discard commands to the underlying block device when blocks are freed. This improves performance and device longevity on SSDs and space utilization on thinly provisioned SAN devices, but leaks information about which disk blocks contain data.

{
  "ignition": { "version": "3.4.0" },
  "storage": {
    "luks": [{
      "name": "luks-tpm",
      "device": "/dev/sdb",
      "discard": true,
      "clevis": {
        "tpm2": true
      }
    }]
  }
}

LUKS open options

The luks section gained a new openOptions field. It is a list of options Ignition should pass to cryptsetup luksOpen when unlocking the volume. Ignition also passes --persistent, so any options that support persistence will be saved to the volume and automatically used for future unlocks. Any options that do not support persistence will only be applied to Ignition’s initial unlock of the volume.

{
  "ignition": { "version": "3.4.0" },
  "storage": {
    "luks": [{
      "name": "luks-tpm",
      "device": "/dev/sdb",
      "openOptions": ["--perf-no_read_workqueue", "--perf-no_write_workqueue"],
      "clevis": {
        "tpm2": true
      }
    }]
  }
}

Special mode bits supported

The mode field of the files and directories sections now respects the setuid, setgid, and sticky bits. Previous spec versions ignore these bits, but will generate a warning on Ignition ≥ 2.14.0.

{
  "ignition": {
    "version": "3.4.0"
  },
  "storage": {
    "files": [{
      "path": "/usr/local/bin/setuid",
      "contents": {
        "source": "https://rootkit.example.com/setuid"
      },
      "mode": 2541
    }],
    "directories": [{
      "path": "/var/local/tmp",
      "mode": 1023
    }]
  }
}

AWS S3 access point ARN support

The sections which allow fetching a remote URL now accept AWS S3 access point ARNs (arn:aws:s3:<region>:<account>:accesspoint/<accesspoint>/object/<path>) in the source field.

{
  "ignition": { "version": "3.4.0" },
  "storage": {
    "files": [{
      "path": "/etc/example",
      "mode": 420,
      "contents": {
        "source": "arn:aws:s3:us-west-1:123456789012:accesspoint/test/object/some/path"
      }
    }]
  }
}

From Version 3.2.0 to 3.3.0

There are not any breaking changes between versions 3.2.0 and 3.3.0 of the configuration specification. Any valid 3.2.0 configuration can be updated to a 3.3.0 configuration by simply changing the version string in the config.

The following is a list of notable new features, deprecations, and changes.

Kernel arguments

The config gained a new top-level kernelArguments section. It allows specifying arguments that should be included or excluded from the kernel command line.

{
  "ignition": { "version": "3.3.0" },
  "kernelArguments": {
    "shouldExist": [
      "foobar",
      "baz boo"
    ],
    "shouldNotExist": [
      "raboof"
    ]
  }
}

The config above will ensure that the kernel argument foobar is present, and the kernel argument raboof is absent. It will also ensure that the kernel arguments baz boo are present exactly in that order.

This feature requires integration with the distribution where Ignition is used. See the [distributor notes][distributor-notes] for details.

New filesystem format `none`

The format field of the filesystems section can now be set to none. This setting erases an existing filesystem signature without creating a new filesystem (if wipeFilesystem is true), or fails if there is any existing filesystem (if wipeFilesystem is false).

{
  "ignition": { "version": "3.3.0" },
  "storage": {
    "filesystems": [{
      "device": "/dev/vdb1",
      "wipeFilesystem": true,
      "format": "none"
    }]
  }
}

Refer to the filesystem reuse semantics for more information.

From Version 3.1.0 to 3.2.0

There are not any breaking changes between versions 3.1.0 and 3.2.0 of the configuration specification. Any valid 3.1.0 configuration can be updated to a 3.2.0 configuration by simply changing the version string in the config.

The following is a list of notable new features, deprecations, and changes.

Partition resizing

The partition section gained a new resize field. When true, Ignition will resize an existing partition if it matches the config in all respects except the partition size.

{
  "ignition": { "version": "3.2.0" },
  "storage": {
    "disks": [{
      "device": "/dev/sda",
      "partitions": [{
        "label": "root",
        "sizeMiB": 16384,
        "resize": true
      }]
    }]
  }
}

LUKS encrypted storage

Ignition now supports creating LUKS2 encrypted storage volumes. Volumes can be configured to allow unlocking with any combination of a TPM2 device via Clevis, network Tang servers via Clevis, and static key files. Alternatively, the Clevis configuration can be manually specified with a custom PIN and CFG. If a key file is not specified for a device, an ephemeral one will be created.

{
  "ignition": {"version": "3.2.0"},
  "storage": {
    "luks": [{
      "name": "static-key-example",
      "device": "/dev/sdb",
      "keyFile": {
        "source": "data:,REPLACE-THIS-WITH-YOUR-KEY-MATERIAL"
      }
    },{
      "name": "tpm-example",
      "device": "/dev/sdc",
      "clevis": {
        "tpm2": true
      }
    },{
      "name": "tang-example",
      "device": "/dev/sdd",
      "clevis": {
        "tang": [{
          "url": "https://tang.example.com",
          "thumbprint": "REPLACE-THIS-WITH-YOUR-TANG-THUMBPRINT"
        }]
      }
    }],
    "filesystems": [{
      "path": "/var/lib/static_key_example",
      "device": "/dev/disk/by-id/dm-name-static-key-example",
      "format": "ext4",
      "label": "STATIC-EXAMPLE"
    },{
      "path": "/var/lib/tpm_example",
      "device": "/dev/disk/by-id/dm-name-tpm-example",
      "format": "ext4",
      "label": "TPM-EXAMPLE"
    },{
      "path": "/var/lib/tang_example",
      "device": "/dev/disk/by-id/dm-name-tang-example",
      "format": "ext4",
      "label": "TANG-EXAMPLE"
    }]
  },
  "systemd": {
    "units": [{
      "name": "var-lib-static_key_example.mount",
      "enabled": true,
      "contents": "[Mount]\nWhat=/dev/disk/by-label/STATIC-EXAMPLE\nWhere=/var/lib/static_key_example\nType=ext4\n\n[Install]\nWantedBy=local-fs.target"
    },{
      "name": "var-lib-tpm_example.mount",
      "enabled": true,
      "contents": "[Mount]\nWhat=/dev/disk/by-label/TPM-EXAMPLE\nWhere=/var/lib/tpm_example\nType=ext4\n\n[Install]\nWantedBy=local-fs.target"
    },{
      "name": "var-lib-tang_example.mount",
      "enabled": true,
      "contents": "[Mount]\nWhat=/dev/disk/by-label/TANG-EXAMPLE\nWhere=/var/lib/tang_example\nType=ext4\n\n[Install]\nWantedBy=remote-fs.target"
    }]
  }
}

User/group deletion

The passwd users and groups sections have a new field shouldExist. If specified and false, Ignition will delete the specified user or group if it exists.

{
  "ignition": { "version": "3.2.0" },
  "passwd": {
    "users": [{
      "name": "core",
      "shouldExist": false
    }],
    "groups": [{
      "name": "core",
      "shouldExist": false
    }]
  }
}

Google Cloud Storage URL support

The sections which allow fetching a remote URL now accept Google Cloud Storage (gs://) URLs in the source field.

{
  "ignition": { "version": "3.2.0" },
  "storage": {
    "files": [{
      "path": "/etc/example",
      "mode": 420,
      "contents": {
        "source": "gs://bucket/object"
      }
    }]
  }
}

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.

{
  "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.

{
  "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.

{
  "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.

{
  "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

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).

{
  "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

The 3.0.0 version of the configuration is fully incompatible with prior versions (i.e. v1, v2.x.0) of the config. The previous versions had bugs that are not representable as a 3.0.0 config, so Ignition does not support older versions.

All deprecated fields are dropped

All deprecated fields have been dropped. Refer to this migration guide in the spec2x branch for how to migrate to their replacements first.

Filesystems now specify path

Ignition now will mount filesystems at the mountpoint specified by path when running. Filesystems no longer have the name field and files, links, and directories no longer specify the filesystem by name. To create a file on a specified filesystem, ensure that the specified path for that filesystem is below the mountpoint for that filesystem. The following two configs are equivalent and both specify /dev/disk/by-label/VAR should be an XFS filesystem with an empty file named example-file at that filesystem’s root. Note the path change in the files section to account for the filesystem’s mountpoint.

{
  "ignition": { "version": "2.3.0" },
  "storage": {
    "filesystems": [{
      "name": "var",
      "mount": {
        "device": "/dev/disk/by-label/VAR",
        "format": "xfs",
        "wipeFilesystem": true,
        "label": "var"
      }
    }],
    "files": [{
      "filesystem": "var",
      "path": "/example-file",
      "mode": 420,
      "contents": { "source": "" }
    }]
  }
}

{
  "ignition": { "version": "3.0.0" },
  "storage": {
    "filesystems": [{
      "path": "/var",
      "device": "/dev/disk/by-label/VAR",
      "format": "xfs",
      "wipeFilesystem": true,
      "label": "var"
    }],
    "files": [{
      "path": "/var/example-file",
      "mode": 420,
      "contents": { "source": "" }
    }]
  }
}

Files now default to overwrite=false

Files do not overwrite existing files by default. If no source is specified, Ignition will simply ensure a file exists at that path, creating an empty file if necessary.

File permissions now default to 0644

If file permissions are unspecified, the permissions default to 0644. If Ignition does not need to create or overwrite the file (i.e. overwrite is false, a file exists at that path, and source is nil), it will not change the mode, owner or group.

Directories now create leading directories with mode 0755 and uid/gid 0

When a file, directory, or link is specified but the parent directory does not exist, Ignition will create the directory(ies) leading up to it. Previously, when a directory was specified, any leading directories were created with the same mode/uid/gid as the specified directory. Now they are created with mode 0755, uid 0, and gid 0. This ensures the behavior is consistent with files and links.

Duplicate entries are no longer allowed

Configs cannot specify contradictory entries. This means a config cannot contain two file entries with the same path, or specify a path as both a link and a file.

Configuration appending is replaced by configuration merging

ignition.config.append has been replaced by ignition.config.merge. Instead of appending entries from the child configs, Ignition merges them. Refer to the operator notes for more information.

Files now have a list of sources to append

Files now have a list of contents to append instead of multiple entries with append=true. The following two configs are equivalent. Since overwrite is false and contents.source is unspecified, Ignition will first ensure a file exists at the path (creating it if necessary) and then append both contents to it.

{
  "ignition": { "version": "2.3.0" },
  "storage": {
    "files": [{
      "filesystem": "root",
      "path": "/example-file",
      "mode": 420,
      "append": true,
      "contents": { "source": "data:,hello" }
    },
    {
      "filesystem": "root",
      "path": "/example-file",
      "mode": 420,
      "append": true,
      "contents": { "source": "data:,world" }
    }]
  }
}

{
  "ignition": { "version": "3.0.0" },
  "storage": {
    "files": [{
      "path": "/example-file",
      "mode": 420,
      "append": [
        { "source": "data:,hello" },
        { "source": "data:,world" }
      ]
    }]
  }
}

Networkd section is removed

The networkd section has been removed. Use the files section instead. Refer to the networkd documentation for more information.

From 2.x.0 to 2.3.0

Refer to this doc in the spec2x 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.

Upgrading Configs

From Version 3.3.0 to 3.4.0

Offline Tang provisioning

LUKS discard

LUKS open options

Special mode bits supported

AWS S3 access point ARN support

From Version 3.2.0 to 3.3.0

Kernel arguments

New filesystem format none

From Version 3.1.0 to 3.2.0

Partition resizing

LUKS encrypted storage

User/group deletion

Google Cloud Storage URL support

From Version 3.0.0 to 3.1.0

SHA-256 resource verification

Compression support for certificate authorities and merged configs

Filesystem mount options

Custom HTTP headers

HTTP proxies

From Version 2.3.0 to 3.0.0

All deprecated fields are dropped

Filesystems now specify path

Files now default to overwrite=false

File permissions now default to 0644

Directories now create leading directories with mode 0755 and uid/gid 0

Duplicate entries are no longer allowed

Configuration appending is replaced by configuration merging

Files now have a list of sources to append

Networkd section is removed

From 2.x.0 to 2.3.0

New filesystem format `none`