Procedure

1. Install the Image Builder and other necessary packages on the virtual machine:

   • lorax-composer
   • composer-cli
   • cockpit-composer

   • bash-completion

     # yum install lorax-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 lorax-composer.socket
   # systemctl enable cockpit.socket

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

3. Configure the system firewall to allow access to the web console:

   # firewall-cmd --add-service=cockpit && firewall-cmd --add-service=cockpit --permanent

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

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 name of the package, such as httpd, gdb-doc, or coreutils.

   Replace package-version with a version to use. This field supports dnf version specifications:

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

3. Blueprints can be customized in a number of ways. For this example, Simultaneous Multi Threading (SMT) can be disabled by performing the steps below. For additional customizations available, please see the Image Customizations section.

   [customizations.kernel]
   append = "nosmt=force"

4. Save the file 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.

6. To verify that the blueprint has been pushed and exists, list the existing blueprints:

   # composer-cli blueprints list

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

   # composer-cli blueprints depsolve BLUEPRINT-NAME

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 of your choice and make your changes.

3. Before finishing with the edits, make sure the file is a valid blueprint:

   1. Remove this line, if present:

      packages = []

   2. Increase the version number. Remember that Image Builder blueprint versions must use the Semantic Versioning scheme. Note also that if you do not change the version, the patch component of version is increased 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 editor.

5. Push (import) the blueprint back into Image Builder:

   # composer-cli blueprints push BLUEPRINT-NAME.toml

   Note that you must supply the file name including the .toml extension, while in other commands you use only the name of the blueprint.

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 image. For possible values, see output of the composer-cli compose types command.

   The compose process starts in the background and the UUID of the compose is shown.

2. Wait until the compose is finished. Please, notice that this may take several minutes.

   To check the status of the compose:

   # composer-cli compose status

   A finished compose shows a status value FINISHED. Identify the compose in the list by its UUID.

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

   # composer-cli compose image UUID

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

   Alternatively, you can access the image file directly under the path /var/lib/lorax/composer/results/UUID/.

   You can also download the logs using the composer-cli compose logs UUID command, or the metadata using the composer-cli compose metadata UUID command.

Procedure

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

   For more information how to remotely access Image Builder, see managing systems using the RHEL 8 web console.

2. Log into the web console with credentials for an user account with sufficient privileges on the system.

3. To display the Image Builder controls, click the Image Builder icon, which is in the upper-left corner of the window.

   The Image Builder view opens, listing existing blueprints.

Procedure

1. Click Create Blueprint in the top right corner.

   A pop-up appears with fields for the blueprint name and description.

2. Fill in the name of the blueprint, its description, then click Create.

   The screen changes to blueprint editing mode.

3. Add components that you want to include in the system image:

   1. On the left, enter all or part of the component name in the Available Components field and press Enter.

      The search is added to the list of filters under the text entry field, and the list of components below is reduced to these that match the search.

      If the list of components is too long, add further search terms in the same way.

   2. The list of components is paged. To move to other result pages, use the arrows and entry field above the component list.
   3. Click on name of the component you intend to use to display its details. The right pane fills with details of the components, such as its version and dependencies.
   4. Select the version you want to use in the Component Options box, with the Version Release dropdown.
   5. Click Add in the top left.
   6. If you added a component by mistake, remove it by clicking the …​ button at the far right of its entry in the right pane, and select Remove in the menu.

   Note

   If you do not intend to select version for some components, you can skip the component details screen and version selection by clicking the + buttons on the right side of the component list.

4. To save the blueprint, click Commit in the top right A dialog with a summary of the changes pops up. Click Commit.

   A small pop-up on the right informs you of the saving progress and then the result.

5. To exit the editing screen, click Back to Blueprints in the top left.

   The Image Builder view opens, listing existing blueprints.

Procedure

1. Locate the blueprint that you want to edit by entering its name or a part of it into the search box at top left, and press Enter.

   The search is added to the list of filters under the text entry field, and the list of blueprints below is reduced to these that match the search.

   If the list of blueprints is too long, add further search terms in the same way.

2. On the right side of the blueprint, press the Edit Blueprint button that belongs to the blueprint.

   The view changes to the blueprint editing screen.

3. Remove unwanted components by clicking their ⫶ button at the far right of its entry in the right pane, and select Remove in the menu.

4. Change version of existing components:

   1. On the Blueprint Components search field, enter component name or a part of it into the field under the heading Blueprint Components and press Enter.

      The search is added to the list of filters under the text entry field, and the list of components below is reduced to these that match the search.

      If the list of components is too long, add further search terms in the same way.

   2. Click the ⫶ button at the far right of the component entry, and select View in the menu.

      A component details screen opens in the right pane.

   3. Select the desired version in the Version Release drop-down menu and click Apply Change in top right.

      The change is saved and the right pane returns to listing the blueprint components.

5. Add new components:

   1. On the left, enter component name or a part of it into the field under the heading Available Components and press Enter.

      The search is added to the list of filters under the text entry field, and the list of components below is reduced to these that match the search.

      If the list of components is too long, add further search terms in the same way.

   2. The list of components is paged. To move to other result pages, use the arrows and entry field above the component list.
   3. Click on name of the component you intend to use to display its details. The right pane fills with details of the components, such as its version and dependencies.
   4. Select the version you want to use in the Component Options box, with the Version Release drop-down menu.
   5. Click Add in the top right.
   6. If you added a component by mistake, remove it by clicking the ⫶ button at the far right of its entry in the right pane, and select Remove in the menu.

