Chapter 9. Composing a customized RHEL system image

Procedure

1. Create the following directory:

   # mkdir /etc/osbuild-composer/repositories/

   Copy to Clipboard Toggle word wrap

2. Copy the content from the /usr/share/osbuild-composer/repositories/rhel-8.version.json file to the new directory:

   # cp /usr/share/osbuild-composer/repositories/rhel-8.version.json /etc/osbuild-composer/repositories

   Copy to Clipboard Toggle word wrap

3. Edit the /etc/osbuild-composer/repositories/rhel-8.version.json file to include the RT kernel repo:

   # grep -C 6 kernel-rt /etc/osbuild-composer/repositories/rhel-8.version.json
         "baseurl": "https://cdn.redhat.com/content/dist/rhel8/8.version/x86_64/appstream/os",
         "gpgkey": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nm………..=\n=UZd/\n-----END PGP PUBLIC KEY BLOCK-----\n",
         "rhsm": true,
         "check_gpg": true
       },
       {
         "name": "kernel-rt",
         "baseurl": "https://cdn.redhat.com/content/dist/rhel8/8.version/x86_64/rt/os",
         "gpgkey": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nmQINBEr………fg==\n=UZd/\n-----END PGP PUBLIC KEY BLOCK-----\n",
         "rhsm": true,
         "check_gpg": true
       },

   Copy to Clipboard Toggle word wrap

4. Restart the service:

   # systemctl restart osbuild-composer

   Copy to Clipboard Toggle word wrap

5. Confirm that the kernel-rt has been included into the .json file:

   # composer-cli sources list
   # composer-cli sources info kernel-rt

   Copy to Clipboard Toggle word wrap

   You will see the URL that you have previously configured.

6. Create a blueprint. In the blueprint, add the "[customizations.kernel]" customization. The following is an example that contains the "[customizations.kernel]" in the blueprint:

   name = "rt-kernel-image"
   description = ""
   version = "2.0.0"
   modules = []
   groups = []
   distro = "rhel-8_version_"
   [[customizations.user]]
   name = "admin"
   password = "admin"
   groups = ["users", "wheel"]
   [customizations.kernel]
   name = "kernel-rt"
   append = ""

   Copy to Clipboard Toggle word wrap

7. Push the blueprint to the server:

   # composer-cli blueprints push rt-kernel-image.toml

   Copy to Clipboard Toggle word wrap

8. Build your image from the blueprint you created. The following example builds a (.qcow2) image:

   # composer-cli compose start rt-kernel-image qcow2

   Copy to Clipboard Toggle word wrap
9. Deploy the image that you built to the system where you want to use the real time kernel features.

Procedure

1. Install Python 3 and the pip tool:

   # yum install python3 python3-pip

   Copy to Clipboard Toggle word wrap

2. Install the AWS command-line tools with pip:

   # pip3 install awscli

   Copy to Clipboard Toggle word wrap

3. Set your profile. The terminal prompts you to provide your credentials, region and output format:

   $ aws configure
   AWS Access Key ID [None]:
   AWS Secret Access Key [None]:
   Default region name [None]:
   Default output format [None]:

   Copy to Clipboard Toggle word wrap

4. Define a name for your bucket and create a bucket:

   $ BUCKET=bucketname
   $ aws s3 mb s3://$BUCKET

   Copy to Clipboard Toggle word wrap

   Replace bucketname with the actual bucket name. It must be a globally unique name. As a result, your bucket is created.

5. To grant permission to access the S3 bucket, create a vmimport S3 Role in the AWS Identity and Access Management (IAM), if you have not already done so in the past:

   1. Create a trust-policy.json file with the trust policy configuration, in the JSON format. For example:

      {
          "Version": "2022-10-17",
          "Statement": [{
              "Effect": "Allow",
              "Principal": {
                  "Service": "vmie.amazonaws.com"
              },
              "Action": "sts:AssumeRole",
              "Condition": {
                  "StringEquals": {
                      "sts:Externalid": "vmimport"
                  }
              }
          }]
      }

      Copy to Clipboard Toggle word wrap

   2. Create a role-policy.json file with the role policy configuration, in the JSON format. For example:

      {
          "Version": "2012-10-17",
          "Statement": [{
              "Effect": "Allow",
              "Action": ["s3:GetBucketLocation", "s3:GetObject", "s3:ListBucket"],
              "Resource": ["arn:aws:s3:::%s", "arn:aws:s3:::%s/"] }, { "Effect": "Allow", "Action": ["ec2:ModifySnapshotAttribute", "ec2:CopySnapshot", "ec2:RegisterImage", "ec2:Describe"],
              "Resource": "*"
          }]
      }
      $BUCKET $BUCKET

      Copy to Clipboard Toggle word wrap

   3. Create a role for your Amazon Web Services account, by using the trust-policy.json file:

      $ aws iam create-role --role-name vmimport --assume-role-policy-document file://trust-policy.json

      Copy to Clipboard Toggle word wrap

   4. Embed an inline policy document, by using the role-policy.json file:

      $ aws iam put-role-policy --role-name vmimport --policy-name vmimport --policy-document file://role-policy.json

      Copy to Clipboard Toggle word wrap

