Menu Close

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

You can use Image Builder to create a customized 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.

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 Commit image
  3. Download the RHEL for Edge Commit image

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 a blueprint for the RHEL for Edge Installer image
  4. Create a RHEL for Edge Installer image
  5. 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.

5.1. Network-based deployments workflow

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

To create a blueprint for RHEL for Edge Commit 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 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

Additional resources

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

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

Prerequisites

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

Procedure

  1. Create the RHEL for Edge Commit image.

    # composer-cli compose start blueprint-name image-type

    Where,

    • blueprint-name is the RHEL for Edge blueprint name.
    • image-type is edge-commit for network-based deployment.

      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 output displays the status in the following format:

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

    The image creation process takes up to 20 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>

    After the image is ready, you can download it and use the image on your network deployments.

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

  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:

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

5.2. Non-network-based deployments workflow

5.2.1. Creating a RHEL for Edge Container image blueprint using Image Builder CLI

To create a blueprint for RHEL for Edge Container 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 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

Additional resources

5.2.2. Creating a RHEL for Edge Container image using Image Builder CLI

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

Prerequisites

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

Procedure

  1. Create the RHEL for Edge Container 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 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 Setting up a web server to install RHEL for Edge image.
    • blueprint-name is the RHEL for Edge blueprint name.
    • image-type is edge-container for non-network-based deployment.

      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 output displays the status in the following format:

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

    The image creation process takes up to 20 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>

    After the image is ready, it can be used for non-network deployments.

5.2.3. Creating a RHEL for Edge Installer image blueprint using Image Builder CLI

You can now specify user accounts in the RHEL for Edge Installer blueprint. It creates a user on the system at installation time. To create a blueprint for RHEL for Edge Installer 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-installer"
    description = "blueprint-for-installer-image"
    version = "0.0.1"
    
    [[customizations.user]]
    name = "user"
    description = "account"
    password = "user-password"
    key = "user-ssh-key "
    home = "path"
    groups = ["user-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.
  2. Push (import) the blueprint to the Image Builder server:

    # composer-cli blueprints push blueprint-name.toml
  3. List the existing blueprints to check whether the created blueprint is successfully pushed and exists.

    # composer-cli blueprints show blueprint-name
  4. Check whether the components and versions listed in the blueprint and their dependencies are valid:

    # composer-cli blueprints depsolve blueprint-name

5.2.4. 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 a blueprint for RHEL for Edge Installer image.

    The RHEL for Edge Installer blueprint now supports user accounts.

Procedure

  1. Begin to create the RHEL for Edge Installer 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 Setting up a web server to install RHEL for Edge image.
    • blueprint-name is the RHEL for Edge Installer blueprint name.
    • image-type is 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>

    After the image is ready, you can use it for non-network deployments.

5.2.5. Downloading a RHEL for Edge Installer image using the Image Builder CLI

To download a RHEL for Edge Installer 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 Installer 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 an .iso file to the current directory.

    The UUID number and the image size is displayed alongside.

    $ <UUID>-boot.iso: size MB

The resulting image is a bootable ISO image.

5.3. Additional resources