Chapter 4. Composing a RHEL for Edge image using Image Builder command-line

Use Image Builder to create a custom RHEL for Edge image (OSTree commit).

To access Image Builder and to create your custom RHEL for Edge image, you can either use the RHEL web console interface or the command-line interface.

This chapter provides information about creating RHEL for Edge images using the CLI. To create RHEL for Edge images using RHEL web console, see, Chapter 3, Composing a RHEL for Edge image using Image Builder in RHEL web console.

For Network-based deployments, the workflow to compose RHEL for Edge images using the CLI, involves the following high-level steps:

  1. Create a blueprint for RHEL for Edge image
  2. Create a RHEL for Edge image
  3. Download the RHEL for Edge image

To perform the steps, use the composer-cli package.

Note

To run the composer-cli commands as non-root, you must be part of the weldr group or you must have administrator access to the system.

For Non-Network-based deployments, the workflow to compose RHEL for Edge images using the CLI, involves the following high-level steps:

  1. Create a blueprint for RHEL for Edge image
  2. Create a RHEL for Edge Container image
  3. Create an empty RHEL for Edge Installer image
  4. Download the RHEL for Edge image

4.1. Creating a RHEL for Edge image blueprint using Image Builder command-line interface

To create a blueprint for RHEL for Edge image, perform the following steps:

Procedure

  1. Create a plain text file in the Tom’s Obvious, Minimal Language (TOML) format, with the following content: 

    name = "blueprint-name"
description = "blueprint-text-description"
version = "0.0.1"
modules = [ ]
groups = [ ]

    Where,

    • blueprint-name is the name and blueprint-text-description is the description for your blueprint.
    • 0.0.1 is the version number according to the Semantic Versioning scheme.

    • Modules describe the package name and matching version glob to be installed into the image, for example, the package name = "tmux" and the matching version glob is version = "2.9a".

      Notice that currently there are no differences between packages and modules.

    • Groups are packages groups to be installed into the image, for example the group package anaconda-tools.

      At this time, if you do not know the modules and groups, leave them empty.

  2. Include the required packages and customize the other details in the blueprint to suit your requirements.

    For more information about the packages that you can include and customize in a blueprint, see Supported Image Customizations.

    For every package that you want to include in the blueprint, add the following lines to the file: 

    [[packages]]
name = "package-name"
version = "package-version"

    Where,

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

    • package-version is the version number of the package that you want to use.

      The package-version supports the following dnf version specifications:

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

  3. Push (import) the blueprint to the Image Builder server: 

    # composer-cli blueprints push blueprint-name.toml

  4. List the existing blueprints to check whether the created blueprint is successfully pushed and exists. 

    # composer-cli blueprints show BLUEPRINT-NAME

  5. Check whether the components and versions listed in the blueprint and their dependencies are valid: 

    # composer-cli blueprints depsolve blueprint-name

4.2. Creating a RHEL for Edge image using Image Builder command-line interface

To create a RHEL for Edge image using Image Builder command line interface, ensure that you have met the following prerequisites and then follow the procedure.

Prerequisites

  • You have created a blueprint for RHEL for Edge image.

Procedure

  1. Begin to create the RHEL for Edge image. 

    # composer-cli compose start-ostree --ref rhel/8/x86_64/edge --url URL-OSTree-repository blueprint-name image-type

    Where,

  2. Check the image compose status. 

    # composer-cli compose status

    The output displays the status in the following format: 

    <UUID> RUNNING date blueprint-name blueprint-version image-type
    Note

    The image creation process takes a few minutes to complete.

    To interrupt the image creation process, run: 

    # composer-cli compose cancel <UUID>

    To delete an existing image, run: 

    # composer-cli compose delete <UUID>

4.3. Creating a RHEL for Edge Installer image using command-line interface for non-network-based deployments

To create a RHEL for Edge Installer image that embeds the OSTree commit, using Image Builder command-line interface, ensure that you have met the following prerequisites and then follow the procedure.

