Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 4. Creating bootc compatible base disk images with bootc-image-builder

The bootc-image-builder, available as a Technology Preview, is a containerized tool to create disk images from bootc images. You can use the images that you build to deploy disk images in different environments, such as the edge, server, and clouds.

By using the bootc-image-builder tool, you can convert bootc images into disk images for a variety of different platforms and formats. Converting bootc images into disk images is equivalent to installing a bootc. After you deploy these disk images to the target environment, you can update them directly from the container registry.

Note

Building base disk images which come from private registries by using bootc-image-builder is not supported in this release. Building base disk images which come from private registries by using bootc-image-builder is not supported in this release. The bootc-image-builder tool is intended to create images from Red Hat official registry.redhat.io repository, to ensure compliance with the Red Hat Enterprise Linux End User License Agreement (EULA).

While you cannot directly use bootc-image-builder with private registries, you can still build your base images by using one of the following methods:

  • Use a local RHEL system, installing the Podman tool, and building your image locally. Then, you can push the images to your private registry.
  • Use a CI/CD pipeline: Create a CI/CD pipeline that uses a RHEL based system to build images and push them to your private registry.

The bootc-image-builder tool supports generating the following image types:

  • Disk image formats, such as ISO, suitable for disconnected installations.

  • Virtual disk images formats, such as:

    • QEMU copy-on-write (QCOW2)
    • Amazon Machine Image (AMI)
    • Unformatted raw disk (Raw)
    • Virtual Machine Image (VMI)

Deploying from a container image is beneficial when you run VMs or servers because you can achieve the same installation result. That consistency extends across multiple different image types and platforms when you build them from the same container image. Consequently, you can minimize the effort in maintaining operating system images across platforms. You can also update systems that you deploy from these disk images by using the bootc tool, instead of re-creating and uploading new disk images with bootc-image-builder.

Note

Generic base container images do not include any default passwords or SSH keys. Also, the disk images that you create by using the bootc-image-builder tool do not contain the tools that are available in common disk images, such as cloud-init. These disk images are transformed container images only.

Although you can deploy a rhel-10-bootc image directly, you can also create your own customized images that are derived from this bootc image. The bootc-image-builder tool takes the rhel-10-bootc OCI container image as an input.

4.2. Installing bootc-image-builder
Copy link

The bootc-image-builder is intended to be used as a container and it is not available as an RPM package in RHEL. To access it, follow the procedure.

Prerequisites

  • The container-tools meta-package is installed. The meta-package contains all container tools, such as Podman, Buildah, and Skopeo.
  • You are authenticated to registry.redhat.io. For details, see Red Hat Container Registry Authentication.

Procedure

  1. Login to authenticate to registry.redhat.io: 

    $ sudo podman login registry.redhat.io
    Copy to Clipboard Toggle word wrap

  2. Install the bootc-image-builder tool: 

    $ sudo podman pull registry.redhat.io/rhel9/bootc-image-builder
    Copy to Clipboard Toggle word wrap

Verification

  • List all images pulled to your local system: 

    $ sudo podman images
REPOSITORY                                    TAG         IMAGE ID      CREATED       SIZE
registry.redhat.io/rhel9/bootc-image-builder  latest      b361f3e845ea  24 hours ago  676 MB
    Copy to Clipboard Toggle word wrap

You can use a build configuration file in the TOML or JSON format to add customizations for your resulting disk image.

The container directory maps the config file to /config.toml. The customizations object defines the image modifications. Additionally, you can embed a build configuration file, either as config.json or config.toml in the /usr/lib/bootc-image-builder directory. The system automatically uses any file system or disk customizations found in this directory by default. This behavior can be overridden if you explicitly specify a different customization.

For the JSON format, you can also pass the configuration by using stdin when you use the --config argument.

User customization

Add a user to your disk image, and optionally set an SSH key. All fields for this section are optional except for the name.

