Red Hat Summit Red Hat SummitSupportConsoleDéveloppeursCommencer un essaiContact

Ce contenu n'est pas disponible dans la langue sélectionnée.

Chapter 12. Managing RHEL bootc images

After installing and deploying RHEL bootc images, you can perform management operations on your container images, such as changing or updating the systems. The system supports in-place transactional updates with rollback after deployment.

This kind of management, also known as Day 2 management baseline, consists of transactionally fetching new operating system updates from a container registry and booting the system into them, while supporting manual, or automated rollbacks in case of failures.

See Day 2 operations support for more details.

Note

The rhel-bootc images are rebuilt whenever their underlying inputs, such as RPM packages, are updated. These rebuilds occur at least monthly, or more frequently if critical updates are released. As a user, you maintain full control over when to push the update images. A newly published base image does not trigger automatic rebuilds or redeployments of your custom images. You configure the update cadence and only push changes as required.

Figure 12.1. Manually updating an installed operating system, changing the container image reference or rolling back changes if needed

Bootc update diagram
View larger image
Bootc update diagram

12.1. Switching the container image reference
Copier lien

You can change the container image reference used for upgrades by using the bootc switch command. For example, you can switch from the stage to the production tag. To manually switch an existing ostree-based container image reference, use the bootc switch command.

Prerequisites

  • A booted system using bootc.

Procedure

  • Run the following command: 

    $ sudo bootc switch [--apply] quay.io/<namespace>/<image>:<tag>
    Copy to Clipboard Toggle word wrap

    Optionally, you can use the --apply option when you want to automatically take actions, such as rebooting if the system has changed.

Note

The bootc switch command has the same effect as bootc upgrade. The only difference is the container image reference is changed. This allows preserving the existing states in /etc and /var, for example, host SSH keys and home directories.

12.2. Adding modules to the bootc image initramfs
Copier lien

The rhel9/rhel-bootc image uses the dracut infrastructure to build an initial RAM disk, the initrd during the image build time. The initrd is built and included in the /usr/lib/modules/<kernel-version>/initramfs.img location inside the container.

You can use a drop-in configuration file to override the dracut configuration, and place it in a file in the /usr/lib/dracut/dracut.conf.d/<custom-added-modules.conf> directory. This re-creates initrd with the modules you want to add.

Prerequisites

  • A booted system using bootc.

Procedure

  • Re-create the initrd as part of a container build: 

    FROM <baseimage>
COPY <custom-added-modules>.conf /usr/lib/dracut/dracut.conf.d
RUN set -x; kver=$(cd /usr/lib/modules && echo *); dracut -vf /usr/lib/modules/<kernel-version>/initramfs.img $kver
    Copy to Clipboard Toggle word wrap
    Note

    By default the command attempts to pull the running kernel version, which causes an error. Explicitly pass to dracut the kernel version of the target to avoid errors.

12.3. Modifying and regenerating initrd
Copier lien

The default container image includes a pre-generated initial RAM disk (initrd) in /usr/lib/modules/<kernel-version>/initramfs.img. To regenerate the initrd, for example, to add a dracut module, follow the steps:

Prerequisites

  • A booted system using bootc.

Procedure

  1. Create your drop-in configuration file. For example: 

    dracutmodules = "module"
    Copy to Clipboard Toggle word wrap

  2. Place your drop-in configuration file in the location that dracut normally uses: /usr. For example: 

    /usr/lib/dracut/dracut.conf.d/50-custom-added-modules.conf
    Copy to Clipboard Toggle word wrap

  3. Regenerate the initrd as part of the container build. You must explicitly pass the kernel version to target to dracut, because it tries to pull the running kernel version, which can cause an error. The following is an example: 

    FROM <baseimage>
COPY 50-custom-added-modules.conf /usr/lib/dracut/dracut.conf.d
RUN set -x; kver=$(cd /usr/lib/modules && echo *); dracut -vf /usr/lib/modules/$kver/initramfs.img $kver
    Copy to Clipboard Toggle word wrap

With image mode for RHEL, you can perform any other management task, such as changing or updating the system, by pushing the changes to the container registry.

When using image mode for RHEL, you can choose to perform manual updates for your systems. If you have automatic updates enabled, you must turn them off to perform a manual update. To do so, use one of the following options:

  • Running the bootc upgrade command
  • Modifying the systemd timer file

12.4.1. Turning off automatic updates
Copier lien

To perform manual updates you must turn off automatic updates. You can do this by disabling the timer of the container build, by using one of the following options described in the procedure.

Prerequisites

  • A booted system using bootc.