Prerequisites

  • You have created an empty blueprint for RHEL for Edge image.

    An empty blueprint has no customizations, that is, no added packages and created users. The added packages and created users are pulled from the repository that is used to build the ISO image.

Procedure

  1. Begin to create the RHEL for Edge image. 

    # composer-cli compose start-ostree --ref rhel/8/x86_64/edge --url URL-OSTree-repository blueprint-name image-type

    Where,

    • ref is the same value that customer used to build ostree repository
    • URL-OSTree-repository is the URL to the OSTree repository of the commit to embed in the image. For example, http://10.0.2.2:8080/repository/. See Section 5.2, “Setting up a web server to install RHEL for Edge image”
    • blueprint-name is the RHEL for Edge blueprint name.

    • image-type is rhel-edge-installer.

      A confirmation that the composer process has been added to the queue appears. It also shows a Universally Unique Identifier (UUID) number for the image created. Use the UUID number to track your build. Also keep the UUID number handy for further tasks.

  2. Check the image compose status. 

    # composer-cli compose status

    The command output displays the status in the following format: 

    <UUID> RUNNING date blueprint-name blueprint-version image-type
    Note

    The image creation process takes a few minutes to complete.

    To interrupt the image creation process, run: 

    # composer-cli compose cancel <UUID>

    To delete an existing image, run: 

    # composer-cli compose delete <UUID>

4.4. Creating a RHEL for Edge image update with a parent commit using Image Builder command-line interface

If you performed a change in an existing blueprint, for example, you added a new package, and want to update an existing RHEL for Edge image with this new package, you can use a parent commit ID to generate an updated RHEL for Edge Commit (.tar) image.

To create a RHEL for Edge image with a parent commit using Image Builder command line interface, ensure that you have met the following prerequisites and then follow the procedure.

Prerequisites

Procedure

  1. Create the RHEL for Edge image. 

    # composer-cli compose start-ostree --ref rhel/8/x86_64/edge --parent parent-OSTree-commit-id blueprint-name image-type

    Where,

    • --ref is the same value used by to build ostree repository
    • --parent is the OSTree parent commit
    • blueprint-name is the RHEL for Edge blueprint name.

    • image-type is rhel-edge-commit for network-based deployment

      Note

      The --parent argument can only be used for RHEL for Edge Commit (.tar) image type. Using the --url and --parent arguments together results in errors.

      A confirmation that the composer process has been added to the queue appears. It also shows a Universally Unique Identifier (UUID) number for the image created. Use the UUID number to track your build. Also keep the UUID number handy for further tasks.

      For more information about supported image types, refer to the Creating a system image with Image Builder in the command-line interface .

  2. Check the image compose status. 

    # composer-cli compose status

    The output displays the status in the following format: 

    <UUID> RUNNING date blueprint-name blueprint-version image-type
    Note

    The image creation process takes a few minutes to complete.

    (Optional) To interrupt the image creation process, run: 

    # composer-cli compose cancel <UUID>

    (Optional) To delete an existing image, run: 

    # composer-cli compose delete <UUID>

After the image creation is complete, to upgrade an existing ostree deployment, you need:

Additional resources

4.5. Downloading a RHEL for Edge image using the Image Builder command-line interface

To download a RHEL for Edge image using Image Builder command line interface, ensure that you have met the following prerequisites and then follow the procedure.

Prerequisites

  • You have created a RHEL for Edge image.

Procedure

  1. Review the RHEL for Edge image status. 

    # composer-cli compose status

    The output must display the following: 

    $ <UUID> FINISHED date blueprint-name blueprint-version image-type

  2. Download the image. 

    # composer-cli compose image <UUID>

    Image Builder downloads the image as a tar file to the current directory.

    The UUID number and the image size is displayed alongside. 

    $ <UUID>-commit.tar: size MB

The image contains a commit and a json file that contains information metadata about the repository content.