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, and 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

By using logically bound images, you can associate container application images to a base bootc system image. By default, application containers as executed by, for example, podman have a lifecycle independent of host upgrades; they can be added or removed at any time, and are typically fetched on demand after booting if the container image is not present.

Logically bound images offer a key benefit that the application containers bound in this way have a lifecycle tied to the host upgrade and are available before the host reboots into the new operating system. The container images bound in this way will be present as long as 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 often important that the container start from a very early stage in the boot process before e.g. networking might be available. Logically bound images enable you to start containers (often via systemd) with the the same reliability of using ExecStart= of a binary in the base bootc image.

The term logically bound can also be contrasted with another model of physically bound images, where application container content is physically stored in the bootc container image. A key advantage for logically bound over physically bound is that tou can update the bootc system without re-downloading application container images which are not changed.

When using logically bound images, you must 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 must 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 must be present in the default /var/lib/containers container store. The images will be 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 bootable container 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

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
    Copy to Clipboard Toggle word wrap

  3. In the .container definition, use: 

    GlobalArgs=--storage-opt=additionalimagestore=/usr/lib/bootc/storage
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

    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>
    Copy to Clipboard Toggle word wrap
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.

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