Procedure

  • Disable the timer of a container build.

    • By running the systemctl mask command: 

      $ systemctl mask bootc-fetch-apply-updates.timer
      Copy to Clipboard Toggle word wrap

    • By modifying the systemd timer file. Use systemd "drop-ins" to override the timer. In the following example, updates are scheduled for once a week.

      1. Create an updates.conf file with the following content: 

        [Timer]
# Clear previous timers
OnBootSec= OnBootSec=1w OnUnitInactiveSec=1w
        Copy to Clipboard Toggle word wrap

      2. Add you file to the directory that you created: 

        $ mkdir -p /usr/lib/systemd/system/bootc-fetch-apply-updates.timer.d
$ cp updates.conf /usr/lib/systemd/system/bootc-fetch-apply-updates.timer.d
        Copy to Clipboard Toggle word wrap

12.4.2. Manually updating an installed operating system
Copier lien

To manually fetch updates from a registry and boot the system into the new updates, use bootc upgrade. This command fetches the transactional in-place updates from the installed operating system to the container image registry. The command queries the registry and queues an updated container image for the next boot. It stages the changes to the base image, but does not change the running system by default.

Prerequisites

  • A booted system using bootc.

Procedure

  • Run the following command: 

    $ bootc upgrade [--apply]
    Copy to Clipboard Toggle word wrap

    The apply argument is optional and you can use it when you want to automatically take actions, such as rebooting if the system has changed.

Note

The bootc upgrade command is an alias for bootc update. Both commands have the same effect.

12.5. Performing rollbacks from a updated operating system
Copier lien

You can roll back to a previous boot entry to revert changes in the system by using the bootc rollback command. This command changes the boot loader entry ordering by making the deployment under rollback queued for the next boot. The current deployment then becomes the rollback. Any staged changes, such as a queued upgrade that was not applied, are discarded.

After a rollback completes, the system reboots and the update timer run within 1 to 3 hours which automatically update and reboot your system to the image you just rolled back from.

Warning

If you perform a rollback, the system will automatically update again unless you turn off auto-updates. See Turning off automatic updates.

When performing a rollback, for example, by using the bootc rollback command, changes made to files in the /etc directory do not carry over to the rolled-back deployment. Instead, the files in the /etc directory revert to the state they were in during the previous deployment.

The bootc rollback command reorders existing deployments but does not create new ones. The /etc directory is merged when new deployments are created.

To preserve a modified /etc file for use after a rollback, copy it to a directory under /var, such as /var/home/<user> for a specific <user>, or under /var/root/, for the root user. These directories are unaffected by rollbacks, as they store user content.

When returning to the original state, either through a temporary rollback or another bootc rollback, the /etc directory reverts to its state from the original deployment.

Alternatively, if the issue you are rolling back does not involve configuration files in the /etc directory and you want to revert to an older deployment, use the bootc switch command. This command performs the necessary /etc merge and deploy the previous version of the software.

Prerequisites

  • You performed an update to the system.

Procedure

  • Run the following command: 

    $ bootc rollback [-h|--help] [-V|--version]
    Copy to Clipboard Toggle word wrap
    Note

    The bootc rollback command has the same effect as bootc upgrade. The only difference is the container image being tracked. This enables preserving the existing states in /etc and /var, for example, host SSH keys and home directories.

Verification

  • Use systemd journal to check the logged message for the detected rollback invocation. 

    $ journalctl -b
    Copy to Clipboard Toggle word wrap

    You can see a log similar to: 

    MESSAGE_ID=26f3b1eb24464d12aa5e7b544a6b5468
    Copy to Clipboard Toggle word wrap

12.6. Deploying updates to system groups
Copier lien

You can change the configuration of your operating system by modifying the Containerfile. The update will be applied after you build and push your container image to the registry, and reboot the operating system.

You can also change the container image source by using the bootc switch command. The content in the container registry determines the specific configuration of the RHEL Image Mode operating systemSee Switching the container image reference.

Usually, when deploying updates to system groups, you can use a central management service to provide a client to be installed on each system which connects to the central service. Often, the management service requires the client to perform a one time registration. The following is an example on how to deploy updates to system groups. You can modify, by injecting the credentials for the management service into the image, to create a persistent systemd service, if required.

Note

For clarity reasons, the Containerfile in the example is not optimized. For example, a better optimization to avoid creating multiple layers in the image is by invoking RUN a single time.

You can install a client into a image mode for RHEL image and run it at startup to register the system.

Prerequisites

  • The management-client handles future connections to the server, by using a cron job or a separate systemd service.

Procedure

  • Create a management service with the following characteristics. It determines when to upgrade the system. 

    FROM registry.redhat.io/rhel9/rhel-bootc:latest
# Management services determine when to upgrade the system.
# Disable bootc-fetch-apply-updates.timer if it is included in the base image.
RUN systemctl disable bootc-fetch-apply-updates.timer

