Chapter 5. Building customized RHEL images

You can use a blueprint to build customized RHEL images for a variety of deployment types by using Insights Images. You can build Conventional (RPM-DNF) images or Immutable (OSTree) images.

5.1. About building customized images

You can build either Conventional (RPM-DNF) images or Immutable (OStree) images from a blueprint.

  • The Conventional (RPM-DNF) enables you to manage or modify the system software by using the DNF package manager and updated RPM packages.
  • The Immutable (OStree) images contain a complete operating system ready to be remotely installed and allows you to manage the system software by referencing a central image repository. For more details, see Create RHEL for Edge images and configure automated management.

When creating a blueprint, you can perform any of the following customizations:

  • Select the cloud target environment to launch the instances.
  • Choose to automatically register and enable advanced capabilities to the system images, such as:

    • Red Hat Insights, to identify and address operational and vulnerability risks.
    • Remote host configuration (rhc), to enable remote remediations and system management with automation.
    • Optionally, you can manually register your systems later, with rhc. See Remote Host Configuration and Management.
  • Define the system images with a specific file system customization.
  • Select packages from Red Hat and third-parties.

The image artifacts are saved for 14 days and expire after that. To avoid losing the image, transfer the image to your account before the expiration date. If an image has already expired, you can also re-create the exact image based on an existing blueprint to reuse the previous configuration.

You can share an existing AWS image to a new region to run on your AWS account so that all regions can launch with the same configuration.

You can also download the compose request of your image and use the image builder API to automate your image building tasks.

5.2. Copying your customized RHEL system image for AWS to a different region on your AWS EC2

You can copy the image you successfully shared with the Amazon Web Services EC2 to your own account. Doing so, you grant that the image you shared and copied is available until you delete it, instead of expiring after some time. To copy your image to your own account, follow the steps:


  • You have access to your customized image on AWS.


  1. From the list of Public images, select the image you want to copy.
  2. On the top of the panel, click Actions.
  3. From the dropdown menu, choose Copy AMI. A popup window appears.
  4. Choose the Destination region and click Copy AMI.

    After the copying process is complete, you are provided with the new AMI ID. You can launch a new instance in the new region.


    When you copy an image to a different region, it results in a separate and new AMI in the destination region, with a unique AMI ID.

5.3. Authorizing image builder to push images to Microsoft Azure Cloud

To push a RHEL image to the Microsoft Azure target environment, you must authorize Image Builder to push images to the Microsoft Azure cloud. The authorization consists of the following steps:

  • Configure Insights Images as an authorized application for your tenant GUID
  • Give it the role of Contributor to at least one resource group.

    To authorize Image Builder as an authorized application, follow the steps:


  • You have an existing Resource Group in Microsoft Azure portal.
  • You have the User Access Administrator role rights.
  • Your Microsoft Azure subscription has Microsoft.Storage and Microsoft.Compute as a resource provider.


  1. Access Hybrid Cloud Console.
  2. Click Red Hat Insights > RHEL > Inventory > Images.

    The Insights Images dashboard appears.

  3. Click Create image.

    The Create image dialog wizard opens.

On the Image output page, complete the following steps:

  1. From the Release list, select the release that you want to use.
  2. From the Select target environments option, select Microsoft Azure.

    Click Next.

    1. On the Target Environment - Microsoft Azure window, to add Image Builder as an authorized application, complete the following steps:
  3. Insert your Tenant GUID.

    Images checks if your Tenant GUID is correctly formatted and the Authorize image builder button becomes available.

  4. Click Authorize image builder to authorize Insights Images to push images to the Microsoft Azure cloud.

    This redirects you to the Microsoft Azure portal.

    1. Login with your credentials.
    2. Click Accept the Permission requested.
  5. Confirm that Image Builder is authorized for your tenant.

    1. Search for Azure Active Directory and choose Enterprise applications, from the left menu.
    2. Search for Image Builder and confirm it is authorized.
  6. Add the Enterprise application as a contributor to your Resource Group.

    1. In the search bar, type Resource Groups and select the first entry under Services. This redirects you to the Resource Groups dashboard.
    2. Select your Resource Group.
    3. On the left menu, click Access control (IAM) to add a permission so the Image Builder application can access your resource group.
    4. From the menu, click the tab Role assignments.
    5. Click +Add.
    6. From the dropdown menu, choose Add role assignment. A menu appears on the left side.
    7. Enter the following details:

      1. Role: Assign the Contributor role
      2. Assign access to: User, group, service principal. Add members: Click +Select members and type Red Hat in the search bar. Click enter.
      3. Select: Image Builder application

