Example Configs

These examples are written in version 3.0.0 of the config. Ignition v2.0.0+ understands all configs with version 3.0.0+.

  1. Services
    1. Start Services
    2. Modify Services
  2. Create Files on the Root Filesystem
  3. Reformat the /var Filesystem
    1. Btrfs
  4. Create a RAID-enabled Data Volume
  5. Replace the Config with a Remote Config
  6. Set the Hostname
  7. Add Users
  8. Create a LUKS Volume
  9. Set Kernel Arguments

Services

Start Services

This config will write a single service unit (shown below) with the contents of an example service. This unit will be enabled as a dependency of multi-user.target and therefore start on boot.

{
  "ignition": { "version": "3.0.0" },
  "systemd": {
    "units": [{
      "name": "example.service",
      "enabled": true,
      "contents": "[Service]\nType=oneshot\nExecStart=/usr/bin/echo Hello World\n\n[Install]\nWantedBy=multi-user.target"
    }]
  }
}

example.service:

[Service]
Type=oneshot
ExecStart=/usr/bin/echo Hello World

[Install]
WantedBy=multi-user.target

Modify Services

This config will add a systemd unit drop-in to modify the existing service systemd-journald and sets its environment variable SYSTEMD_LOG_LEVEL to debug.

{
  "ignition": { "version": "3.0.0" },
  "systemd": {
    "units": [{
      "name": "systemd-journald.service",
      "dropins": [{
        "name": "debug.conf",
        "contents": "[Service]\nEnvironment=SYSTEMD_LOG_LEVEL=debug"
      }]
    }]
  }
}

systemd-journald.service.d/debug.conf:

[Service]
Environment=SYSTEMD_LOG_LEVEL=debug

Create Files on the Root Filesystem

In many cases it is useful to write files to the root filesystem. This example writes a single file to /etc/someconfig on the root filesystem. The contents of the file (“example file”) are specified inline in the config using the data URL scheme.

{
  "ignition": { "version": "3.0.0" },
  "storage": {
    "files": [{
      "path": "/etc/someconfig",
      "mode": 420,
      "contents": { "source": "data:,example%20file%0A" }
    }]
  }
}

Paths are specified relative to the root filesystem of the system Ignition is configuring. Symlinks are followed as if Ignition was running from the final system. See the operator notes for more information about how Ignition follows symlinks.

Reformat the /var Filesystem

Btrfs

This example Ignition configuration will locate the device with the “VAR” filesystem label and reformat it to btrfs, recreating the filesystem label. The wipeFilesystem option is set to ensure that Ignition ignores any existing filesystem. This configuration also writes a file to /var/example-asset, fetching its contents from https://example.com/asset. Ignition mounts filesystems it creates at the specified path before creating anything on the filesystems, ensuring /var/example-asset is created on the newly created filesystem. Note that Ignition will not automatically create mount units or /etc/fstab entries for the filesystems it creates. In this case we assume the OS already has a mount unit or /etc/fstab entry for the /var filesystem by label.

{
  "ignition": { "version": "3.0.0" },
  "storage": {
    "filesystems": [{
      "device": "/dev/disk/by-label/VAR",
      "path": "/var",
      "format": "btrfs",
      "wipeFilesystem": true,
      "label": "VAR"
    }],
    "files": [{
      "path": "/var/example-asset",
      "mode": 420,
      "contents": {
        "source": "http://example.com/asset",
        "verification": { "hash": "sha512-0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" }
      }
    }]
  }
}

The SHA512 sum of the file can be determined using sha512sum. SHA256 sums are also supported, and can be calculated using sha256sum.

Create a RAID-enabled Data Volume

In many scenarios, it may be useful to have an external data volume. This config will set up a RAID0 ext4 volume, data, between two separate disks. It also writes a mount unit (shown below) which will automatically mount the volume to /var/lib/data.