# Install the client from dnf, or some other method that applies for your client
RUN dnf install management-client -y && dnf clean all

# Inject the credentials for the management service into the image
ARG activation_key=

# The existence of .run_next_boot acts as a flag to determine if the
# registration is required to run when booting
RUN touch /etc/management-client/.run_next_boot

COPY <<"EOT" /usr/lib/systemd/system/management-client.service
[Unit]
Description=Run management client at boot
After=network-online.target
ConditionPathExists=/etc/management-client/.run_client_next_boot

[Service]
Type=oneshot
EnvironmentFile=/etc/management-client/.credentials
ExecStart=/usr/bin/management-client register --activation-key ${CLIENT_ACTIVATION_KEY}
ExecStartPre=/bin/rm -f /etc/management-client/.run_next_boot
ExecStop=/bin/rm -f /etc/management-client/.credentials

[Install]
WantedBy=multi-user.target
EOT

# Link the service to run at startup
RUN ln -s /usr/lib/systemd/system/management-client.service /usr/lib/systemd/system/multi-user.target.wants/management-client.service

# Store the credentials in a file to be used by the systemd service
RUN echo -e "CLIENT_ACTIVATION_KEY=${activation_key}" > /etc/management-client/.credentials

# Set the flag to enable the service to run one time
# The systemd service will remove this file after the registration completes the first time
RUN touch /etc/management-client/.run_next_boot
    Copy to Clipboard Toggle word wrap
    1. Disable bootc-fetch-apply-updates.timer if it is included in the base image.
    2. Install the client by using dnf, or some other method that applies for your client.
    3. Inject the credentials for the management service into the image.

12.7. Checking inventory health
Copier lien

You can manually check the system health of the container images and events that are running inside the container.

Prerequisites

  • You pushed the container image to an accessible repository.
  • The container-tools meta-package is installed.

Procedure

  • Display the health check status of a container.

    • By using the podman inspect: or podman ps commands. 

      $ podman inspect --format='{{json .State.Health.Status}}' <container>
healthy
      Copy to Clipboard Toggle word wrap

    • By using the podman ps commands. 

      $ podman healthcheck run <container>
healthy
      Copy to Clipboard Toggle word wrap

  • Monitor and print events that occur in Podman by using the podman events command. Each event includes a timestamp, a type, a status, a name, if applicable, and an image, if applicable. 

    $ now=$(date --iso-8601=seconds)
$ podman events --since=now --stream=false
healthy
    Copy to Clipboard Toggle word wrap

12.8. Automation and GitOps
Copier lien

You can use CI/CD (Continuous Integration and Continuous Delivery) pipelines to automate the building process of your RHEL bootc images. By using a CI/CD , an event can trigger an update, such as updating an application.

You can use automation tools that track these updates and trigger the CI/CD pipelines, such as GitHub Actions, and GitLab CI. The pipeline keeps the systems up to date by using the transactional background operating system updates.

For more details on resources to create image mode for RHEL instances, check the specific implementations available to create image mode for RHEL instances: RHEL Image Mode CI/CD.

12.9. Inspecting bootc containers by using Toolbx
Copier lien

Installing software on a system presents certain risks: it can change a system’s behavior, and can leave unwanted files and directories behind after they are no longer needed. You can prevent these risks by installing your preferred development and debugging tools, editors, and software development kits (SDKs) into the Toolbx utility included in the RHEL bootc, a container image that can be completely modified without affecting the base operating system. You can perform changes on the host system with commands such as less, lsof, rsync, ssh, sudo, and unzip.

The Toolbx utility performs the following actions:

  1. Pulling the registry.access.redhat.com/ubi9/toolbox:latest image to your local system
  2. Starting up a container from the image
  3. Running a shell inside the container from which you can access the host system
Note

Toolbx can run a root container or a rootless container, depending on the rights of the user who creates the Toolbx container. Utilities that would require root rights on the host system also should be run in root containers.

The default container name is rhel-toolbox. To inspect bootc containers, follow the steps:

Procedure

  1. Start a Toolbx container by using the toolbox create command and enter the container with the toolbox enter command.

    • As a rootless user: 

      $ toolbox create <mytoolbox>
      Copy to Clipboard Toggle word wrap

    • As a root user: 

      $ sudo toolbox create <mytoolbox>
Created container: <mytoolbox>
Enter with: toolbox enter
      Copy to Clipboard Toggle word wrap

    • Verify that you pulled the correct image: 

      [user@toolbox ~]$ toolbox list
IMAGE ID      IMAGE NAME    CREATED
fe0ae375f149   registry.access.redhat.com/ubi{ProductVersion}/toolbox 5 weeks ago