1. Commit a new version of the blueprint with your changes:

   1. Click the Commit button in top right.

      A pop-up window with a summary of your changes appears.

   2. Review your changes and confirm them by clicking Commit.

      A small pop-up on the right informs you of the saving progress and then result. A new version of the blueprint is created.

   3. In the top left, click Back to Blueprints to exit the editing screen.

      The Image Builder view opens, listing existing blueprints.

Procedure

1. Find out the name of the blueprint: Open the Image Builder (Image builder) tab on the left in the RHEL 8 web console to see the name of the blueprint.
2. Navigate to the CLI in web console: Open the system administation tab on the left, then select the last item Terminal from the list on the left.

3. Enter the super-user (root) mode:

   $ sudo bash

   Provide your credentials when asked. Note that the terminal does not reuse your credentials you entered when logging into the web console.

   A new shell with root privileges starts in your home directory.

4. Export the blueprint to a file:

   # composer-cli blueprints save BLUEPRINT-NAME

5. Edit the file BLUEPRINT-NAME.toml with a CLI text editor of your choice and add the users and groups.

   Important

   RHEL 8 web console does not have any built-in feature to edit text files on the system, so the use of a CLI text editor is required for this step.

   1. For every user to be added, add this block to the file:

      [[customizations.user]]
      name = "USER-NAME"
      description = "USER-DESCRIPTION"
      password = "PASSWORD-HASH"
      key = "ssh-rsa (...) key-name"
      home = "/home/USER-NAME/"
      shell = "/usr/bin/bash"
      groups = ["users", "wheel"]
      uid = NUMBER
      gid = NUMBER

      Replace PASSWORD-HASH with the actual password hash. To generate the hash, use eg. this command:

      $ python3 -c 'import crypt,getpass;pw=getpass.getpass();print(crypt.crypt(pw) if (pw==getpass.getpass("Confirm: ")) else exit())'

      Replace ssh-rsa (…​) key-name with the actual public key.

      Replace the other placeholders with suitable values.

      Leave out any of the lines as needed, only the user name is required.

   2. For every user group to be added, add this block to the file:

      [[customizations.group]]
      name = "GROUP-NAME"
      gid = NUMBER

   3. Increase the version number.
   4. Save the file and close the editor.

6. Import the blueprint back into Image Builder:

   # composer-cli blueprints push BLUEPRINT-NAME.toml

   Note that you must supply the file name including the .toml extension, while in other commands you use only the name of the blueprint.

7. To verify that the contents uploaded to Image Builder match your edits, list the contents of blueprint:

   # composer-cli blueprints show BLUEPRINT-NAME

   Check if the version matches what you put in the file and if your customizations are present.

   Important

   The Image Builder plugin for RHEL 8 web console does not show any information that could be used to verify that the changes have been applied, unless you edited also the packages included in the blueprint.

8. Exit the privileged shell:

   # exit

9. Open the Image Builder (Image builder) tab on the left and refresh the page, in all browsers and all tabs where it was opened.

   This prevents state cached in the loaded page from accidentally reverting your changes.

Procedure

1. Locate the blueprint that you want to build an image by entering its name or a part of it into the search box at top left, and press Enter.

   The search is added to the list of filters under the text entry field, and the list of blueprints below is reduced to these that match the search.

   If the list of blueprints is too long, add further search terms in the same way.

2. On the right side of the blueprint, press the Create Image button that belongs to the blueprint.

   A pop-up window appears.

3. Select the image type and architecture and press Create.

   A small pop-up in the top right informs you that the image creation has been added to the queue.

4. Click the name of the blueprint.

   A screen with details of the blueprint opens.

5. Click the Images tab to switch to it. The image that is being created is listed with the status In Progress.

   Note

   Image creation takes a longer time, measured in minutes. There is no indication of progress while the image is created.

   To abort image creation, press its Stop button on the right.

6. Once the image is successfully created, the Stop button is replaced by a Download button. Click this button to download the image to your system.

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. Configure the AWS command line client according to your AWS access details:

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

4. Configure the AWS command line client to use your bucket:

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

   Replace bucketname with the actual bucket name.

5. Create a vmimport S3 Role in IAM and grant it permissions to access S3, 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. Push the image to S3:

   $ AMI=8db1b463-91ee-4fd9-8065-938924398428-disk.ami
   $ aws s3 cp $AMI s3://$BUCKET
   Completed 24.2 MiB/4.4 GiB (2.5 MiB/s) with 1 file(s) remaining
   ...

2. After the upload to S3 ends, import the image as a snapshot into EC2:

   $ printf '{ "Description": "my-image", "Format": "raw", "UserBucket": { "S3Bucket": "%s", "S3Key": "%s" } }' $BUCKET $AMI > containers.json
   $ aws ec2 import-snapshot --disk-container file://containers.json

   Replace my-image with the name of the image.

   To track progress of the import, run:

   $ aws ec2 describe-import-snapshot-tasks --filters Name=task-state,Values=active

3. Create an image from the uploaded snapshot by selecting the snapshot in the EC2 console, right clicking on it and selecting Create Image:

   

4. Select the Virtualization type of Hardware-assisted virtualization in the image you create:

   

5. Now you can run an instance using whatever mechanism you like (CLI or AWS Console) from the snapshot. Use your private key via SSH to access the resulting EC2 instance. Log in as ec2-user.

Procedure

1. Upload the image into vSphere via HTTP. Click on Upload Files in the vCenter:

   

2. When you create a VM, on the Device Configuration, delete the default New Hard Disk and use the drop-down to select an Existing Hard Disk disk image:

   

3. Make sure you use an IDE device as the Virtual Device Node for the disk you create. The default value SCSI results in an unbootable virtual machine.

   

Procedure

1. Upload the image to OpenStack and start an instance from it. Use the Images interface to do this:

   

2. Start an instance with that image:

   

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