Skip to content

Building bootc images

Building bootc images

Follow these procedures to build a bootc container image with Automotive Image Builder and convert it to a bootable disk image.

Depending on your needs, you can choose between two workflows:

  • a two-step workflow that gives you access to the intermediate container image
  • a combined single-command workflow that generates a bootable disk image
Prerequisites
Build the builder image

The builder image provides tools required by aib to-disk-image and the combined build command. You must create the builder image before producing a disk image for the first time.

Build the builder image:

$ aib build-builder

The command creates a container image named localhost/aib-build:autosd10-sig (the tag matches the default distribution). You only need to rebuild the builder image when the target distribution changes.

To skip the build if the image already exists, add --if-needed:

$ aib build-builder --if-needed

Note

If you override the distribution with --distro in aib build-builder, you must pass the same --distro value to aib build and aib to-disk-image, or specify the builder image explicitly with --build-container. A mismatch between the builder image tag and the build distribution causes a "not in local container store" error.

Do a two-step build

Use the two-step workflow when you want to inspect or push the container image before converting it to a disk image.

  1. Build the bootc container image. Build the container image from your manifest:

    console $ aib build \ --target qemu \ manifest.aib.yml \ localhost/my-image:latest

    Replace manifest.aib.yml with the path to your manifest file and localhost/my-image:latest with the desired container image name. Using a localhost/ prefix prevents Podman from resolving the name against a remote registry. The --target option selects the hardware target. The default distribution is autosd10-sig; use --distro to override it.

    To log in to the booted image as root, the manifest must define a root password in the auth section. For example:

    yaml auth: root_password: $6$xoLqEUz0cGGJRx01$H3H/bFm0myJPULNMtbSsOFd/2BnHqHkMD92Sfxd.EKM9hXTWSmELG8cf205l6dktomuTcgKGGtGDgtvHVXSWU.

    For additional authentication options such as SSH keys and extra users, see Creating a custom manifest.

  2. Verify the container image. Confirm that the container image was created:

    console $ sudo podman images | grep localhost/my-image

  3. Convert to a disk image. Convert the container image to a QEMU-compatible disk image:

    console $ aib to-disk-image \ localhost/my-image:latest \ my-image.qcow2

    The output format is inferred from the file extension. You can also set it explicitly with --format:

    console $ aib to-disk-image \ --format raw \ localhost/my-image:latest \ my-image.qcow2

  4. Boot the image. Boot the disk image in Automotive Image Runner. Substitute the filename produced in the previous step:

    console $ air --nographics my-image.qcow2

    After the image boots, log in as root using the password defined in the manifest auth section.

Do a combined single-command build

Use the combined workflow to produce both the container image and the disk image in a single command.

  1. Build the container and disk image. Pass the disk image path as the third positional argument:

    console $ aib build \ --target qemu \ manifest.aib.yml \ localhost/my-image:latest \ my-image.qcow2

    The command produces both the container image (localhost/my-image:latest) and the disk image (my-image.qcow2).

  2. Boot the image. Boot the disk image in Automotive Image Runner:

    console $ air --nographics my-image.qcow2

Update a running system

Because aib build produces a standard bootc container image, you can push the image to a container registry and use it to update running systems over the air (OTA).

To switch a running system to a new image from a registry, use the following command:

$ bootc switch <registry>/<image>:<tag>

where:

<registry> : Specifies the container registry hostname (for example, quay.io).

<image> : Specifies the repository and image name (for example, my-org/my-autosd).

<tag> : Specifies the image tag (for example, latest or v1.0).

To update a running system to the latest version of the currently tracked image, use the following command:

$ bootc update
Key bootc build options

The following options are commonly used with the build commands. For a complete list, run aib build --help or aib to-disk-image --help.

  • --target TARGET -- The hardware target board. Run aib list-targets for a complete list of available targets.
  • --distro DISTRO -- The distribution version (default: autosd10-sig). Run aib list-distro for a complete list of available distributions.
  • --format {raw,qcow2,simg} -- The disk image format. If no format is specified, the default is inferred from the file extension you provide in the file name.
  • --separate-partitions -- Split the disk image into per-partition files.
  • --oci-archive -- Produce an OCI archive file instead of storing the image in Podman storage.
  • --build-container IMAGE -- Override the builder image name. The default name is localhost/aib-build:$DISTRO.
Next steps