Procedure

1. Using the text editor, create a configuration file with the following content:

   provider = "aws"
   [settings]
   accessKeyID = "AWS_ACCESS_KEY_ID"
   secretAccessKey = "AWS_SECRET_ACCESS_KEY"
   bucket = "AWS_BUCKET"
   region = "AWS_REGION"
   key = "IMAGE_KEY"

   Copy to Clipboard Toggle word wrap

   Replace values in the fields with your credentials for accessKeyID, secretAccessKey, bucket, and region. The IMAGE_KEY value is the name of your VM Image to be uploaded to EC2.

2. Save the file as CONFIGURATION-FILE.toml and close the text editor.

3. Start the compose to upload it to AWS:

   # composer-cli compose start blueprint-name image-type image-key configuration-file.toml

   Copy to Clipboard Toggle word wrap

   Replace:

   • blueprint-name with the name of the blueprint you created
   • image-type with the ami image type.
   • image-key with the name of your VM Image to be uploaded to EC2.

   • configuration-file.toml with the name of the configuration file of the cloud provider.

     Note

     You must have the correct AWS Identity and Access Management (IAM) settings for the bucket you are going to send your customized image to. You have to set up a policy to your bucket before you are able to upload images to it.

4. Check the status of the image build:

   # composer-cli compose status

   Copy to Clipboard Toggle word wrap

   After the image upload process is complete, you can see the "FINISHED" status.

1. Access EC2 on the menu and select the correct region in the AWS console. The image must have the available status, to indicate that it was successfully uploaded.
2. On the dashboard, select your image and click Launch.

Procedure

1. In the RHEL image builder dashboard, click the blueprint name that you previously created.
2. Select the tab Images.

3. Click Create Image to create your customized image.

   The Create Image window opens.

   1. From the Type drop-down menu list, select Amazon Machine Image Disk (.raw).
   2. Check the Upload to AWS checkbox to upload your image to the AWS Cloud and click Next.

   3. To authenticate your access to AWS, type your AWS access key ID and AWS secret access key in the corresponding fields. Click Next.

      Note

      You can view your AWS secret access key only when you create a new Access Key ID. If you do not know your Secret Key, generate a new Access Key ID.

   4. Type the name of the image in the Image name field, type the Amazon bucket name in the Amazon S3 bucket name field and type the AWS region field for the bucket you are going to add your customized image to. Click Next.

   5. Review the information and click Finish.

      Optionally, click Back to modify any incorrect detail.

      Note

      You must have the correct IAM settings for the bucket you are going to send your customized image. This procedure uses the IAM Import and Export, so you have to set up a policy to your bucket before you are able to upload images to it. For more information, see Required Permissions for IAM Users.

4. A pop-up on the upper right informs you of the saving progress. It also informs that the image creation has been initiated, the progress of this image creation and the subsequent upload to the AWS Cloud.

   After the process is complete, you can see the Image build complete status.

5. In a browser, access Service→EC2.

   1. On the AWS console dashboard menu, choose the correct region. The image must have the Available status, to indicate that it is uploaded.
   2. On the AWS dashboard, select your image and click Launch.
6. A new window opens. Choose an instance type according to the resources you need to start your image. Click Review and Launch.
7. Review your instance start details. You can edit each section if you need to make any changes. Click Launch

8. Before you start the instance, select a public key to access it.

   You can either use the key pair you already have or you can create a new key pair.

   Follow the next steps to create a new key pair in EC2 and attach it to the new instance.

   1. From the drop-down menu list, select Create a new key pair.
   2. Enter the name to the new key pair. It generates a new key pair.
   3. Click Download Key Pair to save the new key pair on your local system.

9. Then, you can click Launch Instance to start your instance.

   You can check the status of the instance, which displays as Initializing.

10. After the instance status is running, the Connect button becomes available.

