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 Fedora CoreOS Configuration (FCC) file.

  2. Run the Fedora CoreOS Configuration Transpiler (fcct) to convert the YAML file into a JSON Ignition file.

During the transpilation process, fcct 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 simply fix the configuration and re-deploy the instance from a fresh image.

Getting FCCT

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

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

Via a container with podman or docker

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

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

Run fcct either by using standard in and standard out or by using files:

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

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

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

Installing via Fedora packages

fcct is available as Fedora a package:

sudo dnf install -y fcct

Standalone binary

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

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

    curl https://getfedora.org/static/fedora.gpg | gpg --import

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

  3. Verify it with gpg:

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

A simple example

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

The overall steps are as follows:

  1. Write the Fedora CoreOS Configuration (FCC) file in the YAML format.

  2. Use the fcct to convert the FCC file into an Ignition (JSON) file.

  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 FCC file

  1. Copy the following example into a text editor:

    variant: fcos
version: 1.3.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.fcc.

YAML files must have consistent indentation. Although fcct checks for syntax errors, ensure that the indentation matches the above example. Overall, the FCC files must conform to fcct's configuration specification format.

Using FCCT

  1. Run fcct on the FCC file:

    fcct --pretty --strict < example.fcc > example.ign

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