Bootc image layering

Bootc image layering overview¶

Bootc image layering uses standard container build techniques to customize an AutoSD bootc image. Instead of defining all customization in an AIB manifest, you write a Containerfile that starts with an existing bootc image and then adds packages, files, and configuration as new container layers.

Manifest-based versus layer-based customization¶

Automotive Image Builder supports two customization approaches. You can use either approach independently, or you can combine them.

Manifest-based customization¶

All OS image content is defined in a single .aib.yml manifest file. The aib build command reads the manifest, resolves dependencies, and produces the final bootc container image in one step.

Manifest-based customization is best suited for the following scenarios:

Defining the core OS packages, kernel, and target configuration
Setting authentication, networking, and SELinux options
Producing a reproducible base image from a declarative specification

For details on available manifest options, see Creating a custom manifest.

Layer-based customization¶

A base bootc image is produced with aib build, and a Containerfile adds packages, files, or configuration on top using podman build. The result is a new bootc container image that includes both the base content and the layered changes.

Layering-based customization is best suited for:

Reusing a common base image across multiple image variants
Adding application-specific packages or configuration files that differ between variants
Applying customization steps that require tools or logic beyond what the manifest supports (for example, compiling software or running scripts during the build)

Base image sources¶

The primary source for a base image is a locally built aib build image. When you run aib build, the resulting container image is stored in local Podman storage under the name you specify (for example, localhost/my-base-image). You can reference that name directly in a Containerfile FROM directive.

If a prebuilt AutoSD bootc base image is available from a container registry, you can use the registry URL in the FROM directive instead. Registry-hosted base images simplify the workflow for teams that share a common base without requiring each developer to run aib build locally.

How layering works with bootc¶

A layered image remains a valid bootc container image. After building the layered image with podman build, you can:

Convert the layered image to a disk image with aib to-disk-image
Push the layered image to a container registry
Update running systems to the layered image with bootc switch or bootc update

The layered image inherits the kernel, target configuration, and partition layout from the base image. Layered changes affect only the root filesystem content.

Composefs and sealed images overview¶

Layering applies at build time in a Containerfile. Once a bootc image is deployed to a device, composefs with signed commits (the default configuration) prevents runtime modification of the OS filesystem. The device receives updates only through bootc update or bootc switch with a new container image.

If you need to allow runtime package installation on a deployed system (for example, during development), set image.sealed to false in the manifest that produces the base image. However, note that disabling composefs signing reduces the tamperproofing guarantees of the deployed image. For production deployments, perform all customization at build time through manifests or layering.

The procedure described in Building an AutoSD-based base container image creates an application container from a UBI base image with AutoSD repositories configured. That container is designed for running workloads (for example, application services) inside an AutoSD system.

Bootc image layering customizes the OS image itself. The base image is a full AutoSD bootc image produced by aib build, and the layered result is a bootable operating system image and not an application container.

Next steps¶

For step-by-step layering instructions, see Layering bootc images.

For background on building the base bootc image, see Bootc image building.