Chapter 7. Composing a customized RHEL system image

Procedure

1. Install the image builder and other necessary packages on the VM:

   • osbuild-composer - supported from RHEL 8.3 onward
   • composer-cli
   • cockpit-composer
   • bash-completion

   # yum install osbuild-composer composer-cli cockpit-composer bash-completion

   The web console is installed as a dependency of the cockpit-composer package.

2. Enable image builder to start after each reboot:

   # systemctl enable --now osbuild-composer.socket
   # systemctl enable --now cockpit.socket

   The osbuild-composer and cockpit services start automatically on first access.

3. Load the shell configuration script so that the autocomplete feature for the composer-cli command starts working immediately without reboot:

   $ source /etc/bash_completion.d/composer-cli

Procedure

1. Remove the osbuild-composer backend.

   # yum remove osbuild-composer
   # yum remove weldr-client

2. In the /etc/yum.conf file, add an exclude entry for osbuild-composer package.

   # cat /etc/yum.conf
   [main]
   gpgcheck=1
   installonly_limit=3
   clean_requirements_on_remove=True
   best=True
   skip_if_unavailable=False
   exclude=osbuild-composer weldr-client

3. Install the lorax-composer package.

   # yum install lorax-composer composer-cli

4. Enable and start the lorax-composer service to start after each reboot.

   # systemctl enable --now lorax-composer.socket
   # systemctl start lorax-composer

1. Export (save) the blueprint definition to a plain text file
2. Edit this file in a text editor
3. Import (push) 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

Procedure

1. Create a plain text file with the following contents:

   name = "BLUEPRINT-NAME"
   description = "LONG FORM DESCRIPTION TEXT"
   version = "0.0.1"
   modules = []
   groups = []

   Replace BLUEPRINT-NAME and LONG FORM DESCRIPTION TEXT 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.

   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 8.7.0.
   • For the latest available version, use the asterisk *.
   • For the latest minor version, use formats such as 8.*.

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.

4. Save the file, for example, as BLUEPRINT-NAME.toml and close the text editor.

5. Push (import) the blueprint:

   # composer-cli blueprints push BLUEPRINT-NAME.toml

   Replace BLUEPRINT-NAME with the value you used in previous steps.

   Note

   To create images using composer-cli as non-root, add your user to the weldr or root groups.

   # usermod -a -G weldr user
   $ newgrp weldr

Procedure

1. Save (export) the blueprint to a local text file:

   # composer-cli blueprints save BLUEPRINT-NAME

2. Edit the BLUEPRINT-NAME.toml file with a text editor and make your changes.

3. Before finishing the edits, verify that the file is a valid blueprint:

   1. Remove this line, if present:

      packages = []

   2. Increase the version number, for example, fro 0.0.1 to 0.1.0. Remember that image builder blueprint versions must use the Semantic Versioning scheme. Note also that if you do not change the version, the patch version component increases automatically.

   3. Check if the contents are valid TOML specifications. See the TOML documentation for more information.

      Note

      TOML documentation is a community product and is not supported by Red Hat. You can report any issues with the tool at https://github.com/toml-lang/toml/issues

4. Save the file and close the text editor.

5. Push (import) the blueprint back into image builder:

   # composer-cli blueprints push BLUEPRINT-NAME.toml

   Note

   To import the blueprint back into image builder, supply the file name including the .toml extension, while in other commands use only the blueprint name.

6. To verify that the contents uploaded to image builder match your edits, list the contents of blueprint:

   # composer-cli blueprints show BLUEPRINT-NAME

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

   # composer-cli blueprints depsolve BLUEPRINT-NAME

Procedure

1. Start the compose:

   # composer-cli compose start BLUEPRINT-NAME IMAGE-TYPE

   Replace BLUEPRINT-NAME with name of the blueprint, and IMAGE-TYPE with the type of the image. For the available values, see the output of the composer-cli compose types command.

   The compose process starts in the background and shows the composer Universally Unique Identifier (UUID).

2. Wait until the compose process is finished. The image creation can take up to ten minutes to complete.

   To check the status of the compose:

   # composer-cli compose status

   A finished compose shows the FINISHED status value. To identify your compose in the list, use its UUID.

3. After the compose process is finished, download the resulting image file:

   # composer-cli compose image UUID

   Replace UUID with the UUID value shown in the previous steps.

Procedure

1. Open https://localhost:9090/ in a web browser on the system where image builder is installed.

   For more information about how to remotely access image builder, see Managing systems using the RHEL web console document.

2. Log in to the web console as the root user.

3. To display the image builder controls, click the image builder icon, in the upper-left corner of the window.

   The image builder view opens, listing existing blueprints.

Procedure

1. Click Create Blueprint in the upper-right corner.

   A dialog wizard with fields for the blueprint name and description opens.

2. Enter the name of the blueprint and, optionally, its description.
3. Click Create.

Procedure

1. Click Back to blueprints to show the blueprints table.

2. On the blueprint table, find the blueprint you want to build an image.

   1. Optionally, you can find the blueprint using the search box. Enter the blueprint name.
3. On the right side of the chosen blueprint, click Create Image. The Create image dialog wizard opens.

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

   1. From the Image output type list, select the image type you want.

      1. You can upload some images to their target cloud environment, such as Amazon Web Service and Oracle Cloud Infrastructure. For that, check the Upload to Target cloud box .
      2. You are prompted to add credentials for the cloud environment on the next page.
5. From the Image Size field, enter the image size. The minimum size depends on the image type. Click Next.

6. On the Upload to Targeted_Cloud page, complete the following steps:

   NOTE:This page is not visible if you did not check the box to upload your image to the cloud environment.

   1. On the Authentication page, enter the information related to your target cloud account ID and click Next.
   2. On the Destination page, enter the information related to your target cloud account type and click Next.

7. On the Customizations page, complete the following steps:

   1. On the System page, enter the Hostname. If you do not enter a hostname, the operating system determines a hostname for your system.

   2. On the Users page, click Add user:

      1. Mandatory: Enter a Username.
      2. Enter a password.
      3. Enter an SSH key.
      4. Check the box if you want to make the user a Server administrator. Click Next.

8. On the Package page, complete the following steps:

   1. On the Available packages search field, enter the package name you want to add to your system image.

      Note

      Searching for the package can take some time to complete.

   2. Click the > arrow to add the selected package or packages. Click Next.

9. On the Review page, review the details about the image creation. Click Save blueprint to save the customizations you added to your blueprint. Click Create image.

   The image build starts and takes up to 20 minutes to complete.

Procedure

1. Install Python 3 and the pip tool:

   # yum install python3
   # yum install python3-pip

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

   # pip3 install awscli

3. Run the following command to 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]:

4. Define a name for your bucket and use the following command to create a bucket:

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

   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:

   $ printf '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "vmie.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals":{ "sts:Externalid": "vmimport" } } } ] }' > trust-policy.json
   $ printf '{ "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 > role-policy.json
   $ aws iam create-role --role-name vmimport --assume-role-policy-document file://trust-policy.json
   $ aws iam put-role-policy --role-name vmimport --policy-name vmimport --policy-document file://role-policy.json

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"

   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:

   # composer-cli compose start BLUEPRINT-NAME IMAGE-TYPE IMAGE_KEY CONFIGURATION-FILE.toml

   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 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 and upload it to AWS:

   # composer-cli compose status

   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. Click the blueprint name.
2. Select the tab Images.

3. Click Create Image to create your customized image.

   A pop-up window opens.

   1. From the Type drop-down menu list, select Amazon Machine Image Disk (.raw).
   2. Check the Upload to AWS check box 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, you can 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 small 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. Click Service→EC2 on the menu and choose the correct region in the AWS console. The image must have the Available status, to indicate that it is uploaded.
6. On the dashboard, select your image and click Launch.
7. A new window opens. Choose an instance type according to the resources you need to start your image. Click Review and Launch.
8. Review your instance start details. You can edit each section if you need to make any changes. Click Launch

9. 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. Alternatively, you can use image builder to add a user to the image with a preset public key. See Creating a user account with an SSH key for more details.

   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.

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

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

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

12. Click Connect. A pop-up window appears with instructions on how to connect 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>_

    3. Connect to your instance using its Public DNS:

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

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

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

Verification

1. Check if you are able to perform any action while connected to your instance using SSH.

Procedure

1. Import the Microsoft repository key:

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

2. Create a local azure-cli repository information:

   # sh -c 'echo -e "[azure-cli]\nname=Azure CLI\nbaseurl=https://packages.microsoft.com/yumrepos/azure-cli\nenabled=1\ngpgcheck=1\ngpgkey=https://packages.microsoft.com/keys/microsoft.asc" > /etc/yum.repos.d/azure-cli.repo'

3. Install the Microsoft Azure CLI:

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

   Note

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

4. Run the Microsoft Azure CLI:

   $ az login

   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 https://microsoft.com/devicelogin 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:

   $ GROUP=resource-group-name
   $ ACCOUNT=storage-account-name
   $ az storage account keys list --resource-group $GROUP --account-name $ACCOUNT

   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

6. Make note of value key1 in the output of the previous command, and assign it to an environment variable:

   $ KEY1=value

7. Create a storage container:

   $ CONTAINER=storage-account-name
   $ az storage container create --account-name $ACCOUNT \
   --account-key $KEY1 --name $CONTAINER

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

Verification

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

   $ az vm create --resource-group $GROUP --location eastus --name $VHD --image $VHD --admin-username azure-user --generate-ssh-keys
    - Running ...

2. Use your private key via SSH to access the resulting instance. Log in as azure-user.

Procedure

1. Navigate to the directory where you downloaded your .vmdk image.

2. Launch the image on vSphere by following the steps:

   1. Import the .vmdk image in to vSphere:

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

   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

   3. Power-on the VM:

      govc vm.power -on vmname

   4. Retrieve the VM IP address:

      HOST=$(govc vm.ip vmname)

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

      $ ssh admin@HOST

      Note

      If you copied the .vmdk image from your local host to the destination using the govc datastore.upload command, using the image is not supported. There is no option to use the import.vmdk command in the vSphere GUI and as a consequence, the vSphere GUI does not support the direct upload, as a consequence, the .vmdk image is not directly 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 2GB.
   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: pasword of the vSphere account.

5. In the Upload to VMware window, under Destination, enter the following details:

   1. Image name: a name for the image to be uploaded.
   2. Host: The URL of your VMware vSphere where the image will be uploaded.
   3. Cluster: The name of the cluster where the image will be uploaded.
   4. Data center: The name of the data center where the image will be uploaded.
   5. Data store:The name of the Data store where the image will be uploaded.
   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.

   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. You can create a new VM from the image you uploaded:

   1. Select the image you uploaded.
   2. Right-click the selected image.

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

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

Procedure

1. For the blueprint name, click the Images tab .

2. Click Create Image