Skip to content

Bootc image building

Bootc image building

Automotive Image Builder produces bootc container images as the default build artifact. A bootc container image packages the full operating system into a standard Open Container Initiative (OCI) container that you can store in a container registry, distribute to devices, and update on running systems with bootc update or bootc switch.

Bootc two-step workflow overview

Building an AutoSD bootc image follows a two-step workflow:

  1. aib build takes a manifest and produces a bootc container image. The container image includes the OS root filesystem, kernel, and all packages and files specified in the manifest.
  2. aib to-disk-image converts the container image into a flashable disk image (raw, qcow2, or simg format) that you can boot on hardware or in a virtual machine.

You can also combine both steps into a single command by passing the optional disk image path as the third positional argument to aib build:

$ aib build manifest.aib.yml localhost/my-image:latest my-image.qcow2

The two-step approach is useful when you want to push the container image to a registry for over-the-air updates before producing a disk image for provisioning.

Note

By default, aib build and related commands use sudo internally to access rootful Podman container storage. The commands prompt for a password if the current user does not have passwordless sudo configured. For rootless builds without sudo, pass the --user-container option to aib build.

Builder images overview

Automotive images are intentionally minimal. They do not include tools such as dnf, mkfs, or osbuild that the disk image conversion process requires. A builder image provides these tools externally in a separate container.

Use aib build-builder to create a builder image, as follows:

$ aib build-builder

When you build a builder image, consider the following key points about builder images in general:

  • The builder image version must match the target distribution. An AutoSD 10 image requires an AutoSD 10 builder image.
  • The default distribution is autosd10-sig. Both aib build-builder and aib build use the same default, so omitting --distro from both commands keeps them in sync.
  • The default image name is localhost/aib-build:$DISTRO (for example, localhost/aib-build:autosd10-sig).
  • Add the --if-needed option on the command line to skip the build if the image already exists.
  • Use --distro to target a non-default distribution. The --distro value must match between aib build-builder and aib build, or you can specify the builder image explicitly with --build-container.
  • You only need to rebuild the builder image when the target distribution changes or when you want to pick up updated tools.

Both aib to-disk-image and aib reseal require the builder image. If you use the combined single-command aib build with a disk output path, the builder image is also required.

Bootc build workflow paths overview

Automotive Image Builder supports two build paths:

  • Bootc workflow (aib build and aib to-disk-image): Use for production deployments. Produces a bootc container image as an intermediate artifact. The container can be pushed to a container registry and used for over-the-air (OTA) updates with bootc update. Note that converting to a disk image is a separate step that requires a builder image.
  • Package-based workflow (aib-dev build): Use in development environments. Produces a disk image directly in a single step without an intermediate container. The package-based workflow does not support over-the-air updates through bootc.
Bootc output formats

Container images are stored in local Podman container storage by default. Use --oci-archive to produce an OCI archive file instead, or --tar to produce a tar archive of the container content.

Disk images support three formats, controlled by the --format option or inferred from the output file extension:

  • raw -- raw disk image with partitions
  • qcow2 -- QEMU Copy On Write format
  • simg -- Android sparse image format

Use --separate-partitions to split the disk image into per-partition files, which some hardware targets require for flashing.

Next steps

For step-by-step build instructions, see Building bootc images.

For information about customizing the manifest, see Creating a custom manifest.

For background on the Automotive Image Builder tool, see Automotive Image Builder tool.