Expand
TOMLJSON
[[customizations.user]]
name = "user"
password = "password"
key = "ssh-rsa AAA ... user@email.com"
groups = ["wheel"]
Copy to Clipboard Toggle word wrap 
{
  "customizations": {
    "user": [
      {
        "name": "user",
        "password": "password",
        "key": "ssh-rsa AAA ... user@email.com",
        "groups": [
          "wheel",
          "admins"
        ]
      }
    ]
  }
}
Copy to Clipboard Toggle word wrap
Kernel configuration

You can customize the kernel boot parameters in the configuration file.

Expand
TOMLJSON
[customizations.kernel]
name = "kernel-debug"
append = "nosmt=force"
Copy to Clipboard Toggle word wrap 
{
  "customizations": {
    "kernel": {
      "append": "mitigations=auto,nosmt"
    }
  }
}
Copy to Clipboard Toggle word wrap
File systems configuration

You can use the file system section of the customizations to set the minimum size of the base partitions, such as / and /boot, and to create extra partitions with mount points under /var.

Expand
TOMLJSON
[[customizations.filesystem]]
mountpoint = "/"
minsize = "10 GiB"

[[customizations.filesystem]]
mountpoint = "/var/data"
minsize = "20 GiB"
Copy to Clipboard Toggle word wrap 
{
  "customizations": {
    "filesystem": [
      {
        "mountpoint": "/",
        "minsize": "10 GiB"
      },
      {
        "mountpoint": "/var/data",
        "minsize": "20 GiB"
      }
    ]
  }
}
Copy to Clipboard Toggle word wrap
File system type interaction with rootfs

The root file system type (--rootfs) argument overrides the default value from the source container. It also sets the file system types for all additional mount points for the ext4, xfs, and btrfs types.

For supported mount points and sizes, the following restrictions and rules apply, unless the rootfs is btrfs:

  • You can specify / to set the minimum size of the root file system. The final size of the file system, mounted at /sysroot on a booted system, equals the value you specify in this configuration or 2x the size of the base container, whichever is larger.
  • You can specify /boot to set the minimum size of the boot partition. You can also specify subdirectories of /var, but you cannot specify symlinks in /var. For example, /var/home and /var/run are symlinks and cannot be file systems on their own.
  • /var itself cannot be a mount point. The rootfs option defines the file system type for the root file system.
  • Currently, there is no support for creating btrfs subvolumes during build time. Therefore, if the rootfs is btrfs, no custom mount points are supported under /var. You can only configure / and /boot.
Anaconda ISO (installer) configuration options

Create a Kickstart file that contains the installation commands of your choice. Then, add a Kickstart file to your ISO build to create a fully customized and automated installation medium.

Note

The following combined customizations are not supported: [customizations.user] and [customizations.installer.kickstart]. When you add a Kickstart, use a configuration file in the TOML format, because multi-line strings are prone to error.

Expand
TOMLJSON
[customizations.installer.kickstart]
contents = """
text --non-interactive
zerombr
clearpart --all --initlabel --disklabel=gpt
autopart --noswap --type=lvm
network --bootproto=dhcp --device=link --activate --onboot=on
"""
Copy to Clipboard Toggle word wrap 
{
  "customizations": {
    "installer": {
      "kickstart": {
        "contents": "text --non-interactive\nzerombr\nclearpart --all --initlabel --disklabel=gpt\nautopart --noswap --type=lvm\nnetwork --bootproto=dhcp --device=link --activate --onboot=on"
      }
    }
  }
}
Copy to Clipboard Toggle word wrap
Warning

bootc-image-builder does not add additional Kickstart commands besides the container image, which the system adds automatically to the container image. See Creating Kickstart files for more information.

Build a RHEL bootc image into a QEMU (QCOW2) image for the architecture that you are running the commands on.

