Mastering Butane: Configuring Fedora CoreOS from YAML to Ignition the DevOps Way

Why is Fedora CoreOS Configuration So Confusing for Many?

If you’re used to “traditional” server installation—plugging in a USB, manual partitioning, and then SSHing in to edit /etc/fstab—Fedora CoreOS (FCOS) will come as a shock. This operating system has no graphical installer. It was born to serve containers and automation at a scale of hundreds or thousands of nodes.

The heart of FCOS is the Ignition file. This is a JSON file containing all the configuration “directives” from the very first boot. But believe me, never write JSON by hand. Just one extra comma or a missing curly bracket, and the server will hang during startup. That’s why Butane exists to save our sanity.

Butane and Ignition: An Inseparable Duo

To deploy smoothly, you need to clearly distinguish the roles of these two tools:

• Ignition: Runs in the very early initramfs stage. It reads JSON to partition, format disks, and create users. It runs exactly once during the first boot.
• Butane: Acts as a translator. It helps us write configurations in highly readable YAML (.bu files), which are then compiled into JSON that Ignition can understand.

Instead of struggling with 200 lines of messy JSON, you only need to manage a few dozen lines of clean YAML.

Installing Butane in 30 Seconds

On Fedora, installation is extremely simple via DNF:

sudo dnf install butane

If you’re using another distro, run Butane via Podman to keep your environment clean. This is how I usually do it to avoid cluttering the host machine:

podman run --rm -v .:/pwd -w /pwd quay.io/coreos/butane:release --strict config.bu > config.ign

Hands-on: Creating Your First Configuration File

Let’s try setting up an FCOS node with a devops user, an added SSH key, and Nginx running automatically via Podman. Create a config.bu file with the following content:

1. Declaring Basic Information

variant: fcos
version: 1.5.0
passwd:
  users:
    - name: devops
      ssh_authorized_keys:
        - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... user@machine
      groups: [sudo, wheel]

Note: variant and version are mandatory. If missing, Butane will throw an error immediately.

2. Automating Services with Systemd

FCOS doesn’t come with Nginx pre-installed like typical distros. We will instruct the system to pull the image and run the container as soon as it boots up:

systemd:
  units:
    - name: nginx-container.service
      enabled: true
      contents: |
        [Unit]
        Description=Run Nginx container using Podman
        After=network-online.target
        Wants=network-online.target

        [Service]
        ExecStartPre=-/usr/bin/podman kill nginx
        ExecStartPre=-/usr/bin/podman rm nginx
        ExecStartPre=/usr/bin/podman pull nginx:latest
        ExecStart=/usr/bin/podman run --name nginx -p 80:80 nginx:latest
        ExecStop=/usr/bin/podman stop nginx

        [Install]
        WantedBy=multi-user.target

3. Overwriting System Files

Need to change the hostname or create a welcome message (MOTD)? Butane handles this very efficiently:

storage:
  files:
    - path: /etc/hostname
      mode: 0644
      contents:
        inline: fcos-node-01
    - path: /etc/motd
      mode: 0644
      contents:
        inline: "Welcome to the FCOS node managed by Butane!\n"

Compiling to Ignition

Once the YAML file is ready, use the following command to export the JSON file. I always use the --strict flag for the most rigorous syntax checking:

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

This config.ign file is what you will provide in the “User Data” section when creating virtual machines on AWS, Proxmox, or VMware.

Hard-Won Tips for Real-World Deployment

Through several FCOS cluster deployment projects, I’ve gathered three golden rules:

• Forgetting the SSH Key is “suicide”: FCOS locks down user passwords by default. No key means you’re permanently locked out of the server. In that case, your only option is to delete the instance and start over.
• Be careful with whitespace: YAML is very sensitive to indentation. Use VS Code with a YAML extension to avoid silly mistakes that prevent Butane from compiling.
• Always test locally first: Don’t push straight to the Cloud and waste money. Use qemu or virt-install on your local machine to check if the Ignition file boots smoothly.

Conclusion

Butane is more than just a conversion tool. It is a bridge that brings Infrastructure as Code (IaC) thinking closer to home. Instead of memorizing dry JSON structures, we focus on defining the desired state of the server. If you’re diving into the world of Fedora CoreOS, consider mastering Butane a mandatory skill.