Chapter 6. Deploying RHEL bootc images

Procedure

1. Export the RHEL installation ISO image to the HTTP server. The PXE boot server is now ready to serve PXE clients.
2. Boot the client and start the installation.
3. Select PXE Boot when prompted to specify a boot source. If the boot options are not displayed, press the Enter key on your keyboard or wait until the boot window opens.
4. From the Red Hat Enterprise Linux boot window, select the boot option that you want, and press Enter.
5. Start the network installation.

Procedure

1. Create a metadata.yaml file and add the following information to this file:

   instance-id: cloud-vm
   local-hostname: vmname

2. Create a userdata.yam file and add the following information to the file:

   #cloud-config
   users:
   - name: admin
     sudo: "ALL=(ALL) NOPASSWD:ALL"
     ssh_authorized_keys:
     - ssh-rsa AAA...fhHQ== your.email@example.com

   ssh_authorized_keys is your SSH public key. You can find your SSH public key in ~/.ssh/id_rsa.pub.

3. Export the metadata.yaml and userdata.yaml files to the environment, compressed with gzip, encoded in base64 as follows. You will use these files in further steps.

   export METADATA=$(gzip -c9 <metadata.yaml | { base64 -w0 2>/dev/null || base64; }) \
   USERDATA=$(gzip -c9 <userdata.yaml | { base64 -w0 2>/dev/null || base64; })

4. Launch the image on vSphere with the metadata.yaml and userdata.yaml files:

   1. Import the .vmdk image in to vSphere:

      $ govc import.vmdk ./composer-api.vmdk <foldername>

   2. Create the VM in vSphere without powering it on:

      govc vm.create \
      -net.adapter=vmxnet3 \
      -m=4096 -c=2 -g=rhel8_64Guest \
      -firmware=bios -disk="foldername/composer-api.vmdk” \
      -disk.controller=ide -on=false \
      vmname

   3. Change the VM to add ExtraConfig variables, the cloud-init config:

      govc vm.change -vm vmname \
      -e guestinfo.metadata="${METADATA}" \
      -e guestinfo.metadata.encoding="gzip+base64" \
      -e guestinfo.userdata="${USERDATA}" \
      -e guestinfo.userdata.encoding="gzip+base64"
      .. Power-on the VM:
      govc vm.power -on vmname

   4. Retrieve the VM IP address:

      HOST=$(govc vm.ip vmname)

Procedure

1. In a browser, access Service→EC2 and log in.
2. On the AWS console dashboard menu, choose the correct region. The image must have the Available status, to indicate that it was correctly uploaded.
3. On the AWS dashboard, select your image and click Launch.
4. In the new window that opens, choose an instance type according to the resources you need to start your image. Click Review and Launch.
5. Review your instance details. You can edit each section if you need to make any changes. Click Launch.
6. Before you start the instance, select a public key to access it. You can either use the key pair you already have or you can create a new key pair.

7. Click Launch Instance to start your instance. You can check the status of the instance, which displays as Initializing.

   After the instance status is Running, the Connect button becomes available.

8. Click Connect. A window appears with instructions on how to connect by using SSH.

9. Run the following command to set the permissions of your private key file so that only you can read it. See Connect to your Linux instance.

   $ chmod 400 <your-instance-name.pem>

10. Connect to your instance by using its Public DNS:

    $ ssh -i <your-instance-name.pem>ec2-user@<your-instance-IP-address>

    Note

    Your instance continues to run unless you stop it.

Procedure

1. Create a custom installer ISO disk image with bootc-image-builder. See Creating ISO images by using bootc-image-builder.
2. Copy the ISO disk image to a USB flash drive.
3. Perform a bare-metal installation by using the content in the USB stick into a disconnected environment.

Procedure

1. Create a ./config.toml. The following example shows how to add a user to the disk image.

   [[customizations.user]]
   name = "user"
   password = "pass"
   key = "ssh-rsa AAA ... user@email.com"
   groups = ["wheel"]

   • name - Mandatory. Name of the user.
   • password - Not mandatory. Nonencrypted password.
   • key - Not mandatory. Public SSH key contents.
   • groups - Not mandatory. An array of groups to add the user into.

2. Run bootc-image-builder and pass the following arguments, including the ./config.toml:

   $ sudo podman run \
       --rm \
       -it \
       --privileged \
       --pull=newer \
       --security-opt label=type:unconfined_t \
       -v ./config.toml:/config.toml \
       -v ./output:/output \
       registry.redhat.io/rhel10/bootc-image-builder:latest \
       --type qcow2 \
       --config config.toml \
       quay.io/<namespace>/<image>:<tag>

3. Launch a VM, for example, by using virt-install:

   $ sudo virt-install \
     --name bootc \
     --memory 4096 \
     --vcpus 2 \
     --disk qcow2/disk.qcow2 \
     --import \
     --os-variant rhel10

Procedure

1. After the instance starts, connect to it by using SSH using the key you selected when creating the instance:

   $ ssh -i <ssh-key-file> <cloud-user@ip>

2. Make sure that the system-reinstall-bootc subpackage is installed:

   # rpm -q system-reinstall-bootc

   If not, install the system-reinstall-bootc subpackage:

   # dnf -y install system-reinstall-bootc

3. Convert the system to use a bootc image:

   # system-reinstall-bootc <image>

   • You can use the container image from the Red Hat Ecosystem Catalog or the customized bootc image built from a Containerfile.
4. Select users to import to the bootc image by pressing the "a" key.
5. Confirm your selection twice and wait until the image is downloaded.

6. Reboot the system:

   # reboot

