// Module included in the following assemblies:
//
// * architecture/architecture-rhcos.adoc

:_mod-docs-content-type: CONCEPT
[id="rhcos-about-ignition_{context}"]
= Ignition

[role="_abstract"]
Automate {op-system} disk provisioning on first boot using Ignition. Learn how Ignition reads configuration files to automatically partition disks, format filesystems, write essential files, and create user accounts during initial setup.

On first boot, Ignition reads its configuration from the installation media or specified location. Ignition then applies the configuration.

Whether you are installing your cluster or adding machines to it, Ignition always performs the initial configuration of the {product-title} cluster machines. Most of the actual system setup happens on each machine itself. For each machine, Ignition takes the {op-system} image and boots the {op-system} kernel. Options on the kernel command line identify the type of deployment and the location of the Ignition-enabled initial RAM disk (initramfs).

To create machines by using Ignition, you need Ignition config files. The {product-title} installation program creates the Ignition config files that you need to deploy your cluster. These files are based on the information that you provide to the installation program directly or through an `install-config.yaml` file.

The way that Ignition configures machines is similar to how tools like `cloud-init` or Linux Anaconda Kickstart configure systems, but with the following important differences:

* Ignition runs from an initial RAM disk that is separate from the system you are installing to. Because of that, Ignition can repartition disks, set up file systems, and perform other changes to the machine's permanent file system. In contrast, cloud-init runs as part of the machine init system when the system boots. This makes foundational changes like disk partitioning more difficult. With cloud-init, difficulty exists to reconfigure the boot process while you are in the middle of the node boot process.

* Ignition is meant to initialize systems, not change existing systems. After a machine initializes and the kernel is running from the installed system, the Machine Config Operator from the {product-title} cluster completes all future machine configuration.

* Instead of completing a defined set of actions, Ignition implements a declarative configuration. Ignition checks that all partitions, files, services, and other items are in place before the new machine starts. Ignition then makes the changes, like copying files to disk that are necessary for the new machine to meet the specified configuration.

* After Ignition finishes configuring a machine, the kernel keeps running but discards the initial RAM disk and pivots to the installed system on disk. All of the new system services and other features start without requiring a system reboot.

* Because Ignition confirms that all new machines meet the declared configuration, you cannot have a partially configured machine. If a machine setup fails, the initialization process does not finish, and Ignition does not start the new machine. Your cluster never contain partially configured machines. If Ignition cannot complete, the machine is not added to the cluster. You must add a new machine instead. This behavior prevents the difficult case of debugging a machine when the results of a failed configuration task are not known until something that depended on it fails at a later date.

* If there is a problem with an Ignition config that causes the setup of a machine to fail, Ignition does not try to use the same config to set up another machine. For example, a failure could result from an Ignition config made up of a parent and child config that both want to create the same file. A failure in such a case would prevent that Ignition config from being used again to set up on other machines until the problem is resolved.

* If you have multiple Ignition config files, you get a union of that set of configs. Because Ignition is declarative, conflicts between the configs could cause Ignition to fail to set up the machine. The order of information in those files does not matter. Ignition sorts and implements each setting in ways that make the most sense. For example, if a file needs a directory several levels deep, if another file needs a directory along that path, the later file is created first. Ignition sorts and creates all files, directories, and links by depth.

* Ignition can start with an empty disk and set up bare-metal systems from scratch by using PXE boot. This is a capability that cloud-init cannot do. In the bare metal case, the Ignition config is injected into the boot partition so that Ignition can find it and configure the system correctly.

The Ignition process for an {op-system} machine in an {product-title} cluster involves the following steps:

* The machine gets its Ignition config file. Control plane machines get their Ignition config files from the bootstrap machine, and worker machines get Ignition config files from a control plane machine.
* Ignition creates disk partitions, file systems, directories, and links on the machine. It supports RAID arrays but does not support LVM volumes.
* Ignition mounts the root of the permanent file system to the `/sysroot` directory in the initramfs and starts working in that `/sysroot` directory.
* Ignition configures all defined file systems and sets them up to mount appropriately at runtime.
* Ignition runs systemd temporary files to populate required files in the `/var` directory.
* Ignition runs the Ignition config files to set up users, systemd unit files, and other configuration files.
* Ignition unmounts all components in the permanent system that were mounted in the initramfs.
* Ignition starts up the init process of the new machine, which in turn starts up all other services on the machine that run during system boot.

At the end of this process, the machine is ready to join the cluster and does not require a reboot.

////
After Ignition finishes its work on an individual machine, the kernel pivots to the installed system. The initial RAM disk is no longer used and the kernel goes on to run the init service to start up everything on the host from the installed disk. When the last machine under the bootstrap machine's control is completed, and the services on those machines come up, the work of the bootstrap machine is over.
////
