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

With RHEL image builder, you can build security hardened images using the OpenSCAP tool. You can take advantage of the support for container customization in the blueprints to 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, you must add a container customization to your blueprint. For example:

source = ""
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. You can specify a tag version. The default tag version is latest.
  • name - The name of the container in the local registry.
  • tls-verify - Boolean field. The tls-verify boolean field controls the transport layer security. The default value is true.

    RHEL 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, such as 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.


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.

For example:

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

Additional resources

  • The containers-auth.json man page

9.3. Pushing a container artifact directly to a container registry

You can push container artifacts, such as RHEL for Edge container images directly, directly to a container registry after you build it, by using the RHEL image builder CLI.


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


  1. Set up a registry-config.toml file to select the container provider. The credentials are optional.

    provider = "container_provider"
    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"
    name = "nginx"
    version = "*"
  3. Push the blueprint:

    # composer-cli blueprints push blueprint.toml
  4. Build the container image, by passing the registry and the repository to the composer-cli tool as arguments.

    # composer-cli compose start simple-container container "" registry-config.toml
    • simple-container - is the blueprint name.
    • container - is the image type.
    • "" - 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.


      Building the container image takes time because of resolving dependencies of the customized packages.

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


  1. Open 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.
  2. 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.



  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"
    name = "podman"
    version = "*"
    source = " 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
    • image is the blueprint name.
    • qcow2 is the image type.


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

  4. To check the status of the compose:

    # composer-cli compose status

    A finished compose shows the FINISHED status value. To identify your compose in the list, use its UUID.

  5. After the compose process is finished, download the resulting image file to your default download location:

    # composer-cli compose image UUID

    Replace UUID with the UUID value shown in the previous steps.

    You can use the qcow2 image you created and downloaded to create a VM.


From the resulting qcow2 image that you downloaded, perform the following steps:

  1. Start the qcow2 image in a VM. See Creating a virtual machine from a KVM guest image.
  2. 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.
  3. Run the container image and open a shell prompt inside the container:

    # podman run -it /bin/bash/ is the target registry, osbuild is the organization and repository is the location to push the container when it finishes building.

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

    # type -a nginx

    The output shows you the nginx package path.