Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 3. Building and managing logically bound images

Logically bound images give you support for container images that are bound to the lifecycle of the base bootc image. This helps combine different operational processes for applications and operating systems. The container application images are referenced from the base image as image files or an equivalent. Consequently, you can manage multiple container images for system installations.

You can use containers for lifecycle-bound workloads, such as security agents and monitoring tools. You can also upgrade such workloads by using the bootc upgrade command.

3.1. Introduction to logically bound images
Copy link

You can associate container application images to a base bootc system image, by using logically bound images. By default, application containers as run by, for example, podman have a lifecycle independent of host upgrades.

Logically bound images offer a key benefit that the application containers bound in this way tie their lifecycle to the host upgrade and are available before the host reboots into the new operating system. These container images remain present if a bootc container references them.

The following are examples for lifecycle bound workloads which are usually not updated outside of the host:

  • Logging, for example, journald→remote log forwarder container
  • Monitoring, for example, Prometheus node_exporter
  • Configuration management agents
  • Security agents

For these types of workloads it is important that the container start from early stage in the boot process, for example, networking might be available. Logically bound images help you to start containers (often by systemd) with the same reliability of using ExecStart= of a binary in the base bootc image.

When using logically bound images, you can manage multiple container images for the system to install the logically bound images. This is an advantage and also a disadvantage. For example, for a disconnected or offline installation, you mirror all the containers, not just one. The application images are only referenced from the base image as .image files or an equivalent.

Logically bound images installation
When you run bootc install, logically bound images are present in the default /var/lib/containers container store. The images are copied into the target system and present directly at boot, alongside the bootc base image.
Logically bound images lifecycle
Logically bound images are referenced by the bootc and have guaranteed availability when the bootc based server starts. The image is always upgraded by using bootc upgrade and is available as read-only to other processes, such as Podman.
Logically bound images management on upgrades, rollbacks, and garbage collection
  • During upgrades, the logically bound images are managed exclusively by bootc.
  • During rollbacks, the logically bound images corresponding to rollback deployments are retained.
  • bootc performs garbage collection of unused bound images.

3.2. Creating logically bound images
Copy link

To create logically bound images, link application container images to the lifecycle of a base bootc image. This approach allows you to manage applications and the operating system as a cohesive unit, facilitating updates and ensuring consistency. You can create logically bound images by using a Podman Quadlet .image or .container files.

Prerequisites

  • The container-tools meta-package is installed.

Procedure

  1. Select the image that you want to logically bound.

  2. Create a Containerfile: 

    $ cat Containerfile
FROM quay.io/<namespace>/<image>:latest
COPY ./<app_1>.image /usr/share/containers/systemd/<app_1>.image
COPY ./<app_2>.container /usr/share/containers/systemd/<app_2>.container

RUN ln -s /usr/share/containers/systemd/<app_1>.image \
	/usr/lib/bootc/bound-images.d/<app_1>.image && \
    ln -s /usr/share/containers/systemd/<app_2>.container \
    	/usr/lib/bootc/bound-images.d/<app_2>.container

  3. In the .container definition, use: 

    GlobalArgs=--storage-opt=additionalimagestore=/usr/lib/bootc/storage

    In the Containerfile example, the image is selected to be logically bound by creating a symlink in the /usr/lib/bootc/bound-images.d directory pointing to either an .image or a .container file.

  4. Run the bootc upgrade command. 

    $ bootc upgrade

    The bootc upgrade performs the following overall steps:

    1. Fetches the new base image from the image repository. See Configuring container pull secrets.
    2. Reads the new base image root file system to discover logically bound images.
    3. Automatically pulls any discovered logically bound images defined in the new bootc image into the bootc-owned /usr/lib/bootc/storage image storage.

  5. Make the bound images become available to container runtimes such as Podman. For that, you must explicitly configure bound images to point to the bootc storage as an "additional image store". For example: 

    podman --storage-opt=additionalimagestore=/usr/lib/bootc/storage run <image>
    Important

    Do not attempt to globally enable the /usr/lib/bootc/storage image storage in /etc/containers/storage.conf. Only use the bootc storage for logically bound images.

    The bootc image store is owned by bootc. The logically bound images will be garbage collected when they are no longer referenced by a file in the /usr/lib/bootc/bound-images.d directory.

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

© 2026 Red HatBack to top