The RHEL base image does not include a default user. Optionally, you can inject a user configuration by using the --config option to run the bootc-image-builder container. Alternatively, you can configure the base image with cloud-init to inject users and SSH keys on first boot. See Users and groups configuration - Injecting users and SSH keys by using cloud-init. .Prerequisites

  • You have Podman installed on your host machine.
  • You have virt-install installed on your host machine.
  • You have root access to run the bootc-image-builder tool, and run the containers in --privileged mode, to build the images.

Procedure

  1. Optional: Create a config.toml to configure user access, for example: 

    [[customizations.user]]
name = "user"
password = "pass"
key = "ssh-rsa AAA ... user@email.com"
groups = ["wheel"]
    Copy to Clipboard Toggle word wrap

  2. Run bootc-image-builder. Optionally, if you want to use user access configuration, pass the config.toml as an argument.

    Note

    If you do not have the container storage mount and --local image options, your image must be public.

    1. The following is an example of creating a public QCOW2 image:

    2. The following example creates a public QCOW2 image. The image must be accessible from a registry, such as registry.redhat.io/rhel10/bootc-image-builder:latest. 

      $ sudo podman run \
    --rm \
    --privileged \
    --pull=newer \
    --security-opt label=type:unconfined_t \
    -v ./config.toml:/config.toml:ro \
    -v ./output:/output \
    -v /var/lib/containers/storage:/var/lib/containers/storage \
    registry.redhat.io/rhel10/bootc-image-builder:latest \
    --type qcow2 \
    --config /config.toml \
  quay.io/<namespace>/<image>:<tag>
      Copy to Clipboard Toggle word wrap
    3. The following is an example of creating a private QCOW2 image:

    4. This example creates a private QCOW2 image from a local container. 

      $ sudo podman run \
    --rm \
    -it \
    --privileged \
    --pull=newer \
    --security-opt label=type:unconfined_t \
    -v ./config.toml:/config.toml:ro \
    -v ./output:/output \
    -v /var/lib/containers/storage:/var/lib/containers/storage \
    registry.redhat.io/rhel10/bootc-image-builder:latest \
    --type qcow2 \
    --config /config.toml \
    quay.io/<namespace>/<image>:<tag>
      Copy to Clipboard Toggle word wrap

      You can find the .qcow2 image in the output folder.

Create a Virtual Machine Disk (VMDK) from a bootc image and use it within VMware’s virtualization platforms, such as vSphere, or use in Oracle VirtualBox.

Prerequisites

  • You have Podman installed on your host machine.
  • You have authenticated to the Red Hat Registry by using the podman login registry.redhat.io.
  • You have pulled the rhel10/bootc-image-builder container image.

Procedure

  1. Create a Containerfile with the following content: 

    FROM registry.redhat.io/rhel10/rhel-bootc:latest
RUN dnf -y install cloud-init open-vm-tools && \
ln -s ../cloud-init.target /usr/lib/systemd/system/default.target.wants && \
rm -rf /var/{cache,log} /var/lib/{dnf,rhsm} && \
systemctl enable vmtoolsd.service
    Copy to Clipboard Toggle word wrap

  2. Build the bootc image: 

    # podman build . -t localhost/rhel-bootc-vmdk
    Copy to Clipboard Toggle word wrap
  3. Create a VMDK file from the previously created bootc image:

  4. Create a VMDK file from the previously created bootc image. The image must be accessible from a registry, such as registry.redhat.io/rhel10/bootc-image-builder:latest. 

    # podman run \
--rm \
-it \
--privileged \
-v /var/lib/containers/storage:/var/lib/containers/storage \
-v ./output:/output \
--security-opt label=type:unconfined_t \
--pull newer \
registry.redhat.io/rhel10/bootc-image-builder:latest \
--local \
--type vmdk \
--config /config.toml \
localhost/rhel-bootc-vmdk:latest
    Copy to Clipboard Toggle word wrap

    The --local option uses the local container storage to source the originating image to produce the VMDK instead of a remote repository.

A VMDK disk file for the bootc image is stored in the output/vmdk directory.

