Producing an Ignition Config

Ignition overview

Ignition is a provisioning utility that reads a configuration file (in JSON format) and provisions a Fedora CoreOS system based on that configuration. Configurable components include storage and filesystems, systemd units, and users.

Ignition runs only once during the first boot of the system (while in the initramfs). Because Ignition runs so early in the boot process, it can re-partition disks, format filesystems, create users, and write files before the userspace begins to boot. As a result, systemd services are already written to disk when systemd starts, speeding the time to boot.

Configuration process

Ignition configurations are formatted as JSON, which is quick and easy for a machine to read. However, these files are not easy for humans to read or write. The solution is a two-step configuration process that is friendly for both humans and machines:

  1. Produce a YAML-formatted Butane config.

  2. Run Butane to convert the YAML file into a JSON Ignition config.

During the transpilation process, Butane verifies the syntax of the YAML file, which can catch errors before you use it to launch the FCOS system.

Once you have an Ignition (.ign) file, you can use it to boot an FCOS system in a VM or install it on bare metal.

Try to plan your configuration with the full set of customization details before provisioning a Fedora CoreOS instance. But don’t worry if you forgot something as you can fix the configuration and re-deploy the instance from a fresh image.

Getting Butane

You can run Butane as a container with docker or podman or download it as a standalone binary.

Unless otherwise noted, new releases of Butane are backwards compatible with old releases.

Via a container with podman or docker

You can get Butane from a container hosted on quay.io:

podman pull quay.io/coreos/butane:release
The release tag tracks the most recent release, and the latest tag tracks the Git development branch.

Run Butane either by using standard input and standard output or by using files:

Example running Butane using standard input and standard output
podman run --interactive --rm quay.io/coreos/butane:release \
       --pretty --strict < your_config.bu > transpiled_config.ign
Example running Butane using a file as input and standard output
podman run --interactive --rm --security-opt label=disable \
       --volume "${PWD}:/pwd" --workdir /pwd quay.io/coreos/butane:release \
       --pretty --strict your_config.bu > transpiled_config.ign

To make it simpler to type, you may also add the following alias to your shell configuration:

alias butane='podman run --rm --interactive         \
              --security-opt label=disable          \
              --volume "${PWD}:/pwd" --workdir /pwd \
              quay.io/coreos/butane:release'
Those examples use podman, but you can use docker in a similar manner.

Installing via distribution packages

Installing on Fedora

Butane is available as a Fedora package:

sudo dnf install -y butane

Installing via Homebrew

Butane is available as a Homebrew package:

brew install butane

Installing via MacPorts

Butane is available as a MacPorts package:

sudo port install butane

Installing via Scoop

Butane is available as a Scoop package via the extras:

scoop bucket add extras
scoop install butane

Installing via Windows Package Manager Client (winget)

Butane is available as a winget package:

winget install --id Fedora.CoreOS.butane

Standalone binary

Linux

To use the Butane binary on Linux, follow these steps:

  1. If you have not already done so, download the Fedora signing keys and import them:

    curl https://fedoraproject.org/fedora.gpg | gpg --import

  2. Download the latest version of Butane and the detached signature from the releases page.

  3. Verify it with gpg:

    gpg --verify butane-x86_64-unknown-linux-gnu.asc

macOS

To use the Butane binary on macOS, follow these steps:

  1. If you have not already done so, download the Fedora signing keys and import them:

    curl https://fedoraproject.org/fedora.gpg | gpg --import

  2. Download the latest version of Butane and the detached signature from the releases page.

  3. Verify it with gpg:

    gpg --verify butane-x86_64-apple-darwin.asc

Windows

To use the Butane binary on Windows, follow these steps:

  1. If you have not already done so, download the Fedora signing keys and import them:

    Invoke-RestMethod -Uri https://fedoraproject.org/fedora.gpg | gpg --import

  2. Download the latest version of Butane and the detached signature from the releases page.

  3. Verify it with gpg:

    gpg --verify butane-x86_64-pc-windows-gnu.exe.asc

Example

Create a basic Ignition config that modifies the default Fedora CoreOS user core to allow this user to log in with an SSH key.

The overall steps are as follows:

  1. Write the Butane config in the YAML format.

  2. Use Butane to convert the Butane config into an Ignition (JSON) config.

  3. Boot a fresh Fedora CoreOS image with the resulting Ignition configuration.

Prerequisite

This example uses a pair of SSH public and private keys. If you don’t already have it, you can generate an SSH key pair.

The SSH public key will be provisioned to the Fedora CoreOS machine (via Ignition). The SSH private key needs to be available to your user on the local workstation, in order to remotely authenticate yourself over SSH.

Writing the Butane config

  1. Copy the following example into a text editor:

    variant: fcos
version: 1.6.0
passwd:
  users:
    - name: core
      ssh_authorized_keys:
        - ssh-rsa AAAA...

  2. Replace the above line starting with ssh-rsa with the contents of your SSH public key file.

  3. Save the file with the name example.bu.

YAML files must have consistent indentation. Although Butane checks for syntax errors, ensure that the indentation matches the above example. Overall, the Butane configs must conform to Butane’s configuration specification format.
If you use VScode with the Red Hat Yaml extension you can associate *.bu files to yaml in the files.associations setting and get help/auto completion.

Using Butane

  1. Run Butane on the Butane config:

    butane --pretty --strict example.bu > example.ign

  2. Use the example.ign file to boot Fedora CoreOS.

If using Butane on Windows, > example.ign will create an UTF-16 encoded Ignition file. This can prevent Fedora CoreOS from booting properly. Use --output example.ign instead.

Want to help? Learn how to contribute to Fedora Docs ›