11. Click Connect. A window appears with instructions on how to connect by using SSH.

    1. Select A standalone SSH client as the preferred connection method to and open a terminal.

    2. In the location you store your private key, ensure that your key is publicly viewable for SSH to work. To do so, run the command:

       $ chmod 400 <_your-instance-name.pem_>

       Copy to Clipboard Toggle word wrap

    3. Connect to your instance by using its Public DNS:

       $ ssh -i <_your-instance-name.pem_> ec2-user@<_your-instance-IP-address_>

       Copy to Clipboard Toggle word wrap

    4. Type yes to confirm that you want to continue connecting.

       As a result, you are connected to your instance over SSH.

Procedure

1. Import the Microsoft repository key:

   # rpm --import https://packages.microsoft.com/keys/microsoft.asc

   Copy to Clipboard Toggle word wrap

2. Create a local azure-cli.repo repository with the following information. Save the azure-cli.repo repository under /etc/yum.repos.d/:

   [azure-cli]
   name=Azure CLI
   baseurl=https://packages.microsoft.com/yumrepos/vscode
   enabled=1
   gpgcheck=1
   gpgkey=https://packages.microsoft.com/keys/microsoft.asc

   Copy to Clipboard Toggle word wrap

3. Install the Microsoft Azure CLI:

   # yumdownloader azure-cli
   # rpm -ivh --nodeps azure-cli-2.0.64-1.el7.x86_64.rpm

   Copy to Clipboard Toggle word wrap
   Note

   The downloaded version of the Microsoft Azure CLI package can vary depending on the current available version.

4. Run the Microsoft Azure CLI:

   $ az login

   Copy to Clipboard Toggle word wrap

   The terminal shows the following message Note, we have launched a browser for you to login. For old experience with device code, use "az login --use-device-code. Then, the terminal opens a browser with a link to https://microsoft.com/devicelogin from where you can login.

   Note

   If you are running a remote (SSH) session, the login page link will not open in the browser. In this case, you can copy the link to a browser and login to authenticate your remote session. To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the device code to authenticate.

5. List the keys for the storage account in Microsoft Azure:

   $ az storage account keys list --resource-group <resource_group_name> --account-name <storage_account_name>

   Copy to Clipboard Toggle word wrap

   Replace resource-group-name with name of your Microsoft Azure resource group and storage-account-name with name of your Microsoft Azure storage account.

   Note

   You can list the available resources using the following command:

   $ az resource list

   Copy to Clipboard Toggle word wrap

   Make note of value key1 in the output of the previous command.

6. Create a storage container:

   $ az storage container create --account-name <storage_account_name>\
   --account-key <key1_value> --name <storage_account_name>

   Copy to Clipboard Toggle word wrap

   Replace storage-account-name with name of the storage account.

Procedure

1. Push the image to Microsoft Azure and create an instance from it:

   $ az storage blob upload --account-name <_account_name_> --container-name <_container_name_> --file <_image_-disk.vhd> --name <_image_-disk.vhd> --type page
   ...

   Copy to Clipboard Toggle word wrap

2. After the upload to the Microsoft Azure Blob storage completes, create a Microsoft Azure image from it:

   $ az image create --resource-group <_resource_group_name_> --name <_image_>-disk.vhd --os-type linux --location <_location_> --source https://$<_account_name_>.blob.core.windows.net/<_container_name_>/<_image_>-disk.vhd
    - Running ...

   Copy to Clipboard Toggle word wrap
   Note

   Because the images that you create with RHEL image builder generate hybrid images that support to both the V1 = BIOS and V2 = UEFI instances types, you can specify the --hyper-v-generation argument. The default instance type is V1.

Verification

1. Create an instance either with the Microsoft Azure portal, or a command similar to the following:

   $ az vm create --resource-group <_resource_group_name_> --location <_location_> --name <_vm_name_> --image <_image_>-disk.vhd --admin-username azure-user --generate-ssh-keys
    - Running ...

   Copy to Clipboard Toggle word wrap
2. Use your private key via SSH to access the resulting instance. Log in as azure-user. This username was set on the previous step.

Procedure

1. In the RHEL image builder dashboard, select the blueprint you want to use.
2. Click the Images tab.

3. Click Create Image to create your customized .vhd image.

   The Create image wizard opens.

   1. Select Microsoft Azure (.vhd) from the Type drop-down menu list.
   2. Check the Upload to Azure checkbox to upload your image to the Microsoft Azure Cloud.
   3. Enter the Image Size and click Next.

