Chapter 5. Using Image Builder to create system images from different releases

You can use Image Builder to create images of multiple RHEL minor releases that are different from the host, such as RHEL 8.4 and RHEL 8.5. 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:

    $ curl --unix-socket /run/weldr/api.socket http://localhost/api/v1/distros/list

    The output shows you a JSON string that lists the supported release distribution names:


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

5.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 CLI, you must set the new 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_84"
description = "A 8.5 base image"
version = "0.0.1"
modules = []
groups = []
distro = "rhel-84"

By attributing “rhel-84” to the distro field, you ensure that it always builds a RHEL 8.2 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.4 base image"
    version = "0.0.1"
    modules = []
    groups = []
    distro = "rhel-84"
  2. Save the file and close the editor.
  3. Push (import) the blueprint back into 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. Notice that this may take several minutes.

  5. Check the status of the compose:

    # composer-cli compose status

    Once 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.

5.2. Using system repositories with specific distributions

You can specify a list of distribution strings that the system repository source uses when depsolving and building images. For that, see the following example:


  1. Create a JSON file with the following structure, 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