7. Remove the stored SSH host key for the given <ip> from your /.ssh/known_hosts file:

   # ssh-keygen -R <ip>

   The bootc system is now using a new public SSH host key. When attempting to connect to the same IP address with a different key than what is stored locally, SSH will raise a warning or refuse the connection due to a host key mismatch. Since this change is expected, the existing host key entry can be safely removed from the ~/.ssh/known_hosts file using the following command.

8. Connect to the bootc system:

   # ssh -i <ssh-key-file> root@<ip>

Procedure

1. Verify which storage devices are already connected to your system.

   $ lsblk
   NAME          MAJ:MIN     SIZE   RO TYPE  MOUNTPOINTS
   zram0           251:0       8G    0 disk  [SWAP]
   nvme0n1         259:0   476.9G    0 disk
   ├─nvme0n1p1    259:1     600M    0 part  /boot/efi
   ├─nvme0n1p2    259:2       1G    0 part  /boot
   └─nvme0n1p3    259:3   475.4G    0 part

2. Connect your external storage and run the same command. Compare the two outputs to find the name of your external storage device on your system.

   $ lsblk
   NAME        MAJ:MIN   SIZE   RO TYPE  MOUNTPOINTS
   sda             8:0   28.9G    0 disk
   └─sda1         8:1   28.9G    0 part
   zram0         251:0      8G    0 disk  [SWAP]
   nvme0n1       259:0  476.9G    0 disk
   ├─nvme0n1p1  259:1    600M    0 part  /boot/efi
   ├─nvme0n1p2  259:2      1G    0 part  /boot
   └─nvme0n1p3  259:3  475.4G    0 part

   In this case, the USB drive whose name is sda has an sda1 partition.

   The MOUNTPOINTS column lists the mount points of the partitions on your external storage. If your system automatically mounts external storage, then valid mount points already exist. However, if there are no mount points, you must mount it yourself before you can store anything on the device.

3. Create an empty directory, or use an existing one, to mount your partition:

   $ sudo mkdir /mnt/usb/

   1. Mount your device partition.

      $ sudo mount /dev/sda1 /mnt/usb

   2. Optional: Verify if the partition was correctly created:

      $ lsblk
      NAME         MAJ:MIN    SIZE   RO TYPE  MOUNTPOINTS
      sda              8:0   28.9G    0 disk
      └─sda1          8:1   28.9G    0 part  /mnt/usb
      [...]

      Your external storage device is ready for copying files onto it.

4. Copy the container stored locally to your mounted device by using the skopeo command, and adapting the paths and names of the container for your own environment:

   • For local storage:

     $ sudo skopeo copy --preserve-digests --all \
       containers-storage:localhost/rhel-container:latest \
       oci://mnt/usb/

   • For a container stored on a remote registry:

     $ sudo skopeo copy --preserve-digests --all \
       docker://quay.io/example:latest \
       oci://mnt/usb/

     Note

     Depending on the size of the container, these commands might take a few minutes to complete.

5. Unmount and eject the external storage:

   $ sudo umount /dev/sda1
   $ sudo eject /dev/sda1

6. Apply the update to the container on the offline system.
7. Plug the external storage device into your offline system. If the storage device does not mount automatically, use the mkdir and mount commands to locate the external storage and mount it.

8. Copy the container from the external device over to the offline system’s local container registry. Copy the container to the offline machine’s local container storage:

   $ skopeo copy --preserve-digests --all \
     oci://mnt/usb \
     containers-storage:rhel-update:latest

   In this case, the mount point of the external storage is the path to the OCI section, while the containers-storage section varies depending on the name and tag you want the container to have.

9. Use Podman to verify that your container is now local:

   $ podman images
   REPOSITORY			        TAG     IMAGE ID  CREATED  SIZE
   example.io/library/rhel-update   latest  cdb6d...  1 min    1.48 GB

10. Deploy the update to the container on the offline system by using bootc:

    $ bootc switch --transport containers-storage \
    example.io/library/rhel-update:latest

    1. If you cannot copy your container to local storage, use the oci transport flag and the path to your storage device instead:

       $ bootc switch --transport oci /mnt/usb

       With the --transport flag in the bootc switch command, you can specify an alternative source for the container.

       By default, bootc attempts to pull from a registry because the bootc-image-builder uses a registry to build the original image. When using bootc upgrade, you cannot specify where an update is located. By using the bootc switch and specifying that you are using local container storage, you cannot only remove the requirement of a remote registry, but also deploy updates by using this local container in the future.

       You can now successfully use the bootc upgrade, provided that your local container and the update share the same location. If you want to switch to updates on a remote repository in the future, you must use bootc switch again.

Verification

1. Ensure that the update was properly deployed:

   $ bootc status
   Staged image: containers-storage:example.io/library/rhel-update:latest
     Digest: sha256: 05b1dfa791...
     Version: 10.0 (2025-07-07 18:33:19.380715153 UTC)
   Booted Image: localhost/rhel-intel:base
     Digest: sha256: 7d6f312e09...
     Version: 10.0 (2025-06-23 15:58:12.228704562 UTC)

   The output shows your current booted image, along with any changes staged to happen. The container you used earlier is visible, but the staged changes do not happen until the next reboot. The output also confirms that updates will be pulled from your container storage.

2. Reboot the system:

   $ bootc status
   Booted image: containers-storage:example.io/library/rhel-update:latest
   	Digest: sha256: 05b1dfa791...
   	Version: 10.0 (2025-07-07 18:33:19.380715153 UTC)
   Rollback image: localhost/rhel-intel:base
   	Digest: sha256: 7d6f312e09...
   	Version: 10.0 (2025-06-23 15:58:12.228704562 UTC)

   You can verify that you have booted into the correct image:

   • The booted image is your updated image.
   • The rollback image is your previous image. You have successfully performed an offline image mode update.