4. On the Upload to Azure page, enter the following information:

   1. On the Authentication page, enter:

      1. Your Storage account name. You can find it on the Storage account page, in the Microsoft Azure portal.
      2. Your Storage access key: You can find it on the Access Key Storage page.
      3. Click Next.

   2. On the Authentication page, enter:

      1. The image name.
      2. The Storage container. It is the blob container to which you will upload the image. Find it under the Blob service section, in the Microsoft Azure portal.
      3. Click Next.

5. On the Review page, click Create. The RHEL image builder and upload processes start.

   Access the image you pushed into Microsoft Azure Cloud.

6. Access the Microsoft Azure portal.
7. In the search bar, type "storage account" and click Storage accounts from the list.
8. On the search bar, type "Images" and select the first entry under Services. You are redirected to the Image dashboard.
9. On the navigation panel, click Containers.
10. Find the container you created. Inside the container is the .vhd file you created and pushed by using RHEL image builder.

Verification

1. Verify that you can create a VM image and launch it.

   1. In the search bar, type images account and click Images from the list.
   2. Click +Create.
   3. From the dropdown list, choose the resource group you used earlier.
   4. Enter a name for the image.
   5. For the OS type, select Linux.
   6. For the VM generation, select Gen 2.
   7. Under Storage Blob, click Browse and click through the storage accounts and container until you reach your VHD file.
   8. Click Select at the end of the page.
   9. Choose an Account Type, for example, Standard SSD.
   10. Click Review + Create and then Create. Wait a few moments for the image creation.

2. To launch the VM, follow the steps:

   1. Click Go to resource.
   2. Click + Create VM from the menu bar on the header.
   3. Enter a name for your virtual machine.
   4. Complete the Size and Administrator account sections.

   5. Click Review + Create and then Create. You can see the deployment progress.

      After the deployment finishes, click the virtual machine name to retrieve the public IP address of the instance to connect by using SSH.

   6. Open a terminal to create an SSH connection to connect to the VM.

Procedure

1. Configure the following values in the user environment with the GOVC environment variables:

   GOVC_URL
   GOVC_DATACENTER
   GOVC_FOLDER
   GOVC_DATASTORE
   GOVC_RESOURCE_POOL
   GOVC_NETWORK

   Copy to Clipboard Toggle word wrap
2. Navigate to the directory where you downloaded your VMware vSphere image.

