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:
-
Produce a YAML-formatted Fedora CoreOS Configuration (FCC) file.
-
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:
fcct
using standard in and standard out:podman run --interactive --rm quay.io/coreos/fcct:release \
--pretty --strict < your_config.fcc > transpiled_config.ign
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. |
Standalone binary
To use the fcct
binary on Linux, follow these steps:
-
If you have not already done so, download the Fedora signing keys and import them:
curl https://getfedora.org/static/fedora.gpg | gpg --import
-
Download the latest version of
fcct
and the detached signature from the releases page. -
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:
-
Write the Fedora CoreOS Configuration (FCC) file in the YAML format.
-
Use the
fcct
to convert the FCC file into an Ignition (JSON) file. -
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
-
Copy the following example into a text editor:
variant: fcos version: 1.3.0 passwd: users: - name: core ssh_authorized_keys: - ssh-rsa AAAA...
-
Replace the above line starting with
ssh-rsa
with the contents of your SSH public key file. -
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
-
Run fcct on the FCC file:
fcct --pretty --strict < example.fcc > example.ign
-
Use the
example.ign
file to boot Fedora CoreOS.