BOOTC-LO...D-IMAGES(7)

🌸 BOOTC-LO...D-IMAGES 🌸

okay bestie we are in section 7 of the Miscellaneous Information Manual and this page is Logically Bound Images, and honestly it's giving main character energy for your container apps 💅 let's get into it.

---

✨ NAME ✨

bootc-logically-bound-images — Logically Bound Images. short, sweet, iconic, periodt. ✨

💖 DESCRIPTION 💖

🫶 About logically bound images 🫶

okay so this feature enables an association of container "app" images to a base bootc system image. the use cases include:

• Logging (e.g. journald->remote log forwarder container)
• Monitoring (e.g. Prometheus node_exporter https://github.com/prometheus/node_exporter)
• Configuration management agents
• Security agents

these types of things are commonly not updated outside of the host, and there's a secondary important property: we always want them present and available on the host, possibly from very early on in the boot. in contrast with default usage of tools like podman or docker, images may be pulled dynamically after the boot starts; requiring functioning networking, etc. for example if the remote registry is unavailable temporarily, the host system may run for a longer period of time without log forwarding or monitoring, which can be very undesirable 😭 no thank u.

another simple way to say this is that logically bound images allow you to reference container images with the same confidence you can with ExecStart= in a systemd unit. that's the vibe. 👑

the term "logically bound" was created to contrast with physically bound images (https://github.com/bootc-dev/bootc/issues/644). there are some trade-offs between the two approaches. some benefits of logically bound images are:

• The bootc system image can be updated without re-downloading the app image bits.
• The app images can be updated without modifying the bootc system image, this would be especially useful for development work

🌈 Using logically bound images 🌈

each image is defined in a Podman Quadlet (https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html) .image or .container file. an image is selected to be bound by creating a symlink in the /usr/lib/bootc/bound-images.d directory pointing to a .image or .container file 🎀

with these defined, during a bootc upgrade or bootc switch the bound images defined in the new bootc image will be automatically pulled into the bootc image storage, and are available to container runtimes such as podman by explicitly configuring them to point to the bootc storage as an "additional image store", via e.g.:

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

An example Containerfile

FROM quay.io/myorg/myimage:latest

COPY ./my-app.image /usr/share/containers/systemd/my-app.image
COPY ./another-app.container /usr/share/containers/systemd/another-app.container

RUN ln -s /usr/share/containers/systemd/my-app.image \
    /usr/lib/bootc/bound-images.d/my-app.image && \
    ln -s /usr/share/containers/systemd/another-app.container \
    /usr/lib/bootc/bound-images.d/another-app.container

in the .container definition, you should use:

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

NOTE: Do not attempt to globally enable /usr/lib/bootc/storage in /etc/containers/storage.conf; only use the bootc storage for logically bound images, not also floating images. For more, see below. ⚠️ like fr fr do not do this one.

🔐 Pull secret 🔐

images are fetched using the global bootc pull secret by default (/etc/ostree/auth.json). it is not yet supported to configure PullSecret in these image definitions 🙈

🗑️ Garbage collection 🗑

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

💾 Installation 💾

logically bound images must be present in the default container store (/var/lib/containers) when invoking bootc install (see bootc-installation(7)); the images will be copied into the target system and present directly at boot, alongside the bootc base image 🔥

🚧 Limitations 🚧

the only field parsed and honored by bootc currently is the Image field of a .image or .container file.

other pull-relevant flags such as PullSecret= for example are not supported (see above). another example unsupported flag is Arch (the default host architecture is always used).

there is no mechanism to inject arbitrary arguments to the podman pull (or equivalent) invocation used by bootc. however, many properties used for container registry interaction can be configured via containers-registries.conf (https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md) and apply to all commands operating on that image.

it is not currently supported in general to launch "rootless" containers from system-owned image stores in general, whether from /var/lib/containers or the /usr/lib/bootc/storage. there is no integration between bootc and "rootless" storage today, and none is planned. instead, it's recommended to ensure that your "system" or "rootful" containers drop privileges. more in e.g. https://github.com/containers/podman/discussions/13728 💀

🐍 Distro/OS installer support 🐍

at the current time, logically bound images are not supported by Anaconda (https://github.com/rhinstaller/anaconda/discussions/5197).

⚖️ Comparison with default podman systemd units ⚖️

in the comparison below, the term "floating" will be used for non-logically bound images. these images are often fetched by e.g. podman-systemd (https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html) and may be upgraded, added or removed independently of the host upgrade lifecycle.

🔄 Lifecycle 🔄

• Floating image: The images are downloaded by the machine the first time it starts (requiring networking typically). Tools such as podman auto-update can be used to upgrade them independently of the host.
• Logically bound image: The images are referenced by the bootable container and are ensured to be available when the (bootc based) server starts. The image is always upgraded via bootc upgrade and appears read-only to other processes (e.g. podman).

↩️ Upgrades, rollbacks and garbage collection ↪️

• Floating image: Managed by the user (podman auto-update, podman image prune). This can be triggered at anytime independent of the host upgrades or rollbacks, and host upgrades/rollbacks do not affect the set of images.
• Logically bound image: Managed exclusively by bootc during upgrades. The logically bound images corresponding to rollback deployments will also be retained. bootc performs garbage collection of unused images.

🙅 rootless container image 🙅

• Floating image: Supported.
• Logically bound image: Not supported (bootc cannot be invoked as non-root). Instead, it's recommended to just drop most privileges for launched logically bound containers.

🚫 Avoid using /usr/lib/bootc/storage for floating images 🚫

okay this one matters, listen up bestie. because images and in particular layers of images can be removed over time as the OS upgrades, if you attempt to globally enable /usr/lib/bootc/storage in the global /etc/containers/storage.conf that would also apply to "floating" container images (i.e. the default podman run and other runtimes), it can cause a bug where floating images can later fail if layers that were reused in the LBI storage are removed. in the future, this restriction may be lifted, but at the current time you can only configure this additional storage for logically bound images 😤 so don't get cute with it.

---

👀 SEE ALSO 👀

bootc(8), bootc-docs(7), bootc-installation(7)

🏷️ VERSION 🏷️

v1.17.1

---

and that's a wrap, angel 💋 this was BOOTC-LO...D-IMAGES(7) from the Miscellaneous Information Manual, sitting pretty at version v1.17.1 🫶 go bind some images logically, you absolute icon 👑 🦋