3. Launch the VMware vSphere image on vSphere by following the steps:

   1. Import the VMware vSphere image in to vSphere:

      $ govc import.vmdk ./composer-api.vmdk foldername

      Copy to Clipboard Toggle word wrap

      For the .ova format:

      $ govc import.ova ./composer-api.ova foldername

      Copy to Clipboard Toggle word wrap

   2. Create the VM in vSphere without powering it on:

      govc vm.create \
      -net.adapter=vmxnet3 \
      -m=4096 -c=2 -g=rhel8_64Guest \
      -firmware=efi -disk=”foldername/composer-api.vmdk” \
      -disk.controller=scsi -on=false \
       vmname

      Copy to Clipboard Toggle word wrap

      For the .ova format, replace the line -firmware=efi -disk=”foldername/composer-api.vmdk” \ with `-firmware=efi -disk=”foldername/composer-api.ova” \

   3. Power-on the VM:

      govc vm.power -on vmname

      Copy to Clipboard Toggle word wrap

   4. Retrieve the VM IP address:

      govc vm.ip vmname

      Copy to Clipboard Toggle word wrap

   5. Use SSH to log in to the VM, using the username and password you specified in your blueprint:

      $ ssh admin@<_ip_address_of_the_vm_>

      Copy to Clipboard Toggle word wrap
      Note

      If you copied the .vmdk image from your local host to the destination using the govc datastore.upload command, using the resulting image is not supported. There is no option to use the import.vmdk command in the vSphere GUI and as a result, the vSphere GUI does not support the direct upload. As a consequence, the .vmdk image is not usable from the vSphere GUI.

Procedure

1. For the blueprint you created, click the Images tab .

2. Click Create Image to create your customized image.

   The Image type window opens.

3. In the Image type window:

   1. From the dropdown menu, select the Type: VMware vSphere (.vmdk).
   2. Check the Upload to VMware checkbox to upload your image to the vSphere.
   3. Optional: Set the size of the image you want to instantiate. The minimal default size is 2 GB.
   4. Click Next.

4. In the Upload to VMware window, under Authentication, enter the following details:

   1. Username: username of the vSphere account.
   2. Password: password of the vSphere account.

5. In the Upload to VMware window, under Destination, enter the following details about the image upload destination:

   1. Image name: a name for the image.
   2. Host: The URL of your VMware vSphere.
   3. Cluster: The name of the cluster.
   4. Data center: The name of the data center.
   5. Data store:The name of the Data store.
   6. Click Next.

6. In the Review window, review the details of the image creation and click Finish.

   You can click Back to modify any incorrect detail.

   RHEL image builder adds the compose of a RHEL vSphere image to the queue, and creates and uploads the image to the Cluster on the vSphere instance you specified.

   Note

   The image build and upload processes take a few minutes to complete.

   After the process is complete, you can see the Image build complete status.

1. Access VMware vSphere Client.
2. Search for the image in the Cluster on the vSphere instance you specified.
3. Select the image you uploaded.
4. Right-click the selected image.

5. Click New Virtual Machine.

   A New Virtual Machine window opens.

   In the New Virtual Machine window, provide the following details:

   1. Select New Virtual Machine.
   2. Select a name and a folder for your VM.
   3. Select a computer resource: choose a destination computer resource for this operation.
   4. Select storage: For example, select NFS-Node1
   5. Select compatibility: The image should be BIOS only.
   6. Select a guest operating system: For example, select Linux and Red Hat Fedora (64-bit).
   7. Customize hardware: When creating a VM, on the Device Configuration button on the upper right, delete the default New Hard Disk and use the drop-down to select an Existing Hard Disk disk image:
   8. Ready to complete: Review the details and click Finish to create the image.

6. Navigate to the VMs tab.

   1. From the list, select the VM you created.
   2. Click the Start button from the panel. A new window appears, showing the VM image loading.
   3. Log in with the credentials you created for the blueprint.

   4. You can verify if the packages you added to the blueprint are installed. For example:

      $ rpm -qa | grep firefox

      Copy to Clipboard Toggle word wrap

Procedure

1. Open the RHEL image builder interface of the web console in a browser.
2. Click Create blueprint. The Create blueprint wizard opens.
3. On the Details page, enter a name for the blueprint, and optionally, a description. Click Next.
4. On the Packages page, select the components and packages that you want to include in the image. Click Next.
5. On the Customizations page, configure the customizations that you want for your blueprint. Click Next.
6. On the Review page, click Create.
7. To create an image, click Create Image. The Create image wizard opens.

8. On the Image output page, complete the following steps:

   1. From the "Select a blueprint" drop-down menu, select the blueprint you want.
   2. From the "Image output type" drop-down menu, select Oracle Cloud Infrastructure (.qcow2).
   3. Check the "Upload OCI checkbox to upload your image to the OCI.
   4. Enter the "image size". Click Next.

9. On the Upload to OCI - Authentication page, enter the following mandatory details:

   1. User OCID: you can find it in the Console on the page showing the user’s details.
   2. Private key

10. On the Upload to OCI - Destination page, enter the following mandatory details and click Next.

    1. Image name: a name for the image to be uploaded.
    2. OCI bucket
    3. Bucket namespace
    4. Bucket region
    5. Bucket compartment
    6. Bucket tenancy
11. Review the details in the wizard and click Finish.

Verification

1. Access the OCI dashboard Custom Images.
2. Select the Compartment you specified for the image and locate the image in the Import image table.
3. Click the image name and verify the image information.

Procedure

1. Start the compose of a QCOW2 image.

   # composer-cli compose start blueprint_name openstack

   Copy to Clipboard Toggle word wrap

2. Check the status of the building.

   # composer-cli compose status

   Copy to Clipboard Toggle word wrap

   After the image build finishes, you can download the image.

3. Download the QCOW2 image:

   # composer-cli compose image UUID

   Copy to Clipboard Toggle word wrap
4. Access the OpenStack dashboard and click +Create Image.
5. On the left menu, select the Admin tab.

6. From the System Panel, click Image.

   The Create An Image wizard opens.

7. In the Create An Image wizard:

   1. Enter a name for the image
   2. Click Browse to upload the QCOW2 image.
   3. From the Format dropdown list, select the QCOW2 - QEMU Emulator.

   4. Click Create Image.

      

8. On the left menu, select the Project tab.

   1. From the Compute menu, select Instances.

   2. Click the Launch Instance button.

      The Launch Instance wizard opens.

   3. On the Details page, enter a name for the instance. Click Next.
   4. On the Source page, select the name of the image you uploaded. Click Next.

   5. On the Flavor page, select the machine resources that best fit your needs. Click Launch.

      

9. You can run the image instance using any mechanism (CLI or OpenStack web UI) from the image. Use your private key via SSH to access the resulting instance. Log in as cloud-user.