Ignition and Butane — Declarative First-Boot for CoreOS

Ignition is the first-boot provisioning system for Fedora CoreOS and RHCOS (the OS RHEL CoreOS/OpenShift nodes run) — conceptually the same job as cloud-init (configure an already-installed image on its first boot: users, files, systemd units) but with an entirely separate, immutable-infrastructure-oriented format: Ignition itself consumes strict, versioned JSON, and Butane is the human-friendly YAML front end that compiles down to it.

Butane YAML → Ignition JSON¶

variant: fcos
version: 1.5.0
passwd:
  users:
    - name: admin
      groups: [wheel, sudo]
      ssh_authorized_keys:
        - ssh-ed25519 AAAA...
storage:
  files:
    - path: /etc/motd
      mode: 0644
      contents:
        inline: |
          Provisioned by Ignition
systemd:
  units:
    - name: chronyd.service
      enabled: true

# Install butane, then compile
podman run --rm -v $PWD:/pwd:z -w /pwd quay.io/coreos/butane:release --pretty --strict config.bu > config.ign
# or, if the butane binary is installed locally:
butane --pretty --strict config.bu > config.ign

--strict rejects unknown fields rather than silently ignoring a typo, which is worth always including — a silently-dropped field in a boot-critical config is a bad way to find out about a typo.

Delivering the Ignition file¶

Most platforms (bare metal via PXE, most clouds, libvirt) accept the Ignition file as a boot-time config source, analogous to a cloud-init NoCloud seed:

# coreos.inst.ignition_url= for the bare-metal installer, e.g. via PXE kernel args
coreos.inst.ignition_url=http://<server>/config.ign

# libvirt/QEMU via fw_cfg (no network dependency for the initial fetch)
qemu-system-x86_64 ... -fw_cfg name=opt/com.coreos/config,file=config.ign

Why not just use cloud-init¶

Fedora CoreOS/RHCOS is built around immutable, atomically-updated infrastructure (rpm-ostree rather than a traditional mutable package-managed filesystem), and Ignition's design matches that: it runs exactly once, very early in boot (before the root filesystem's normal init), rather than cloud-init's later, re-runnable, more mutable model. If you're standing up an OpenShift cluster or a Fedora CoreOS host, Ignition is the format the platform expects and cloud-init is not available/relevant; for a normal Ubuntu/RHEL/Debian VM or cloud instance, use cloud-init instead — the two are not interchangeable formats for the same OS.