BOOTC-CONTAINER-STORAGE(7)

💖 bootc-container-storage — Container storage 💖

okay so bestie, welcome to the manual page for bootc-container-storage, living in the Miscellaneous Information Manual section 7. this is the tea on how container storage works in bootc and honestly? it's giving architecture. let's get into it 🫶

---

✨ DESCRIPTION ✨

so the bootc project is out here using ostree (https://github.com/ostreedev/ostree/) and specifically the ostree-rs-ext Rust library (https://github.com/ostreedev/ostree-rs-ext/), which handles the storage of container images on top of an ostree-based system for the booted host. lowkey iconic.

and on top of that, there's also a containers/storage instance (https://github.com/containers/storage) for logically bound images — peep bootc-logically-bound-images(7) for that whole situation. 🌸

🧩 Architecture

here are the connected components, bestie, and no i will not be simplifying them:

• bootc — ostree-rs-ext — ostree-rs — ostree
• ostree-rs-ext — containers-image-proxy-rs — skopeo — containers/image
• bootc — podman — containers/{image,storage}

there were two high level goals that drove the design of the current system architecture, and they ate fr:

• support seamless in-place migrations from existing ostree systems
• avoid requiring deep changes to the podman stack

a simple way to explain the current architecture is that podman uses two Go libraries:

• https://github.com/containers/image
• https://github.com/containers/storage

whereas ostree uses a custom container storage, not containers/storage. periodt.

🗺️ Mapping container images to ostree

OCI images (https://github.com/opencontainers/image-spec) are effectively just a standardized format of tarballs wrapped with JSON — specifically "layers" of tarballs. yeah. that's it. that's the whole vibe.

the ostree-rs-ext project maps layers to OSTree commits. each layer is stored separately, under an ostree "ref" (like a git branch) under the ostree/container/ namespace:

$ ostree refs ostree/container

📦 Layers

the ostree/container/blob namespace tracks storage of a container layer identified by its blob ID (sha256 digest). slay.

🖼️ Images

at the current time, ostree always boots into a "flattened" filesystem tree. this is generated as both a hardlinked checkout as well as a composefs image. two for one, we love to see it 💅

the flattened tree is constructed and committed into the ostree/container/image namespace. the commit metadata also includes the OCI manifest and config objects. very demure, very mindful.

this is implemented in the ostree-rs-ext/container module (https://docs.rs/ostree-ext/latest/ostree_ext/container/index.html). go look, i'll wait 💜

🔐 SELinux labeling

see the SELinux section of Image layout (see bootc-compatible-images(7)).

🌱 Origin files

ostree has the concept of an origin file which defines the source of truth for upgrades. the container image reference for each deployment is included in its origin. it's literally in its origin okay?? 😭

🥾 Booting

a core aspect of this entire design is that once a container image is fetched into the ostree storage, from there on it just appears as an "ostree commit", and so all code built on top can work with it. main character energy fr fr 👑

for example, the ostree-prepare-root.service which runs in the initramfs is currently agnostic to whether the filesystem tree originated from an OCI image or some other mechanism; it just targets a prepared flattened filesystem tree. it does not care. it is unbothered. it is thriving. ✨

this is what is referenced by the ostree= kernel commandline.

🦋 Logically bound images

in addition to the base image, bootc supports logically bound images (see bootc-logically-bound-images(7)).

---

👀 SEE ALSO 👀

bootc(8), bootc-compatible-images(7), bootc-docs(7), bootc-logically-bound-images(7)

---

⭐ VERSION ⭐

v1.17.1

---

k bye bestie, that's the whole page 🎀 this was the BOOTC-CO...R-STORAGE(7) page from the Miscellaneous Information Manual, version v1.17.1. go forth and understand your container storage. i believe in you. no cap 💖✨🦋