The Image Builder application is now authorized to push images to Microsoft Azure cloud.


Even though any user can add an application to the resources group, the application is not able to locate any resource unless the account administrator adds the shared application as a contributor under the IAM section of the resource group.


  • From the menu, click the tab Role assignments.

    You can see Insights image builder set as a Contributor of the Resource Group you selected.

5.4. Copying the GCE image to your project group

You can create a Virtual Machine (VM) instance using the GCE image.


  • The universally unique identifier (UUID) of the image you created.
  • Access to the Image-builder service API endpoint.
  • Access to the Google Cloud Shell from your browser.


  1. From the Images dashboard, copy the UUID image of the image you created.
  2. Access /composes/{composeId} API endpoint.
  3. Click the Try it Out button to activate the composeId string path.
  4. Enter the UUID into the composes/{composeId} field in the API endpoint.
  5. Click Execute. The API endpoint generates a response in the Response body, for example:

      "image_status": {
        "status": "success",
        "upload_status": {
          "options": {
            "image_name": "composer-api-03f0e19c-0050-4c8a-a69e-88790219b086",
            "project_id": "red-hat-image-builder"
          "status": "success",
          "type": "gcp"
  6. From the Response body field, copy the image_name and project_id to access the image from the Google Cloud Platform environment. From the Response body:

    "image_name": "composer-api-03f0e19c-0050-4c8a-a69e-88790219b086",
    "project_id": "red-hat-image-builder"
  7. From your browser, access Google Cloud Shell.
  8. Set your Google Cloud Platform Project ID as the default GCP project. You can find the Product ID of your project by accessing the Google Cloud Platform dashboard.

    $ gcloud config set project PROJECT_ID
  9. In the Authorize Cloud Shell window prompt, click Authorize to allow this and future calls that require your credentials.
  10. Copy the image to your project by using the gcloud command:

    $ gcloud compute images create MY_IMAGE_NAME \
      --source-image-project red-hat-image-builder \
      --source-image IMAGE_NAME


    • MY_IMAGE_NAME is the name you give to your instance;
    • red-hat-image-builder is the project_id generated by Response body;
    • IMAGE_NAME is the image_name generated by Response body;


Confirm that the image has been successfully copied to your project:

  • Using the Google Cloud Platform UI, by accessing the Compute Engine / Images section.
  • Using the gcloud tool, by running the command in Google Cloud Shell:

    $ gcloud compute images list --no-standard-images

Additional resources

5.5. Creating a new image from an existing build

You can create a new image from an existing customized RHEL image by using Insights Images. The Insights Images re-creates the exact image, with a different UUID, which you can use to identify the image in the Hybrid Cloud Console. The new image also fetches package updates and refreshes the content with those updates. You can customize this new image to fit your requirements.


You can re-create images from failed builds.


  • You created an AWS image with Insights Images.


  1. From the Images dashboard, select the image from which you want to create your customized image.
  2. Click the Node options menu (⫶) and select Re-create image. The Create image wizard opens.


    If the image status is Expired, click the Re-create image button.

    1. Optional: You can customize the new image by using the Navigation panel to open a step and making changes. Click Next.
    2. On the Review page, click Create image.

The Insights Images dashboard opens. The image build starts to re-create the image and lists the following information:

  • Image name
  • UUID
  • Cloud target environment
  • Image operating system release
  • Status of the image creation


  • From the Status column, check if the image is Ready.
  • Optional: Click Image details to display additional information about the re-created image.

5.6. Sharing AWS images to other regions

You can share an existing AWS image to a new region. Sharing the image configures it for the new regions to run on your AWS account. After configuring new regions, all these regions launch with the same configuration as the original AWS image.


  • You created an AWS image.


  1. From the Images table, select the image you want to share with other regions.
  2. From the Node options menu (⫶), select Share to new region. The Share to new region wizard opens.
  3. From the Select region dropdown menu, select the region to share the image.

    You can choose more than one region to share your image with.

  4. Click Share.

    Your image is built, uploaded to AWS, and shared to the regions you selected.


    The shared image expires in 14 days.

  5. To ensure that you can access the image permanently, copy the Red Hat image to your own AWS account.

5.7. Downloading the JSON compose request

If you download the .json compose request of your image, you can use the image builder API to automate your image building tasks, such as:

  • Customizing the image with extra packages
  • Customizing the partition layout
  • Embedding an activation key.


  • You created an image with Insights Images.


  1. From the Images table, select the image that you want to download as a .json compose request.
  2. Click the Node options () menu and select Download compose request (.json).

    The .json compose request is now saved to your host server. To use the image builder API, see Using hosted image builder via its API.