Build a RHEL bootc image into a GCE image for the architecture that you are running the commands on. The RHEL base image does not include a default user. Optionally, you can inject a user configuration by using the --config option to run the bootc-image-builder container. Alternatively, you can configure the base image with cloud-init to inject users and SSH keys on first boot. See Users and groups configuration - Injecting users and SSH keys by using cloud-init.

Prerequisites

  • You have Podman installed on your host machine.
  • You have root access to run the bootc-image-builder tool, and run the containers in --privileged mode, to build the images.

Procedure

  1. Optional: Create a config.toml to configure user access, for example: 

    [[customizations.user]]
name = "user"
password = "pass"
key = "ssh-rsa AAA ... user@email.com"
groups = ["wheel"]
    Copy to Clipboard Toggle word wrap

  2. Run bootc-image-builder. Optionally, if you want to use user access configuration, pass the config.toml as an argument.

    Note

    If you do not have the container storage mount and --local image options, your image must be public.

  3. Run bootc-image-builder. Optionally, if you want to use user access configuration, pass the config.toml as an argument. The image must be accessible from a registry, such as registry.redhat.io/rhel10/bootc-image-builder:latest.

    1. The following is an example of creating a gce image: 

      $ sudo podman run \
    --rm \
    -it \
    --privileged \
    --pull=newer \
    --security-opt label=type:unconfined_t \
    -v ./config.toml:/config.toml \
    -v ./output:/output \
    -v /var/lib/containers/storage:/var/lib/containers/storage \
    registry.redhat.io/rhel10/bootc-image-builder:latest \
    --type gce \
    --config /config.toml \
  quay.io/<namespace>/<image>:<tag>
      Copy to Clipboard Toggle word wrap

      You can find the gce image in the output folder.

Create an Amazon Machine Image (AMI) from a bootc image and use it to launch an Amazon Web Services (AWS) Amazon Elastic Compute Cloud (EC2) instance.

Prerequisites

  • You have Podman installed on your host machine.
  • You have an existing AWS S3 bucket within your AWS account.
  • You have root access to run the bootc-image-builder tool, and run the containers in --privileged mode, to build the images.
  • You have the vmimport service role configured on your account to import an AMI into your AWS account.

Procedure

  1. Create a disk image from the bootc image.

    • Configure the user details in the Containerfile. Make sure that you assign it with sudo access.
    • Build a customized operating system image with the configured user from the Containerfile. It creates a default user with passwordless sudo access.

  2. Optional: Configure the machine image with cloud-init. See Users and groups configuration - Injecting users and SSH keys by using cloud-init. The following is an example: 

    FROM registry.redhat.io/rhel10/rhel-bootc:latest

RUN dnf -y install cloud-init && \
    ln -s ../cloud-init.target /usr/lib/systemd/system/default.target.wants && \
    rm -rf /var/{cache,log} /var/lib/{dnf,rhsm}
    Copy to Clipboard Toggle word wrap
    Note

    You can also use cloud-init to add users and additional configuration by using instance metadata.

  3. Build the bootc image. For example, to deploy the image to an x86_64 AWS machine, use the following commands: 

    $ podman build -t quay.io/<namespace>/<image>:<tag> .
$ podman push quay.io/<namespace>/<image>:<tag> .
    Copy to Clipboard Toggle word wrap
  4. Use the bootc-image-builder tool to create an AMI from the bootc container image.

  5. Use the bootc-image-builder tool to create a public AMI image from the bootc container image. The image must be accessible from a registry, such as registry.redhat.io/rhel10/bootc-image-builder:latest. 

    $ sudo podman run \
  --rm \
  -it \
  --privileged \
  --pull=newer \
  -v $HOME/.aws:/root/.aws:ro \
  -v /var/lib/containers/storage:/var/lib/containers/storage \
  --env AWS_PROFILE=default \
  registry.redhat.io/rhel10/bootc-image-builder:latest \
  --type ami \
  --config /config.toml \
  --aws-ami-name rhel-bootc-x86 \
  --aws-bucket rhel-bootc-bucket \
  --aws-region us-east-1 \
