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
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.
- Log into the web console with credentials for an user account with sufficient privileges on the system.
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.
Additional resources
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
Click
in the top right corner.A pop-up appears with fields for the blueprint name and description.
Fill in the name of the blueprint, its description, then click
.The screen changes to blueprint editing mode.
Add components that you want to include in the system image:
On the left, enter all or part of the component name in the
Available Components
field and press .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.
- The list of components is paged. To move to other result pages, use the arrows and entry field above the component list.
- 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.
-
Select the version you want to use in the
Component Options
box, with theVersion Release
dropdown. - Click in the top left.
-
If you added a component by mistake, remove it by clicking the
Remove
in the menu. button at the far right of its entry in the right pane, and select
NoteIf 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.To save the blueprint, click
in the top right. A dialog with a summary of the changes pops up. Click .A small pop-up on the right informs you of the saving progress and then the result.
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
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
.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.
On the right side of the blueprint, press the
button that belongs to the blueprint.The view changes to the blueprint editing screen.
-
Remove unwanted components by clicking their
Remove
in the menu. button at the far right of its entry in the right pane, and select Change version of existing components:
On the Blueprint Components search field, enter component name or a part of it into the field under the heading
Blueprint Components
and press .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.
Click the
button at the far right of the component entry, and selectView
in the menu.A component details screen opens in the right pane.
Select the desired version in the
Version Release
drop-down menu and click in top right.The change is saved and the right pane returns to listing the blueprint components.
Add new components:
On the left, enter component name or a part of it into the field under the heading
Available Components
and press .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.
- The list of components is paged. To move to other result pages, use the arrows and entry field above the component list.
- 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.
-
Select the version you want to use in the
Component Options
box, with theVersion Release
drop-down menu. - Click in the top right.
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 selectRemove
in the menu.NoteIf 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.
Commit a new version of the blueprint with your changes:
Click the
button in top right.A pop-up window with a summary of your changes appears.
Review your changes and confirm them by clicking
.A small pop-up on the right informs you of the saving progress and the results. A new version of the blueprint is created.
In the top left, click
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
, oremacs
must be installed. To install them:# yum install editor-name
Procedure
- 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.
- 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.
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.
Export the blueprint to a file:
# composer-cli blueprints save BLUEPRINT-NAME
Edit the file BLUEPRINT-NAME.toml with a CLI text editor of your choice and add the users and groups.
ImportantRHEL 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.
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.
For every user group to be added, add this block to the file:
[[customizations.group]] name = "GROUP-NAME" gid = NUMBER
- Increase the version number.
- Save the file and close the editor.
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.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.
ImportantThe 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.
Exit the privileged shell:
# exit
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.
Additional information
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
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.
On the right side of the blueprint, press the
button that belongs to the blueprint.A pop-up window appears.
Select the image type and press
.A small pop-up in the top right informs you that the image creation has been added to the queue.
Click the name of the blueprint.
A screen with details of the blueprint opens.
Click the
tab to switch to it. The image that is being created is listed with the statusIn Progress
.NoteImage 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
button on the right.- Once the image is successfully created, the button is replaced by a 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
Click the Manage Sources button in the top right corner.
A pop-up window appears with the available sources, their names and descriptions.
- On the right side of the pop-up window, click the button.
Add the desired Source name, the Source path, and the Source Type. The Security field is optional.
- Click 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
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.
Click on the blueprint name to display the blueprint details.
Click
.This will open a window with fields for user account creation.
- Fill in the details. Notice that when you insert the name, the User name field autocompletes, suggesting a username.
- Once you have inserted all the desired details, click .
The created user account appears showing all the information you have inserted.
- 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
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
.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.
Click on the blueprint name to display the blueprint details.
Click
.This will open a window with fields for user account creation
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.
- Once you have inserted all the desired details, click .
The new user account will appear in the user list, showing all the information you have inserted.
- If you want to create more user accounts for the blueprint, repeat the process.
Additional resources