DOCSEARCHbyAlgolia
Submit Docs

Ignition Documentation

repository·main·Indexed 21 days ago

https://github.com/coreos/ignition

Ignition is a provisioning utility that automates disk manipulation, file creation, and user configuration during the initramfs stage of a system's first boot. It allows for partitioning disks, formatting filesystems, configuring RAID, managing users and groups, and writing files or systemd units based on a JSON configuration specification (supporting versions such as 3.0.0, 3.1.0, 3.2.0, and 3.3.0).

Tokens
24.2K
Snippets
49
Records
106
Agent score
73%

What's inside Ignition

  1. What is Ignition?

    main

    Ignition is a utility designed to manipulate disks during the initramfs stage of the boot process. It is used to automate the initial setup of a system by performing the following tasks:

    • Partitioning disks
    • Formatting partitions
    • Writing files (including regular files and systemd units)
    • Configuring users

    On the first boot, Ignition retrieves its configuration from a source of truth, such as a remote URL, a network metadata service, or a hypervisor bridge, and applies those settings to the system.

  2. Ignition Configuration v3.2.0 Specification Overview

    main

    An Ignition configuration is a JSON document that describes the desired state of a system. The top-level object must contain an ignition object.

    Key top-level components include:

    • ignition.version: The semantic version of the spec (e.g., 3.2.0).
    • ignition.config: Metadata and options for fetching and merging configurations.
    • ignition.storage: Definitions for disks, partitions, filesystems, files, directories, links, and LUKS devices.
    • ignition.systemd: Definitions for systemd units and drop-ins.
    • ignition.passwd: Definitions for users and groups.

  3. Understand the Ignition code structure

    main

    The Ignition codebase is split into two primary components:

    1. Frontend (/config): Handles configuration parsing and validation. This is a stable library API used by other programs. Because it is a stable API, changes to the frontend cannot be made without bumping the Ignition major version.
    2. Backend (/internal): Performs the actual configuration of the target system.

  4. Understand the Ignition provisioning model

    main

    Ignition is a provisioning utility designed for immutable infrastructure, not a configuration management tool. It operates based on the following principles:

    • First-boot only: Ignition runs only during the initial boot of a machine. To modify a machine, you should discard the old node and re-provision a new one rather than using configuration management to change running state.
    • Declarative state: Configs describe the desired state of the system (e.g., which files exist, which users exist) rather than a sequence of imperative steps or scripts.
    • Atomic provisioning: Ignition aims to produce exactly the machine specified in the config. If Ignition cannot fulfill a requirement (e.g., failing to fetch a remote file), it will prevent the machine from booting successfully to avoid an inconsistent state.
    • Distro-independence: Ignition provides low-level primitives (filesystems, partitions, files) that work across different Linux distributions, but it does not handle distro-specific tasks like package management.

  5. Configure LUKS devices with Ignition

    main

    Ignition supports creating LUKS2 devices using either key-files or Tang/TPM2 (via Clevis).

    • Key-file based: If no key-file is specified, Ignition generates one and stores it at /etc/luks/<deviceName> (this path is configurable via build flags).
    • Clevis/Tang/TPM2: For clevis-based devices, Ignition uses an SSS Pin and generates the required configuration JSON from provided attributes.
    • OS Integration: Ignition automatically generates entries in /etc/crypttab. The host operating system must have the necessary hooks (e.g., systemd-cryptsetup-generator) to unlock the devices.

  6. How Ignition config merging works

    main

    Ignition supports fetching and merging multiple configurations. This mechanism replaces the append functionality from Ignition 2.x.0. The merging process follows these rules:

    • Precedence: When merging a child config with a parent, the child's values override the parent's values. If a field is missing in the child, the parent's value is used.
    • List Deduplication: Most lists of objects are deduplicated based on a unique identifier field. If a child entry matches a parent entry, they are merged. The primary exception is lists specifying command arguments (e.g., mkfs or mdadm), which are simply appended.
    • Filesystem Deduplication: Files, directories, and links are deduplicated across each other. A child config can replace a parent's link with a file, or a directory with a file.
    • Traversal Order: Merging occurs via a depth-first traversal. If a config has multiple children, they are merged in the order they appear.
    • HTTP Header Merging:
      • If names match, the child's header value replaces the parent's.
      • If a child header has no value, the parent header with that name is removed.

  7. Understand Ignition execution stages

    main

    Ignition execution is divided into discrete stages to allow the OS to perform tasks (like networking or mounting) between provisioning steps:

    1. fetch-offline: Initial stage.
    2. (OS enables networking if required)
    3. fetch: Fetches the configuration.
    4. (OS examines config and may copy root filesystem to RAM)
    5. disks: Configures disks.
    6. (OS mounts root filesystem)
    7. mount: Preprocesses configured filesystems.
    8. files: Provisions files.
    9. (OS performs postprocessing)
    10. umount: Unmounts filesystems.

  8. Configure filesystem reuse and wiping

    main

    When specifying a filesystem for a device, Ignition's behavior depends on the existing state and the wipeFilesystem flag in the filesystem section.

    • No existing filesystem: Ignition always creates the desired filesystem.
    • wipeFilesystem: true: Ignition wipes any preexisting filesystem and creates the desired one (or skips if format is none). Data loss will occur.
    • wipeFilesystem: false: Ignition attempts to reuse the existing filesystem. It succeeds only if the filesystem matches the specified type, label, and UUID. If the type is incorrect, Ignition fails and the machine fails to boot. If the format is set to none, any preexisting filesystem causes failure.

  9. How HTTP backoff and retry works in Ignition

    main

    When Ignition fetches a resource over http(s), it uses an exponential backoff strategy if the resource is unavailable.

    • Timeout: Ignition waits 10 seconds for response headers. If headers are not received or an HTTP 5XX error occurs, the request is cancelled and retried.
    • Success/Failure: Any HTTP response code less than 500 is considered a completed request. If the code is < 500 but the resource cannot be fetched, Ignition fails.
    • Backoff Timing: Initial wait is 100 milliseconds. The wait time doubles with each failure, capping at a maximum of 5 seconds between attempts.

  10. Understand Ignition testing frameworks

    main

    Ignition utilizes three distinct testing tiers depending on the scope of the validation:

    1. Unit tests (./test): Validate functionality that only affects internal program state.
    2. Blackbox tests: Validate config directives that affect the target disk (requires host system disk utilities).
    3. Kola tests: Validate functionality that interacts with platforms (e.g., config fetching) or the rest of the OS. These may be internal to coreos-assembler or external to fedora-coreos-config.

  11. How Ignition works and provides configuration

    main

    Ignition is a low-level system configuration utility that runs during the initial boot process from the initramfs. It applies changes defined in a JSON configuration file to the machine before the root filesystem is pivoted to via switch_root.

    Key Concepts

    • Configuration Format: Ignition uses a JSON configuration file. The version number in the JSON must match the version of the Ignition executable being used; a mismatch will cause Ignition to fail and prevent the machine from booting.
    • Data Sources: Ignition looks for configuration in platform-specific locations. This behavior can be overridden by providing a configuration URL via kernel command-line options.
    • Config Merging: On some Linux distributions, a base configuration (e.g., defining a default user) may be provided. This base config is merged with the user-provided configuration before application.

  12. Understand the Ignition Boot Flow

    main

    Ignition follows a specific lifecycle during boot to fetch, process, and apply configurations. The flow depends on whether the system is performing a 'firstboot' or a 'subsequent' boot.

    1. Firstboot Detection

    • GRUB Stage: The bootloader checks for the existence of /ignition.firstboot on the boot filesystem. If present, it appends ignition.firstboot (and optionally ignition_network_kcmdline) to the kernel command line.
    • Generator Stage: The ignition-generator reads /proc/cmdline. If ignition.firstboot is detected, the firstboot path is triggered; otherwise, the system proceeds to a subsequent boot where Ignition services do not run.

    2. Configuration Fetching

    Ignition attempts to locate a configuration file (/run/ignition.json) using the following priority:

    1. Kernel Command Line: Config provided directly via arguments.
    2. Local File: The existence of /usr/lib/ignition/user.ign.
    3. Platform Provider: Fetching from the cloud/platform provider (e.g., Azure IMDS).

    If the configuration requires network resources, ignition-fetch.service will wait for the network to be available before attempting to fetch.

    3. Application Lifecycle

    Once a configuration is found and written to /run/ignition.json, the following services execute in order:

    1. ignition-kargs.service: Processes kernel arguments. If changes are detected, the system reboots to apply them.
    2. ignition-disks.service: Manages disk partitioning and formatting.
    3. ignition-mount.service: Mounts filesystems.
    4. ignition-files.service: Merges the configuration with base configs and applies files/units.

    4. Completion

    After ignition-complete.target is reached, the system pivots to the real root. If it was a firstboot, ignition-delete-config.service may run to clean up the configuration to prevent re-application on subsequent boots.