quay.io/<namespace>/<image>:<tag>
    Copy to Clipboard Toggle word wrap
    Note

    The following flags must be specified all together. If you do not specify any flag, the AMI is exported to your output directory.

    • --aws-ami-name - The name of the AMI image in AWS
    • --aws-bucket - The target S3 bucket name for intermediate storage when you are creating the AMI

    • --aws-region - The target region for AWS uploads

      The bootc-image-builder tool builds an AMI image and uploads it to your AWS s3 bucket by using your AWS credentials to push and register an AMI image after building it. The bootc-image-builder tool builds an AMI image and uploads it to your AWS S3 bucket by using your AWS credentials to push and register an AMI image after building it.

Next steps

For more details on users, groups, SSH keys, and secrets, see Managing users, groups, SSH keys, and secrets in image mode for RHEL. For more details on users, groups, SSH keys, and secrets, see Managing users, groups, SSH keys, and secrets in image mode for RHEL.

Additional resources

You can convert a bootc image to a raw image with an MBR or GPT partition table by using bootc-image-builder.

The RHEL base image does not include a default user, so optionally, you can inject a user configuration by using the --config option to run the bootc-image-builder container. Alternatively, you can configure the base image with cloud-init to inject users and SSH keys on first boot. See Users and groups configuration - Injecting users and SSH keys by using cloud-init.

Prerequisites

  • You have Podman installed on your host machine.
  • You have root access to run the bootc-image-builder tool, and run the containers in --privileged mode, to build the images.
  • You have pulled your target container image in the container storage.

Procedure

  1. Optional: Create a config.toml to configure user access, for example: 

    [[customizations.user]]
name = "user"
password = "pass"
key = "ssh-rsa AAA ... user@email.com"
groups = ["wheel"]
    Copy to Clipboard Toggle word wrap
  2. Run bootc-image-builder. If you want to use user access configuration, pass the config.toml as an argument:

  3. Run bootc-image-builder. If you want to use user access configuration, pass the config.toml as an argument. The image must be accessible from a registry, such as registry.redhat.io/rhel10/bootc-image-builder:latest. 

    $ sudo podman run \
    --rm \
    -it \
    --privileged \
    --pull=newer \
    --security-opt label=type:unconfined_t \
    -v /var/lib/containers/storage:/var/lib/containers/storage \
    -v ./config.toml:/config.toml \
    -v ./output:/output \
    registry.redhat.io/rhel10/bootc-image-builder:latest \
    --local \
    --type raw \
    --config /config.toml \
  quay.io/<namespace>/<image>:<tag>
    Copy to Clipboard Toggle word wrap

    You can find the .raw image in the output folder.

You can use bootc-image-builder to create an ISO image from which you can perform an offline deployment of a bootable container.

Prerequisites

  • You have Podman installed on your host machine.
  • Your host system is subscribed or you have injected repository configuration by using bind mounts to ensure the image build process can fetch RPMs.
  • You have root access to run the bootc-image-builder tool, and run the containers in --privileged mode, to build the images.

Procedure

  1. Optional: Create a config.toml to which overrides the default embedded Kickstart which performs an automatic installation. 

    [customizations.installer.kickstart]
contents = """
text --non-interactive
zerombr
clearpart --all --initlabel --disklabel=gpt
autopart --noswap --type=lvm
network --bootproto=dhcp --device=link --activate --onboot=on
"""
    Copy to Clipboard Toggle word wrap
  2. Run bootc-image-builder. If you do not want to add any configuration, omit the -v $(pwd)/config.toml:/config.toml argument.

  3. Run bootc-image-builder to create a public ISO image. If you do not want to add any configuration, omit the -v $(pwd)/config.toml:/config.toml argument. The image must be accessible from a registry, such as registry.redhat.io/rhel10/bootc-image-builder:latest. 

    $ sudo podman run \
    --rm \
    -it \
    --privileged \
    --pull=newer \
    --security-opt label=type:unconfined_t \
    -v /var/lib/containers/storage:/var/lib/containers/storage \
    -v $(pwd)/config.toml:/config.toml \
    -v $(pwd)/output:/output \
    registry.redhat.io/rhel10/bootc-image-builder:latest \
    --type iso \
    --config /config.toml \
  quay.io/<namespace>/<image>:<tag>
    Copy to Clipboard Toggle word wrap

    You can find the .iso image in the output folder.

