Create system images by using the RHEL image builder CLI

RHEL image builder is a tool for creating custom system images. To control RHEL image builder and create your custom system images, you can use the command line (CLI) or the web console interface.

The RHEL image builder command-line interface
Copy link

You can use the RHEL image builder command-line interface (CLI) to create blueprints, by running the image-builder command with the suitable options and subcommands.

By default, you must run the image-builder command as a root user.

The workflow for the command line can be summarized as follows:

  1. Create a blueprint or export an existing blueprint definition to a plain text file.
  2. Optional: Edit this file in a text editor.
  3. Import the blueprint text file back into image builder.
  4. Run a compose to build an image from the blueprint.
  5. Export the image file to download it.

Apart from the basic subcommands to create a blueprint, you can use the image-builder command with many subcommands to examine the state of configured blueprints and composes.

RHEL image builder blueprint format
Copy link

With RHEL image builder, you can use blueprints in both the .toml and .json formats.

A typical blueprint file includes the following elements:

The blueprint metadata
name = "<blueprint_name>"
description = "<long_form_description_text>"
version = "<version>"

The <blueprint_name> and <long_form_description_text> fields are the name and description for your blueprint.

The <version> is a version number according to the Semantic Versioning scheme, and is present only once for the entire blueprint file.

Groups to include in the image
[[groups]]
name = "<group_name>"

The <group_name> entry describes a group of packages to be installed into the image. Groups use the following package categories:

  • Mandatory
  • Default
  • Optional

    The group-name is the name of the group, for example, anaconda-tools, widget, wheel, or users. Blueprints install the mandatory and default packages. There is no mechanism for selecting optional packages.

Packages to include in the image
[[packages]]
name = "<package_name>"
version = "<package_version>"

package-name is the name of the package, such as httpd, gdb-doc, or coreutils.

package-version is a version to use. In this field, you can specify ‎dnf version constraints as follows:

  • For a specific version, use the exact version number, such as 8.7.0.
  • For the latest available version, use the asterisk *.
  • For the latest minor version, use a format such as 8.*.

    Repeat this block for every package to include.

    Note
    There are no differences between packages and modules in the RHEL image builder tool. RHEL image builder treats both as RPM Package Manager (RPM) package dependencies.

Create a blueprint by using the command line
Copy link

You can create a new blueprint by using the command line (CLI). The blueprint describes the final image and its customizations, such as packages and kernel customizations.

Before you begin
Copy link

  • You are logged in as the root user or a user who is a member of the weldr group

Procedure
Copy link

  1. Create a plain text file with the following contents: 
    name = "<blueprint_name>"
description = "<long_form_description>"
version = "<0.0.1>"
modules = []
groups = []

    Replace <blueprint_name> and <long_form_description> with a name and description for your blueprint.

    Replace <0.0.1> with a version number according to the Semantic Versioning scheme.

  2. For every package that you want to be included in the blueprint, add the following lines to the file: 
    [[packages]]
name = "<package_name>"
version = "<package_version>"

    Replace <package_name> with the name of the package, such as httpd, gdb-doc, or coreutils.

    Optionally, replace <package_version> with the version to use. This field supports dnf version specifications:

    • For a specific version, use the exact version number such as 9.6.0.
    • For the latest available version, use the asterisk *
    • For the latest minor version, use formats such as 9.*.
  3. Customize your blueprints to suit your needs. For example, disable Simultaneous Multi Threading (SMT), add the following lines to the blueprint file: 
    [customizations.kernel]
append = "nosmt=force"

    For additional customizations available, see Supported image customizations.

    Note that [] and [[]] are different data structures expressed in TOML.

    • The [customizations.kernel] header represents a single table that defines collection of keys and their corresponding value pairs, for example: append = "nosmt=force".
    • The [[packages]] header represents an array of tables. The first instance defines the array and its first table element, such as name = "package-name" and version = "package-version". Each subsequent instance adds a new element in the order that you define them.
  4. Save the file, for example, as <blueprint_name>.toml and close the text editor.

Create a system image with RHEL image builder on the command line
Copy link

To build a customized RHEL image by using the RHEL image builder command-line interface, you must specify a blueprint and an image type. Optionally, you can also specify a distribution.

Before you begin
Copy link

  • You have a blueprint prepared for the image.

About this task
Copy link

If you do not specify a distribution, it uses the same distribution and version as the host system. The architecture is also the same as the one on the host.

Procedure
Copy link

  1. Optional: List the image formats you can create: 
    # image-builder list
  2. Start the compose: 
    # image-builder build <image_type> --blueprint <blueprint_name>
    • Replace <blueprint_name> with the name of the blueprint, and <image_type> with the type of the image.
    • If you do not specify a distro, image-builder uses the same distribution and version as the host system.

Results
Copy link

The compose process takes some minutes to complete. You can follow the image building steps until the image is ready.

After the image building process finishes, the image is available for your use at the directory where you create it.

Basic RHEL image builder command-line commands
Copy link

Use the RHEL image builder command-line interface to run these basic image-builder commands.

List all available images
# image-builder list
Filter images by name
# image-builder list-images --filter "rhel"
Filter by distribution and architecture
# image-builder list-images --filter "distro:rhel-10" --filter "arch:s390x"
Note

The --filter argument does not support multiple key:value pairs within a single expression. To combine multiple filters and narrow down your results, pass each filter individually using a separate --filter flag.
Change output format
# image-builder list-images --filter "distro:rhel-10" --format=json | jq
 
# image-builder list-images --filter "distro:rhel-10" --format=shell
Building images
# image-builder build <image-type>

<image-type> is the image type supported for RHEL image builder, such as qcow2, wsl, and so on.

Specify a distribution
# image-builder build <image-type> --distro <distro>
Show the progress of the image creation and detailed steps
# image-builder build <image-type> --distro <distro>  --with-buildlog
Cross-architecture build
# image-builder build <image-type> --arch=riscv64
Add a custom repository to the build
# image-builder build <image-type> --extra-repo=<file:///path/to/my/repo>

Enabled services on custom images
Copy link

When you configure a custom image by using RHEL image builder to the RHEL version and image type determine the default services that the image uses.

For example, use the ami image type to enable the sshd, chronyd, and cloud-init services by default. If these services are not enabled, the custom image does not boot.

Table 1. Enabled services to support image type creation
Image type Default enabled Services

ami

sshd, cloud-init, cloud-init-local, cloud-config, cloud-final

openstack

sshd, cloud-init, cloud-init-local, cloud-config, cloud-final

qcow2

cloud-init

tar

Do not enable extra services by default

vhd

sshd, chronyd, waagent, cloud-init, cloud-init-local, cloud-config, cloud-final

vmdk

sshd, chronyd, vmtoolsd, cloud-init
Note
You can customize which services to enable during the system boot. However, the customization does not override services enabled by default for the mentioned image types.