Red Hat Training

A Red Hat training course is available for RHEL 8

Chapter 9. Pushing a container to a registry and embedding it into an image

With support for container customization in the blueprints, you can create a container and embed it directly into the image you create.

9.1. Blueprint customization to embed a container into an image

To embed a container from registry.access.redhat.com registry, you must add a container customization to your blueprint. For example: 

[[containers]]
source = "registry.access.redhat.com/ubi9/ubi:latest"
name =  "local-name"
tls-verify = true
  • source - Mandatory field. It is a reference to the container image at a registry. This example uses the registry.access.redhat.com registry. You can specify a tag version. The default tag version is latest.
  • name - the name of the container in the local registry.

  • tls-verify - Optional boolean field. The tls-verify boolean field controls the transport layer security. The default value is true.

    Image builder pulls the container during the image build and stores the container into the image. The default local container storage location depends on the image type, so that all support container-tools like Podman are able to work with it. The embedded containers are not started. To access protected container resources, you can use a containers-auth.json file.

9.2. The Container registry credentials

The osbuild-worker service is responsible for the communication with the container registry. To enable that, you can set up the /etc/osbuild-worker/osbuild-worker.toml configuration file.

Note

After setting the /etc/osbuild-worker/osbuild-worker.toml configuration file, you must restart the osbuild-worker service, because it reads the /etc/osbuild-worker/osbuild-worker.toml configuration file only once, during the osbuild-worker service start.

The /etc/osbuild-worker/osbuild-worker.toml configuration file has a containers section with an auth_field_path entry that is a string referring to a path of a containers-auth.json file to be used for accessing protected resources. The container registry credentials are only used to pull a container image from a registry, when embedding the container into the image.

The following is an example: 

[containers]
auth_file_path = "/etc/osbuild-worker/containers-auth.json"

Additional resources

9.3. Pushing a container artifact directly to a container registry

You can push container artifacts, such as RHEL for Edge container images directly to a container registry after you build it, using the image builder CLI. For that you must set up an upload provider and optionally, credentials, and then you can build the container image, passing the registry and the repository to composer-cli as arguments. After the image is ready, it is available in the container registry that you set up.

Prerequisites

  • Access to quay.io registry. This example uses the quay.io container registry as a target registry, but you can use a container registry of your choice.

Procedure

  1. Set up a registry-config.toml file to select the container provider. 

    provider = "container_provider"

[settings]
tls_verify = false
username = "admin"
password = "your_password"

  2. Create a blueprint in the .toml format. This is a blueprint for the container in which you install an nginx package into the blueprint. 

    name = "simple-container"
description = "Simple RHEL container"
version = "0.0.1"

[[packages]]
name = "nginx"
version = "*"

  3. Push the blueprint: 

    # composer-cli blueprints push blueprint.toml

  4. Build the container image: 

    # composer-cli compose start simple-container container "quay.io:8080/osbuild/repository" registry-config.toml
    • simple-container - is the blueprint name.
    • container - is the image type.

    • "quay.io:8080/osbuild/repository" - quay.io is the target registry, osbuild is the organization and repository is the location to push the container when it finishes building. Optionally, you can set a tag. If you do not set a value for :tag, it uses :latest tag by default.

      Note

      Building the container image takes time because of depsolving the customized packages.

  5. After the image build finishes, the container you created is available in quay.io.

  6. Access quay.io. and click Repository Tags. 

     You can see details about the container you created, such as:
- last modified
- image size
- the `manifest ID`, that you can copy to the clipboard.
  7. Copy the manifest ID value to build the image in which you want to embed a container.

Additional resources

9.4. Building an image and pulling the container into the image

After you have created the container image, you can build your customized image and pull the container image into it. For that, you must specify a container customization in the blueprint, and the container name for the final image. During the build process, the container image is fetched and placed in the local Podman container storage.

Prerequisites

  • You created a container image and pushed it into your local quay.io container registry instance.
  • You have access to registry.access.redhat.com.
  • You have a container manifest ID.

  • You have the qemu-kvm and qemu-img packages installed. To install it, run the command: 

    # yum install qemu-kvm qemu-img

Procedure

  1. Create a blueprint to build a qcow2 image. The blueprint must contain the customization. 

    name = "image"
description = "A qcow2 image with a container"
version = "0.0.1"
distro = "rhel-90"

[[packages]]
name = "podman"
version = "*"

[[containers]]
source = "registry.access.redhat.com/ubi9:8080/osbuild/container/container-image@sha256:manifest-ID-from-Repository-tag: tag-version"
name =  "source-name"
tls-verify = true

  2. Push the blueprint: 

    # composer-cli blueprints push blueprint-image.toml

  3. Build the container image: 

    # composer-cli start compose image qcow2

    Where:

    • image is the blueprint name.

    • qcow2 is the image type.

      Note

      Building the image takes time because it checks the container on quay.io registry.

      After the image build status is "FINISHED", you can use the qcow2 image you created in a VM.

Verification

  1. Pull the .qcow2 image from the composer-cli to your local file system: 

    # composer-cli compose image COMPOSE-UUID
  2. Start the qcow2 image in a VM. See Creating a virtual machine from a KVM guest image.

  3. The qemu wizard opens. Login in to the qcow2 image.

    1. Enter the username and password. These can be the username and password you set up in the .qcow2 blueprint in the "customizations.user" section, or created at boot time with cloud-init.

  4. Run the container image and open a shell prompt inside the container: 

    # podman run -it registry.access.redhat.com/ubi9:8080/osbuild/repository /bin/bash/

    Where:

    • registry.access.redhat.com is the target registry, osbuild is the organization and repository is the location to push the container when it finishes building.

  5. Check that the packages you added to the blueprint are available: 

    # type -a nginx

    The output shows you the nginx package path.

Additional resources