Understanding registry-based image distribution and OTA updates for bootc workflows

Understanding registry-based image distribution and OTA updates for bootc workflows¶

The bootc update model centers on container registries. After building a bootc image with aib build, you can push the image to a registry to distribute it to devices. Running systems pull updates from the registry using bootc switch or bootc update.

Registry-centric update model¶

Automotive Image Builder produces bootc container images that follow the standard OCI container image format. The distribution lifecycle follows three stages:

Build: aib build produces a bootc container image stored in local Podman storage (or as an OCI archive with the --oci-archive option).
Push: The image is tagged and pushed to a container registry using podman push or skopeo copy.
Update: Devices pull the image from the registry using bootc switch for a new image or bootc update for a newer version of the currently tracked image.

The registry acts as the central distribution point. Multiple devices can track the same registry image and receive updates independently.

The package-based workflow (aib-dev build) produces disk images that are flashed directly to devices. Disk images created with this workflow are not part of the registry-based update model.

Push workflows¶

Two tools can push bootc images to a registry:

podman push pushes an image from local Podman storage to a remote registry. Use podman push when the image was built with aib build and stored locally (the default behavior).
skopeo copy copies images between storage backends. Use skopeo copy when the image was built as an OCI archive (--oci-archive) or when copying between registries without pulling the image locally.

Both tools support authentication via podman login or credential files at ${XDG_RUNTIME_DIR}/containers/auth.json.

Update commands on the device¶

Three bootc commands manage updates on a running system:

bootc switch <registry>/<image>:<tag> changes the tracked image to a new registry reference and stages the update. The system boots into the new image on the next reboot.
bootc update pulls the latest version of the currently tracked image and stages the update. The system boots into the updated image on the next reboot.
bootc status displays the currently booted image, any staged update, and the registry reference the system tracks.

Updates are atomic. The running system continues operating on the current image until a reboot applies the staged update. If the new image fails to boot, the system rolls back to the previous image.

Registry authentication¶

Pushing images to a registry requires authentication. Run podman login <registry> before pushing:

$ podman login registry.example.com

Podman stores credentials in ${XDG_RUNTIME_DIR}/containers/auth.json. The skopeo tool uses the same credential store.

On the device side, bootc reads credentials from /etc/containers/auth.json or the user-level credential file when pulling updates from authenticated registries.

Relationship to embedding application containers when building images¶

The existing procedures for embedding container images from a remote registry and configuring AIB for private container images document a different workflow: embedding application containers into the OS image at build time. In that workflow, Automotive Image Builder pulls application containers from a registry and includes them in the OS image so they are available after the system boots.

Registry interactions for OS image distribution happen after the image is built. The OS image itself is pushed to a registry, and devices pull the full OS image (not individual application containers) when updating.

Both processes can use the same registry infrastructure, but they serve different purposes and operate at different stages of the image lifecycle.

Next steps¶

For step-by-step instructions on pushing images and updating devices, see Registry workflows.

For background on building the bootc image that you push to a registry, see Bootc image building.