Skip to content

Layering bootc images

Layering bootc images

Follow these procedures to customize an AutoSD bootc image by layering additional packages, files, and configurations using a Containerfile. The layered image can then be converted to a disk image or pushed to a container registry.

Prerequisites
  • A base bootc image built with aib build. For build instructions, see the bootc image building procedure.
  • A builder image created with aib build-builder (required for disk image conversion).
  • Familiarity with the layering concepts described in Bootc image layering.
Procedure

  1. Build a base image. Before layering, you need a base bootc image. If you have not already built one, run aib build with your manifest:

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

    The command stores the container image in local Podman storage. To log in to the final booted image, the manifest must define root credentials in the auth section:

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

    For additional authentication options, see Creating a custom manifest.

  2. Write a Containerfile. Create a Containerfile that references the base image and adds your customizations:

    ```dockerfile FROM localhost/my-base-image

    RUN dnf install -y vim-minimal strace && dnf clean all

    COPY my-config.conf /etc/my-app/config.conf ```

    The FROM directive specifies the base bootc image. Each subsequent instruction adds a new layer. Replace my-config.conf and the destination path with the actual configuration file and target location for your application. Common layering operations include the following directives:

    • RUN dnf install to add packages
    • COPY or ADD to include configuration files or scripts
    • RUN to execute setup commands (for example, enabling a systemd service)

    Note

    The dnf package manager must be present in the base image for RUN dnf install to work. Not all manifests include dnf by default. If the base image lacks dnf, the build fails with dnf: command not found. To include dnf, add it to the manifest content.rpms list:

    yaml content: rpms: - dnf

    If a prebuilt AutoSD bootc base image is available from a container registry, you can replace the local image reference with the registry URL:

    dockerfile FROM registry.example.com/autosd/my-base-image:latest

  3. Build the layered image. Build the layered image from the Containerfile:

    console $ sudo podman build -t localhost/my-layered-image -f Containerfile .

    The sudo prefix is required because aib build stores the base image in the root container storage. Building the layered image requires network access to resolve any repositories configured in the base image. If the container build cannot reach the repositories, add --network host to use the host network stack:

    console $ sudo podman build --network host -t localhost/my-layered-image -f Containerfile .

  4. Verify the layered image. Confirm that the layered image was created:

    console $ sudo podman images | grep my-layered-image

    To inspect the image contents without converting to a disk image, run the following command:

    console $ sudo podman run --rm -it localhost/my-layered-image rpm -q vim-minimal

  5. Convert to a disk image. Convert the layered image to a bootable disk image using aib to-disk-image. As already noted in the prerequisites, the builder image must already exist.

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

    The output format is inferred from the file extension. To set the format explicitly, use --format <format> as shown in the following example:

    console $ aib to-disk-image \ --format raw \ localhost/my-layered-image \ my-layered-image.img

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

    console $ air --nographics my-layered-image.img

    Log in as root using the password defined in the manifest auth section.

Deploying the layered image

After building and verifying the layered image (step 4), you can deploy it through one of the following paths.

Deploy as a disk image

Convert the layered image to a bootable disk image with aib to-disk-image (steps 5-6 above), then boot it in a VM with air or flash it onto hardware. For hardware flashing instructions, see Provisioning hardware.

Deploy as an OTA update

Push the layered image to a container registry and update running systems with bootc switch or bootc update. The disk image conversion step is not needed for this path.

For the full push-and-update workflow, see the registry workflows procedure.

Key considerations

When layering bootc images, keep the following important points in mind:

  • The layered image inherits the kernel, target configuration, and partition layout from the base image. Layered changes affect only the root filesystem content.
  • Packages installed through dnf install in the Containerfile must be available in the repositories configured in the base image.
  • The manifest auth section in the base image defines the login credentials for the final booted image. The Containerfile does not override these settings unless the layered instructions explicitly modify the relevant files.
  • Each layer added by the Containerfile increases the container image size. Combine related RUN instructions and clean package caches (for example, run dnf clean all) to help minimize image size.
Next steps