Produciendo una configuración Ignition

Visión general de Ignition

Ignition es una utilidad de aprovisionamiento que lee un archivo de configuración (en formato JSON) y aprovisiona a un sistema basado en Fedora CoreOS sobre esta configuración. Los componentes configurables incluyen almacenamiento y sistemas de archivos, unidades systemd y usuarios.

Ignition corre sólo una vez durante el primera arranque del sistema (durante el initramfs). Como Ignition corre tan pronto en el proceso de arranque, puede reparticionar los discos, formatear sistemas de archivos, crear usuarios y escribir archivos antes de que el espacio de usuario empieza a arrancar. Como resultado, los servicios systemd están ya escritos en el disco cuando systemd se inicia, acelerando el tiempo de arranque.

Proceso de configuración

Las configuraciones Ignition están formateadas como JSON, los que es más rápido y fácil para que la máquina lo lea. Sin embargo, esto archivos no son fáciles para que los humanos los lean o escriban. La solución es un proceso de configuración en dos pasos que es amigable tanto para los humanos como para las máquinas:

  1. Produce una configuración Butane formateada YAML.

  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 simply 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://getfedora.org/static/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://getfedora.org/static/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://getfedora.org/static/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

A simple 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.4.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.

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.

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