{
  "ignition": { "version": "3.0.0" },
  "storage": {
    "disks": [
      {
        "device": "/dev/sdb",
        "wipeTable": true,
        "partitions": [{
          "label": "raid.1.1",
          "number": 1,
          "sizeMiB": 1024,
          "startMiB": 0
        }]
      },
      {
        "device": "/dev/sdc",
        "wipeTable": true,
        "partitions": [{
          "label": "raid.1.2",
          "number": 1,
          "sizeMiB": 1024,
          "startMiB": 0
        }]
      }
    ],
    "raid": [{
      "devices": [
        "/dev/disk/by-partlabel/raid.1.1",
        "/dev/disk/by-partlabel/raid.1.2"
      ],
      "level": "stripe",
      "name": "data"
    }],
    "filesystems": [{
      "device": "/dev/md/data",
      "path": "/var/lib/data",
      "format": "ext4",
      "label": "DATA"
    }]
  },
  "systemd": {
    "units": [{
      "name": "var-lib-data.mount",
      "enabled": true,
      "contents": "[Mount]\nWhat=/dev/md/data\nWhere=/var/lib/data\nType=ext4\n\n[Install]\nWantedBy=local-fs.target"
    }]
  }
}

var-lib-data.mount:

[Mount]
What=/dev/md/data
Where=/var/lib/data
Type=ext4

[Install]
WantedBy=local-fs.target

Replace the Config with a Remote Config

In some cloud environments, there is a limit on the size of the config which may be provided to a machine. To work around this, Ignition allows configs to be replaced with the contents of an alternate, remote config. The following demonstrates this, using a SHA512 sum to verify the contents of the config.

{
  "ignition": {
    "version": "3.0.0",
    "config": {
      "replace": {
        "source": "http://example.com/config.json",
        "verification": { "hash": "sha512-0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" }
      }
    }
  }
}

The SHA512 sum of the config can be determined using sha512sum. SHA256 sums are also supported, and can be calculated using sha256sum.

Set the Hostname

Setting the hostname of a system is as simple as writing /etc/hostname:

{
  "ignition": { "version": "3.0.0" },
  "storage": {
    "files": [{
      "path": "/etc/hostname",
      "mode": 420,
      "overwrite": true,
      "contents": { "source": "data:,core1" }
    }]
  }
}

Add Users

Users can be added to an OS with the passwd.users key which takes a list of objects that specify a given user. If you wanted to configure a user “systemUser” and a user “jenkins” you would do that as follows:

{
  "ignition": { "version": "3.0.0" },
  "passwd": {
    "users": [
      {
        "name": "systemUser",
        "passwordHash": "$superSecretPasswordHash.",
        "sshAuthorizedKeys": [
          "ssh-rsa veryLongRSAPublicKey"
        ]
      },
      {
        "name": "jenkins",
        "uid": 1000
      }
    ]
  }
}

To add more users, configure them within the users list structure ([...]).

Create a LUKS Volume

This config will set up a key-file based LUKS2 volume, data, put a filesystem on the volume, and write a mount unit (shown below) to automatically mount the volume to /var/lib/data.

{
  "ignition": {"version": "3.2.0"},
  "storage": {
    "luks": [{
      "name": "data",
      "device": "/dev/sdb"
    }],
    "filesystems": [{
      "path": "/var/lib/data",
      "device": "/dev/disk/by-id/dm-name-data",
      "format": "ext4",
      "label": "DATA"
    }]
  },
  "systemd": {
    "units": [{
      "name": "var-lib-data.mount",
      "enabled": true,
      "contents": "[Mount]\nWhat=/dev/disk/by-label/DATA\nWhere=/var/lib/data\nType=ext4\n\n[Install]\nWantedBy=local-fs.target"
    }]
  }
}

var-lib-data.mount:

[Mount]
What=/dev/disk/by-label/DATA
Where=/var/lib/data
Type=ext4

[Install]
WantedBy=local-fs.target

Set Kernel Arguments

This config will ensure that the example and foo bar kernel arguments are set and the somekarg kernel argument is not set.

{
  "ignition": {"version": "3.3.0"},
  "kernelArguments": {
    "shouldExist": ["example", "foo bar"],
    "shouldNotExist": ["somekarg"]
  }
}