CONTAINER ID  CONTAINER NAME  CREATED         STATUS   IMAGE NAME
5245b924c2cb  <mytoolbox>       7 minutes ago   created  registry.access.redhat.com/ubi{ProductVersion}/toolbox:8.9-6
      Copy to Clipboard Toggle word wrap

      1. Enter the Toolbx container: 

        [user@toolbox ~]$ toolbox enter <mytoolbox>
        Copy to Clipboard Toggle word wrap
      2. Optional: Check if you pulled the correct image

    • Enter a command inside the <mytoolbox> container and display the name of the container and the image: 

      ⬢ [user@toolbox ~]$ cat /run/.containerenv
engine="podman-4.8.2"
name="<mytoolbox>"
id="5245b924c2cb..."
image="registry.access.redhat.com/ubi{ProductVersion}/toolbox"
imageid="fe0ae375f14919cbc0596142e3aff22a70973a36e5a165c75a86ea7ec5d8d65c"
      Copy to Clipboard Toggle word wrap

  2. Use the Toolbx to install the development tools:

    1. Install the tools of your choice, for example, the Emacs text editor, GCC compiler and GNU Debugger (GDB): 

      ⬢[user@toolbox ~]$ sudo dnf install emacs gcc gdb
      Copy to Clipboard Toggle word wrap

    2. Optional: Verify that the tools are installed: 

      ⬢[user@toolbox ~]$  dnf repoquery --info --installed <package_name>
      Copy to Clipboard Toggle word wrap

      After installation, you can continue using those tools as a rootless user.

  3. Use Toolbx to troubleshoot the host system without installing them on the host system.

    1. Install the systemd suite to be able to run the journalctl command: 

      ⬢[root@toolbox ~]# dnf install systemd
      Copy to Clipboard Toggle word wrap

    2. Display log messages for all processes running on the host: 

      ⬢[root@toolbox ~]# j journalctl --boot -0
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: microcode: updated ear>
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: Linux version 6.6.8-10>
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: Command line: BOOT_IMA>
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: x86/split lock detecti>
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: BIOS-provided physical>
      Copy to Clipboard Toggle word wrap

    3. Display log messages for the kernel: 

      ⬢[root@toolbox ~]# journalctl --boot -0 --dmesg
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: microcode: updated ear>
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: Linux version 6.6.8-10>
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: Command line: BOOT_IMA>
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: x86/split lock detecti>
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: BIOS-provided physical>
Jan 02 09:06:48 user-thinkpadp1gen4i.brq.csb kernel: BIOS-e820: [mem 0x0000>
      Copy to Clipboard Toggle word wrap

    4. Install the nmap network scanning tool: 

      ⬢[root@toolbox ~]# dnf install nmap
      Copy to Clipboard Toggle word wrap

    5. Scan IP addresses and ports in a network: 

      ⬢[root@toolbox ~]# nmap -sS scanme.nmap.org
Starting Nmap 7.93 ( https://nmap.org ) at 2024-01-02 10:39 CET
Stats: 0:01:01 elapsed; 0 hosts completed (0 up), 256 undergoing Ping Scan
Ping Scan Timing: About 29.79% done; ETC: 10:43 (0:02:24 remaining)
Nmap done: 256 IP addresses (0 hosts up) scanned in 206.45 seconds
      Copy to Clipboard Toggle word wrap
      • The -sS option performs a TCP SYN scan. Most of Nmap’s scan types are only available to privileged users, because they send and receive raw packets, which requires root access on UNIX systems.

  4. Stop the Toolbx bootc container.

    1. Leave the container and return to the host: 

      ⬢ [user@toolbox ~]$ exit
      Copy to Clipboard Toggle word wrap

    2. Stop the toolbox container: 

      ⬢ [user@toolbox ~]$ podman stop <mytoolbox>
      Copy to Clipboard Toggle word wrap

    3. Optional: Remove the toolbox container: 

      ⬢ [user@toolbox ~]$ toolbox rm <mytoolbox>
      Copy to Clipboard Toggle word wrap

      Alternatively, you can also use the podman rm command to remove the bootc container.

Retour au début
Red Hat logoGithubredditYoutubeTwitter

Apprendre

Essayez, achetez et vendez

Communautés

À propos de la documentation Red Hat

Nous aidons les utilisateurs de Red Hat à innover et à atteindre leurs objectifs grâce à nos produits et services avec un contenu auquel ils peuvent faire confiance. Découvrez nos récentes mises à jour.

Rendre l’open source plus inclusif

Red Hat s'engage à remplacer le langage problématique dans notre code, notre documentation et nos propriétés Web. Pour plus de détails, consultez le Blog Red Hat.

À propos de Red Hat

Nous proposons des solutions renforcées qui facilitent le travail des entreprises sur plusieurs plates-formes et environnements, du centre de données central à la périphérie du réseau.

Theme

© 2025 Red Hat