Ignition configuration options

You can configure various system aspects by using Ignition configuration sections. Follow these guidelines to ensure correct configuration syntax and structure.

Configuration format

Ignition uses the JSON format for configurations. The standard workflow uses Butane (YAML) for human-readable authoring, then converts to Ignition JSON.

Converting Butane to Ignition

$ butane --strict config.bu > config.ign
Table 1. Ignition configuration sections
Section Purpose

ignition

Specifies the configuration version and optional remote configuration sources.

storage

Defines files, directories, links, disks, file systems, and RAID arrays.

passwd

Configures users and groups.

systemd

Manages systemd units (enable, disable, mask, or provide unit contents).

kernel_arguments

Modifies kernel command line parameters for subsequent boots.

Storage configuration

The storage section supports the following resources:

Table 2. Storage section resources
Resource Description Example use case

files

Create or overwrite files with specified contents, mode, and ownership.

Configuration files, scripts

directories

Create directories with specified mode and ownership.

Log directories, application data

links

Create symbolic or hard links.

Alternative paths, compatibility

disks

Partition disks by using GPT.

Data partitions

filesystems

Create and format file systems.

Additional storage volumes

raid

Configure software RAID arrays.

Redundant storage

File configuration example
  storage:
    files:
      - path: /etc/resolv.conf
        mode: 0644
        contents:
          inline: |
            ...
      - path: /etc/chrony.conf      # <-- same level as first entry
        mode: 0644
User configuration
passwd:
  users:
    - name: admin
      uid: 1001
      groups:
        - wheel
        - sudo
      ssh_authorized_keys:
        - ssh-rsa AAAAB3... admin@example.com
      password_hash: $6$rounds=4096$salt$hash...
    - name: appuser
      uid: 1002
      system: true
      no_create_home: true
Systemd unit configuration
systemd:
  units:
    - name: myapp.service
      enabled: true
      contents: |
        [Unit]
        Description=My Application
        After=network-online.target

        [Service]
        Type=simple
        ExecStart=/usr/bin/myapp
        Restart=always

        [Install]
        WantedBy=multi-user.target
    - name: debug-shell.service
      mask: true
Kernel arguments
kernel_arguments:
  should_exist:
    - systemd.unified_cgroup_hierarchy=1
    - mitigations=auto
  should_not_exist:
    - quiet
Multi-data-center configuration example

When managing systems across multiple data centers, create environment-specific configurations:

variant: r4e
version: 1.5.0
storage:
  files:
    - path: /etc/resolv.conf
      mode: 0644
      contents:
        inline: |
          nameserver 10.1.0.1
          nameserver 10.1.0.2
          search dc1.example.com example.com
      - path: /etc/chrony.conf
        mode: 0644
        contents:
          inline: |
            server ntp.dc1.example.com iburst prefer
            server ntp.example.com iburst
            driftfile /var/lib/chrony/drift
      - path: /etc/datacenter
        mode: 0644
        contents:
          inline: dc1
Configuration validation

You can validate Ignition configurations before deployment:

$ ignition-validate config.ign

Alternatively, you can use Butane’s strict mode during conversion:

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