Next steps

  • You can use the ISO image on unattended installation methods, such as USB sticks or Install-on-boot. The installable boot ISO contains a configured Kickstart file. See Deploying a container image by using Anaconda and Kickstart.

    Warning

    Booting the ISO on a machine with an existing operating system or data can be destructive, because the Kickstart is configured to automatically reformat the first disk on the system.

  • You can make updates to the image and push the changes to a registry. See Managing RHEL bootable images.

You can use a Kickstart file to configure various parts of the installation process, such as setting up users, customizing partitioning, and adding an SSH key. You can include the Kickstart file in an ISO build to configure any part of the installation process, except the deployment of the base image. For ISOs with bootc container base images, you can use a Kickstart file to configure anything except the ostreecontainer command.

For example, you can use a Kickstart to perform either a partial installation, a full installation, or even omit the user creation. Use bootc-image-builder to build an ISO image that contains the custom Kickstart to configure your installation process.

Prerequisites

  • You have Podman installed on your host machine.
  • You have root access to run the bootc-image-builder tool, and run the containers in --privileged mode, to build the images.

Procedure

  1. Create your Kickstart file. The following Kickstart file is an example of a fully unattended Kickstart file configuration that contains user creation, and partition instructions. 

    [customizations.installer.kickstart]
contents = """
lang en_GB.UTF-8
keyboard uk
timezone CET

user --name <user> --password <password> --plaintext --groups <groups>
sshkey --username <user> ssh-<type> <public key>
rootpw --lock

zerombr
clearpart --all --initlabel
autopart --type=plain
reboot --eject
"""
    Copy to Clipboard Toggle word wrap
  2. Save the Kickstart configuration in the toml format to inject the Kickstart content. For example, config.toml.

  3. Run bootc-image-builder, and include the Kickstart file configuration that you want to add to the ISO build. The bootc-image-builder automatically adds the ostreecontainer command that installs the container image.

    Note

    If you do not have the container storage mount and --local image options, your image must be public.

    1. The following is an example of creating a public ISO image: 

      $ sudo podman run \
    --rm \
    -it \
    --privileged \
    --pull=newer \
    --security-opt label=type:unconfined_t \
    -v /var/lib/containers/storage:/var/lib/containers/storage \
    -v $(pwd)/config.toml:/config.toml \
    -v $(pwd)/output:/output \
    registry.redhat.io/rhel9/bootc-image-builder:latest \
    --type iso \
    --config /config.toml \
  quay.io/<namespace>/<image>:<tag>
      Copy to Clipboard Toggle word wrap

    2. The following is an example of creating a private ISO image: 

      $ sudo podman run \
    --rm \
    -it \
    --privileged \
    --pull=newer \
    --security-opt label=type:unconfined_t \
    -v $(pwd)/config.toml:/config.toml:ro \
    -v $(pwd)/output:/output \
    -v /var/lib/containers/storage:/var/lib/containers/storage \
    registry.redhat.io/rhel9/bootc-image-builder:latest \
    --local
    --type iso \
  quay.io/<namespace>/<image>:<tag>
      Copy to Clipboard Toggle word wrap

      You can find the .iso image in the output folder.

4.11. Verification and troubleshooting
Copy link

If you have any issues configuring the requirements for your AWS image, see the following documentation
For more details on users, groups, SSH keys, and secrets, see
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat