Installing Red Hat Enterprise Linux 10 from a bootc image with bootc

Interested in a modern way to manage Red Hat Enterprise Linux (RHEL)? Image mode is a deployment option that allows the operating system to be built, deployed, and updated like a container image. A key reason to deploy from a bootc image is its enhanced consistency and reliable, atomic updates and rollbacks. With RHEL 10, you can install that image from the network using the same installer you already use for traditional RHEL deployments: Anaconda. A new kickstart command, bootc, directs Anaconda to install the system directly from a bootc image rather than from RPM packages or other supported payloads. This immutable system can be updated later using bootc upgrade or bootc switch. Here's a look at how it works, and how to try it for yourself.

Note: The bootc kickstart command is currently available as a Technology Preview in Red Hat Enterprise Linux 10.2.

What the bootc command does

From a user perspective, the bootc command achieves the same result as the older ostreecontainer command: Installing an immutable system from a container image. However, the underlying implementation differs. When you use the bootc command in kickstart, Anaconda continues to handle the core tasks: storage configuration (partitioning, filesystems) and the final steps of the installation setup. The bootc tool handles the actual deployment of operating system content and the bootloader setup. Previously, with ostreecontainer Anaconda relied on the ostree tool for the image and a separate tool for the bootloader configuration.

Anaconda first creates the storage layout you requested, then invokes the equivalent of bootc install to-filesystem command to populate the root filesystem from the container image and configure the bootloader. Once this step is complete, Anaconda continues with the final configuration steps — including user accounts, root password, SSH keys, and other kickstart options you specified — ensuring the installed system is fully set up before the first boot.

Using the bootc kickstart command

To install a properly configured system that will receive updates, currently you must specify both the container image to install from, and the target image reference. The source image reference must be specified with a registry: prefix, whereas that prefix must NOT be present in the target image reference. This is a difference to the ostreecontainer command, and we aim to address it in the future RHEL releases.

bootc --source-imgref SOURCEIMGREF [--stateroot STATEROOT] [--target-imgref TARGETIMGREF]

• --source-imgref: Required. The image reference (for example, registry:registry.redhat.io/rhel10/rhel-bootc:10.2) to install from.
• --stateroot: Optional. Name for the state directory.
• --target-imgref: Image reference used for future updates. Specifying both --source-imgref and --target-imgref is necessary for the container registry access to work properly in the installed system.

You can combine bootc with typical kickstart commands, such as autopart, clearpart, reqpart, part, network, rootpw, user, timezone, %pre or %post. It cannot be used with installation methods that define the installation method or source (like %packages, ostreesetup, ostreecontainer, liveimg, cdrom, url, repo). For further reference about what kickstart commands are supported, see the Installing RHEL from a bootable container image by using the bootc Kickstart command knowledge base article.

Example: Minimal kickstart file

The following minimal kickstart file deploys the system from a base bootc image present in the Red Hat registry. In practice, you should build a custom image for your specific needs, because there is little reason to install a base image directly. The URLs here serve primarily to illustrate correct registry syntax and authentication. For more information on building custom bootc images, refer to the Best practices for building bootable containers article.

The following example requires a Red Hat account to access the container registry. To try this functionality without an account, you can achieve a similar outcome with a CentOS Stream 10 installation medium in conjunction with a CentOS Stream 10 bootc image (stream10). To use this alternative, modify the example kickstart file by pointing the bootc command to the CentOS Stream image and removing the %pre and %post script sections that handle authentication.

# WARNING: This kickstart file clears and repartitions all storage devices
# accessible to the machine. Use it only in test or isolated environments
# or adjust the storage section accordingly.
# Don't leave the resulting kickstart file unattended, as it contains
# secrets in plaintext.

zerombr
clearpart --all --initlabel
autopart

lang en_US.UTF-8
keyboard us
timezone America/New_York --utc
rootpw changeme

bootc --source-imgref=registry:registry.redhat.io/rhel10/rhel-bootc:10.2 --target-imgref=registry.redhat.io/rhel10/rhel-bootc:10.2
# The following %pre and %post script sections are necessary when
# accessing authenticated registries - the %pre script handles
# authentication during the installation, the %post script handles
# authentication in the installed system.

%pre
mkdir -p /etc/ostree
cat > /etc/ostree/auth.json << 'EOF'
{
  "auths": {
    "registry.redhat.io": {
      "auth": "<your-pull-secret>"
    }
  }
}
EOF
%end

%post
mkdir -p /etc/ostree
cat > /etc/ostree/auth.json << 'EOF'
{
  "auths": {
    "registry.redhat.io": {
      "auth": "<your-pull-secret>"
    }
  }
}
EOF
%end

To start the installation, make the kickstart file available over HTTP, use the RHEL-10.2 or newer boot ISO, point the installer at your kickstart file on the kernel command line:

inst.ks=http://server.example.com/path/to/kickstart.ks

Alternatively, you can use the mkksiso tool from the lorax package to embed the file into the installation ISO.

For more information on using authenticated container registries, refer to Accessing private registries with pull secrets on Anaconda installations. To learn how to access Red Hat container registries that provide base bootc-based images, see Red Hat Container Registry Authentication.

What to keep in mind

A few limitations are worth noting before deployment:

• Image reference format: Both the --source-imgref and --target-imgref options are currently required, and their usage requires a specific format: the registry: prefix must be present for the source image reference but excluded from the target image reference.
• Storage configuration: Multi-disk partitioning and arbitrary custom mount points are not supported; stick to single-disk layouts and the layouts you get from autopart or the usual part/reqpart options.
• Installation media compatibility: Use RHEL 10.2 or newer installation medium when installing a RHEL-10 container image. Using media from another product or variant (CentOS Stream, Fedora) to install a RHEL-10 image can lead to product-specific defaults (for example, filesystem type) that don't match the image you're installing.
• User account requirements: Either set a root password with the rootpw kickstart command or define an administrator user, so that the installation can proceed.

As the feature evolves, there should be less limitations, and we expect to add more capabilities.

Where to go from here

This is just the beginning, and there's a lot more to explore. Here's where to go next:

• For the full picture of image mode — building, deploying, and managing RHEL as a container image — see Using image mode for RHEL to build, deploy, and manage operating systems.
• For kickstart syntax details, see the Pykickstart documentation for the bootc command.
• For more details about the bootc command, see the Installing RHEL from a bootable container image by using the bootc Kickstart command knowledge base article.

If you try out the bootc kickstart command in RHEL 10, we encourage you to share feedback on how it fits your workflows and what you would like to see next through your usual Red Hat channels.