Pushing and updating bootc images with a container registry

Pushing and updating bootc images with a container registry

Follow these procedures to push a bootc container image to a registry and update running systems from the registry.

For background on the registry-centric update model, see Registry interactions.

Prerequisites

Before you begin, verify that you have the following:

• Podman installed. See the Podman installation guide for instructions.
• Automotive Image Builder installed. See Installing Automotive Image Builder for instructions.

• A bootc container image built with aib build. See the bootc image building procedure for instructions.
• Access to a container registry, for example Quay.io, a private registry, or an OpenShift internal registry.
• skopeo installed if you plan to push OCI archives. Most Linux distributions include skopeo in their default repositories.

Push an image to a registry from local storage

Use this workflow when aib build stored the image in local Podman storage (the default behavior).

1. Tag the image for the registry. Assign a registry-qualified name and version tag to the locally built image:

   console $ sudo podman tag localhost/my-image registry.example.com/autosd/my-image:v1.0

   Replace registry.example.com/autosd/my-image with your registry path and v1.0 with the desired version tag.

2. Authenticate with the registry. Log in to the target registry:

   console $ sudo podman login registry.example.com

   Enter your username and password when prompted. Podman stores the credentials for subsequent operations.

3. Push the image to the registry. Upload the tagged image:

   console $ sudo podman push registry.example.com/autosd/my-image:v1.0

4. Verify the push. Confirm that the image is available in the registry:

   console $ skopeo inspect docker://registry.example.com/autosd/my-image:v1.0

   The output displays the image metadata including digest, layers, and creation timestamp.

Push an OCI archive to a registry

Use this workflow when the image was built with --oci-archive and saved to a file rather than local Podman storage.

1. Authenticate with the registry. Log in to the target registry if you have not already done so:

   console $ podman login registry.example.com

2. Copy the OCI archive to the registry. Use skopeo copy to upload the archive:

   console $ skopeo copy \ oci-archive:my-image.oci \ docker://registry.example.com/autosd/my-image:v1.0

   Replace my-image.oci with the path to the OCI archive file.

3. Verify the push. Confirm that the image is available in the registry:

   console $ skopeo inspect docker://registry.example.com/autosd/my-image:v1.0

Update a running system

After pushing an image to a registry, you can update devices that run AutoSD bootc images. Run the following commands on the target device. Access the device by SSH or serial console. For virtual machines launched with air, connect over SSH with ssh -p 2222 root@localhost. SSH access requires that the OS image be built from a manifest that enables PasswordAuthentication in sshd_config through the auth section.

1. Switch to a new image. To change the image a device tracks, run:

   console $ bootc switch registry.example.com/autosd/my-image:v1.0

   The command stages the new image for the next reboot. Use bootc switch when deploying a different image or changing the registry reference.

2. Update to the latest version. To pull the latest version of the currently tracked image, run:

   console $ bootc update

   The command downloads and stages any available update. Use bootc update for routine updates when the device already tracks the correct image.

3. Check the current status. To view the booted image, any staged update, and tracking information, run:

   console $ bootc status

4. Reboot to apply the update. The staged image takes effect after a reboot:

   console $ systemctl reboot

   If the new image fails to boot, the system automatically rolls back to the previous image.

Key considerations

Keep these important points in mind when working with bootc OS images and container registries:

• Tagging strategy: Use semantic versions (for example, v1.0, v1.1) or timestamps rather than relying on the latest tag alone. Explicit version tags make it easier to track which image each device runs.
• Registry storage and bandwidth: Bootc OS images are typically larger than application containers. Plan registry storage capacity and network bandwidth for the expected number of devices pulling updates.
• Signed images: If the image was built with secure boot signing enabled (composefs sealed), complete the signing workflow before pushing to the registry. Devices that enforce signature verification reject unsigned or incorrectly signed images.