Red Hat Training

A Red Hat training course is available for RHEL 8

Chapter 6. Using RHEL image builder to create system images from different releases

You can use RHEL image builder to create images of multiple RHEL minor releases that are different from the host, such as RHEL 8.8 and RHEL 8.7. For that, you can add source system repositories with the release distribution fields set and also, you can create blueprints with the correct release distribution fields set.

Additionally, if you have existing blueprint or source system repositories in an old format, you can create new blueprints with the correct release distribution fields set.

  • To list the supported release distribution, you can run the following command:

    $ composer-cli distros list

    The output shows you a list with supported release distribution names:


    Cross-distribution image building, such as building a CentOS image on RHEL is not supported.

6.1. Creating an image with a different distribution in the CLI

To select the distribution you want to use when composing an image in the RHEL image builder CLI, you must set the distro field in the blueprint. For that, follow the steps:


If you are creating a new blueprint
  1. Create a blueprint. For example:
name = "<blueprint_name>"
description = "<image-description>"
version = "0.0.1"
modules = []
groups = []
distro = "<distro-version>"

By setting the distro field to “rhel-88”, you ensure that it always builds a RHEL 8.8 image, no matter which version is running on the host.


If the distro field is blank, it uses the same distribution of the host.

If you are updating an existing blueprint
  1. Save (export) the existing blueprint to a local text file:
# composer-cli blueprints save EXISTING-BLUEPRINT
  1. Edit the existing blueprint file with a text editor of your choice, setting the distro field with the distribution of your choice, for example:

    name = "blueprint_84"
    description = "A 8.8 base image"
    version = "0.0.1"
    modules = []
    groups = []
    distro = "rhel-88"
  2. Save the file and close the editor.
  3. Push (import) the blueprint back into RHEL image builder:

    # composer-cli blueprints push EXISTING-BLUEPRINT.toml
  4. Start the image creation:

    # composer-cli compose start BLUEPRINT-NAME IMAGE-TYPE

    Wait until the compose is finished.

  5. Check the status of the compose:

    # composer-cli compose status

    After the compose finishes, it shows a FINISHED status value. Identify the compose in the list by its UUID.

  6. Download the resulting image file:

    # composer-cli compose image UUID

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

6.2. Using system repositories with specific distributions

You can specify a list of distribution strings that the system repository source uses when resolving dependencies and building images. For that, follow the step:


  • Create a TOML file with the following structure, for example:

    check_gpg = true
    check_ssl = true
    distros = ["<distro-version>"]
    id = "<image-id>"
    name = "<image-name>_"
    system = false
    type = "<image-type>"
    url = "\http://local/repos/rhel-<distro-version>_/<project-repo>/"

    For example:

    check_gpg = true
    check_ssl = true
    distros = ["rhel-84"]
    id = "rhel-84-local"
    name = "local packages for rhel-84"
    system = false
    type = "yum-baseurl"
    url = "\http://local/repos/rhel-84/projectrepo/"

Additional resources