Chapter 4. Creating system images with Image Builder web console interface

Image Builder is a tool for creating custom system images. To control Image Builder and create your custom system images, you can use the web console interface. Note that the command-line interface is the currently preferred alternative, because it offers more features.

4.1. Accessing Image Builder GUI in the RHEL 8 web console

The cockpit-composer plugin for the RHEL 8 web console enables users to manage Image Builder blueprints and composes with a graphical interface. Note that the preferred method for controlling Image Builder is at the moment using the command-line interface.

Prerequisites

  • You must have root access to the system.

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

  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.

4.2. Creating an Image Builder blueprint in the web console interface

To describe the customized system image, create a blueprint first.

Prerequisites

  • You have opened the Image Builder interface of the RHEL 8 web console in a browser.

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 the 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 a 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.

4.3. Editing an Image Builder blueprint in the web console interface

To change the specifications for a custom system image, edit the corresponding blueprint.

Prerequisites

  • You have opened the Image Builder interface of the RHEL 8 web console in a browser.
  • A blueprint exists.

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

      Note

      If you do not intend to select a 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.

  6. 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 the results. 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.

4.4. Adding users and groups to an Image Builder blueprint in the web console interface

Adding customizations such as users and groups to blueprints in the web console interface is currently not possible. To work around this limitation, use the Terminal tab in web console to use the command-line interface (CLI) workflow.

Prerequisites

  • A blueprint must exist.
  • A CLI text editor such as vim, nano, or emacs must be installed. To install them:

    # yum install editor-name

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 administration 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 a command such as this:

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

4.5. Creating a system image with Image Builder in the web console interface

The following steps below describe creating a system image.

Prerequisites

  • You have opened the Image Builder interface of the RHEL 8 web console in a browser.
  • A blueprint exists.

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

4.6. Adding a source to a blueprint

The sources defined in Image Builder provide the contents that you can add to blueprints. These sources are global and therefore available to all blueprints. The System sources are repositories that are set up locally on your computer and cannot be removed from Image Builder. You can add additional custom sources and thus be able to access other contents than the System sources available on your system.

The following steps describe how to add a Source to your local system.

Prerequisites

  • You have opened the Image Builder interface of the RHEL 8 web console in a browser.

Procedure

  1. Click the Manage Sources button in the top right corner.

    image builder manage source

    A pop-up window appears with the available sources, their names and descriptions.

    image builder available sources

  2. On the right side of the pop-up window, click the Add Source button.
  3. Add the desired Source name, the Source path, and the Source Type. The Security field is optional.

    image builder sources options

  4. Click Add Source button. The screen shows the available sources window and list the source you have added.

As a result, the new System source is available and ready to be used or edited.

4.7. Creating a user account for a blueprint

The images created by Image Builder have the root account locked and no other accounts included. Such configuration is provided in order to ensure that you cannot accidentally build and deploy an image without a password. Image Builder enables you to create a user account with password for a blueprint so that you can log in to the image created from the blueprint.

Prerequisites

  • You have opened the Image Builder interface of the RHEL 8 web console in a browser.
  • You have an existing blueprint.

Procedure

  1. Locate the blueprint that you want to create a user account for by entering its name or a part of it into the search box at the 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 those that match the search.

  2. Click on the blueprint name to display the blueprint details.

    image builder create user account
  3. Click Create User Account.

    This will open a window with fields for user account creation.

    image builder creating user account 2
  4. Fill in the details. Notice that when you insert the name, the User name field autocompletes, suggesting a username.
  5. Once you have inserted all the desired details, click Create.
  6. The created user account appears showing all the information you have inserted.

    image builder user account created
  7. To create further user accounts for the blueprint, repeat the process.

4.8. Creating a user account with SSH key

The images created by Image Builder have the root account locked and no other accounts included. Such configuration is provided in order to ensure that images are secure, by not having a default password. Image Builder enables you to create a user account with SSH key for a blueprint so that you can authenticate to the image that you created from the blueprint. To do so, first, create a blueprint. Then, you will create a user account with a password and an SSH key. The following example shows how to create a Server administrator user with an SSH key configured.

Prerequisites

  • You have created an SSH key that will be paired with the created user later on in the process.
  • You have opened the Image Builder interface of the RHEL 8 web console in a browser.
  • You have an existing blueprint

Procedure

  1. Locate the blueprint that you want to create a user account for by entering its name or a part of it into the search box at the 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 those that match the search.

  2. Click on the blueprint name to display the blueprint details.

    image builder create user account
  3. Click Create User Account.

    This will open a window with fields for user account creation

    image builder creating user account 2
  4. Fill in the details. Notice that when you insert the name, the User name field autocompletes, suggesting a username.

    If you want to provide administrators rights to the user account you are creating, check the Role field.

    Paste the content of your public SSH key file.

  5. Once you have inserted all the desired details, click Create.
  6. The new user account will appear in the user list, showing all the information you have inserted.

    image builder user account created
  7. If you want to create more user accounts for the blueprint, repeat the process.

Additional resources