Menu Close
Composing a customized RHEL system image
Creating customized system images with Image Builder on Red Hat Enterprise Linux 9
Abstract
Making open source more inclusive
Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.
Providing feedback on Red Hat documentation
We appreciate your input on our documentation. Please let us know how we could make it better.
For simple comments on specific passages:
- Make sure you are viewing the documentation in the Multi-page HTML format. In addition, ensure you see the Feedback button in the upper right corner of the document.
- Use your mouse cursor to highlight the part of text that you want to comment on.
- Click the Add Feedback pop-up that appears below the highlighted text.
- Follow the displayed instructions.
For submitting feedback via Bugzilla, create a new ticket:
- Go to the Bugzilla website.
- As the Component, use Documentation.
- Fill in the Description field with your suggestion for improvement. Include a link to the relevant part(s) of documentation.
- Click Submit Bug.
Chapter 1. Image Builder description
1.1. Introduction to Image Builder
You can use Image Builder to create customized system images of Red Hat Enterprise Linux, including system images prepared for deployment on cloud platforms. Image Builder automatically handles details of setup for each output type and is thus easier to use and faster to work with than manual methods of image creation. You can access Image Builder functionality through a command-line interface in the composer-cli
tool, or a graphical user interface in the RHEL web console.
As of Red Hat Enterprise Linux 8.3, the osbuild-composer
backend replaces lorax-composer
. The new service provides REST APIs for image building. As a result, users can benefit from a more reliable backend and more predictable output images.
Image Builder runs as a system service osbuild-composer
. You can interact with this service through two interfaces:
-
CLI tool
composer-cli
for running commands in the terminal. This method is preferred. - GUI plugin for the RHEL web console.
1.2. Image Builder terminology
- Blueprint
Blueprints define customized system images by listing packages and customizations that will be part of the system. Blueprints can be edited and they are versioned. When a system image is created from a blueprint, the image is associated with the blueprint in the Image Builder interface of the RHEL web console.
Blueprints are presented to the user as plain text in the TOML format.
- Compose
- Composes are individual builds of a system image, based on a particular version of a particular blueprint. Compose as a term refers to the system image, the logs from its creation, inputs, metadata, and the process itself.
- Customizations
- Customizations are specifications for the system, which are not packages. This includes users, groups, and SSH keys.
1.3. Image Builder output formats
Image Builder can create images in multiple output formats shown in the following table. To check the supported types, run the command:
# composer-cli compose types
Table 1.1. Image Builder output formats
Description | CLI name | file extension |
---|---|---|
QEMU QCOW2 Image |
|
|
TAR Archive |
|
|
Amazon Machine Image Disk |
|
|
Azure Disk Image |
|
|
VMware Virtual Machine Disk |
|
|
Openstack |
|
|
RHEL for Edge Commit |
|
|
RHEL for Edge Container |
|
|
RHEL for Edge Installer |
|
|
RHEL for Edge Raw |
|
|
RHEL for Edge Simplified Installer |
|
|
ISO image |
|
|
1.4. Image Builder system requirements
The environment where Image Builder runs, for example a dedicated virtual machine, must meet requirements listed in the following table.
Table 1.2. Image Builder system requirements
Parameter | Minimal Required Value |
---|---|
System type | A dedicated virtual machine |
Processor | 2 cores |
Memory | 4 GiB |
Disk space |
20 GiB free space at |
Access privileges | Administrator level (root) |
Network | Connectivity to Internet |
Internet connectivity is not a prerequisite. You can use Image Builder in isolated networks if you reconfigure it to not connect to Red Hat CDN.
Chapter 2. Installing Image Builder
Before using Image Builder, you must install Image Builder in a virtual machine.
2.1. Installing Image Builder in a virtual machine
To install Image Builder on a dedicated virtual machine, follow these steps:
Prerequisites
- Connect to the virtual machine.
- The virtual machine for Image Builder must be installed, subscribed to Red Hat Subscription Manager (RHSM) or Red Hat Satellite, and running.
Procedure
Install the Image Builder and other necessary packages on the virtual machine:
-
osbuild-composer
- supported from RHEL 8.3 onward -
composer-cli
-
cockpit-composer
-
bash-completion
# dnf install osbuild-composer composer-cli cockpit-composer bash-completion
The web console is installed as a dependency of the cockpit-composer package.
-
Enable Image Builder to start after each reboot:
# systemctl enable --now osbuild-composer.socket # systemctl enable --now cockpit.socket
The
osbuild-composer
andcockpit
services start automatically on first access.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
The osbuild-composer
package is the new backend engine that will be the preferred default and focus of all new functionality beginning with Red Hat Enterprise Linux 8.3 and later. The previous backend lorax-composer
package is considered deprecated, will only receive select fixes for the remainder of the Red Hat Enterprise Linux 8 life cycle and will be omitted from future major releases. It is recommended to uninstall lorax-composer
in favor of osbuild-composer.
Verification
You can use a system journal to track Image Builder service activities. Additionally, you can find the log messages in the file.
To find the journal output for traceback, run the following commands:
$ journalctl | grep osbuild
To show both remote or local workers:
$ journalctl -u osbuild-worker*
To show the running services:
$ journalctl -u osbuild-composer.service
Chapter 3. Managing repositories
3.1. Image Builder default system repositories
The osbuild-composer
backend does not inherit the system repositories located in the /etc/yum.repos.d/
directory. Instead, it has its own set of official repositories defined in the /usr/share/osbuild-composer/repositories
directory. To override the official repositories, you must define overrides in /etc/osbuild-composer/repositories
. This directory is for user defined overrides and the files located here take precedence over those in the /usr
directory.
The configuration files are not in the usual DNF repository format known from the files in /etc/yum.repos.d/
. Instead, they are simple JSON files.
3.2. Overriding a system repository
You can configure a repository override in the /etc/osbuild-composer/repositories
directory with the following steps.
Prerequisites
- You have a custom repository that is accessible from the host system
Procedure
Create a directory that contains the repository overrides you want to use:
$ sudo mkdir -p /etc/osbuild-composer/repositories
Create a JSON file with the following structure, for example:
{ "<ARCH>": [ { "name": "baseos", "metalink": "", "baseurl": "http://mirror.example.com/composes/released/RHEL-9/9.0/BaseOS/x86_64/os/", "mirrorlist": "", "gpgkey": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\n (…)", "check_gpg": true, "metadata_expire": "" } ] }
Specify only one of the following attributes:
metalink
,mirrorlist
, orbaseurl
. The remaining fields are optional.Save the JSON file using a name corresponding to your RHEL version, for example:
/etc/osbuild-composer/repositories/rhel-90.json
Alternatively, you can copy the JSON file for your distribution from
/usr/share/osbuild-composer/
and modify its content.Copy the repository file to the directory you created.
$ cp /usr/share/osbuild-composer/repositories/rhel-version.json /etc/osbuild-composer/repositories/
Replace rhel-version.json with your RHEL version, for example: rhel-9.json
Using a text editor, edit the
baseurl
paths in therhel-9.json
file. For example:$ vi /etc/osbuild-composer/repositories/rhel-9.json
As a result, the repository points to the correct URLs which are copied from the /etc/yum.repos.d/redhat.repo
file.
3.3. Overriding a system repository with support for subscriptions
osbuild-composer
service can use system subscriptions that are defined in the /etc/yum.repos.d/redhat.repo
file. To use a system subscription in osbuild-composer
, you need to define a repository override which has:
-
The same
baseurl
as the repository defined in/etc/yum.repos.d/redhat.repo
. -
The value of
”rhsm”: true
defined in the JSON object.
Prerequisites
-
System with a subscription defined in
/etc/yum.repos.d/redhat.repo
- You have created a repository override. See Overriding a system repository.
Procedure
Get the
baseurl
from the/etc/yum.repos.d/redhat.repo
file:[AppStream] name = AppStream mirror example baseurl = https://mirror.example.com/RHEL-9/9.0/AppStream/x86_64/os/ enabled = 1 gpgcheck = 0 sslverify = 1 sslcacert = /etc/pki/ca1/ca.crt sslclientkey = /etc/pki/ca1/client.key sslclientcert = /etc/pki/ca1/client.crt metadata_expire = 86400 enabled_metadata = 0
Configure the repository override to use the same
baseurl
and setrhsm
to true:{ "x86_64": [ { "name": "AppStream mirror example", "baseurl": "https://mirror.example.com/RHEL-9/9.0/AppStream/x86_64/os/", "gpgkey": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\n (…)", "check_gpg": true, "rhsm": true } ] }
osbuild-composer
does not automatically use repositories defined in /etc/yum.repos.d/
. You need to manually specify them either as a system repository override or as an additional source
using composer-cli
. System repository overrides are usually used for “BaseOS” and “AppStream” repositories, whereas composer-cli
sources are used for all the other repositories.
Additional resources
Chapter 4. Creating system images with Image Builder command-line interface
Image Builder is a tool for creating custom system images. To control Image Builder and create your custom system images, use the command-line interface which is currently the preferred method to use Image Builder.
4.1. Image Builder command-line interface
Image Builder command-line interface is currently the preferred method to use Image Builder. It offers more functionality than the web console interface. To use this interface, run the composer-cli
command with suitable options and subcommands.
The workflow for the command-line interface can be summarized as follows:
- Export (save) the blueprint definition to a plain text file
- Edit this file in a text editor
- Import (push) the blueprint text file back into Image Builder
- Run a compose to build an image from the blueprint
- Export the image file to download it
Apart from the basic subcommands to achieve this procedure, the composer-cli
command offers many subcommands to examine the state of configured blueprints and composes.
To run the composer-cli
commands as non-root, user must be in the weldr
or root
groups.
To add a user to the
weldr
orroot
groups, run the following commands:$ sudo usermod -a -G weldr user $ newgrp weldr
4.2. Creating an Image Builder blueprint with command-line interface
This procedure describes how to create a new Image Builder blueprint using the command-line interface.
Procedure
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.
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.6.0.
- For latest available version, use the asterisk *.
- For the latest minor version, use formats such as 8.*.
You can customize your blueprints in a number of ways. For this example, Simultaneous Multi Threading (SMT) can be disabled by performing the steps below. For additional customizations available, see Supported Image Customizations.
[customizations.kernel] append = "nosmt=force"
- Save the file as BLUEPRINT-NAME.toml and close the text editor.
Push (import) the blueprint:
# composer-cli blueprints push BLUEPRINT-NAME.toml
Replace BLUEPRINT-NAME with the value you used in previous steps.
List the existing blueprints to verify that the blueprint has been pushed and exists:
# composer-cli blueprints list
To display the blueprint configuration you have just added, run the command:
# composer-cli blueprints show
Check whether the components and versions listed in the blueprint and their dependencies are valid:
# composer-cli blueprints depsolve BLUEPRINT-NAME
To create images using the composer-cli
command as non-root, add your user to the weldr
or root
groups.
Verification
If Image Builder is unable to depsolve a package from your custom repositories, follow the steps:
Remove the osbuild-composer cache:
$ sudo rm -rf /var/cache/osbuild-composer/* $ sudo systemctl restart osbuild-composer
4.3. Editing an Image Builder blueprint with command-line interface
To edit an existing Image Builder blueprint in the command-line interface, follow the steps.
Procedure
Save (export) the blueprint to a local text file:
# composer-cli blueprints save BLUEPRINT-NAME
- Edit the BLUEPRINT-NAME.toml file with a text editor and make your changes.
Before finishing with the edits, make sure the file is a valid blueprint:
Remove this line, if present:
packages = []
- 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 version component increases automatically.
Check if the contents are valid TOML specifications. See the TOML documentation for more information.
NoteTOML 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
- Save the file and close the text editor.
Push (import) the blueprint back into Image Builder:
# composer-cli blueprints push BLUEPRINT-NAME.toml
NoteTo import the blueprint back into Image Builder, supply the file name including the
.toml
extension, while in other commands use only the blueprint name.To verify that the contents uploaded to Image Builder match your edits, list the contents of blueprint:
# composer-cli blueprints show BLUEPRINT-NAME
Check whether the components and versions listed in the blueprint and their dependencies are valid:
# composer-cli blueprints depsolve BLUEPRINT-NAME
4.4. Creating a system image with Image Builder in the command-line interface
This procedure shows how to build a custom image using the Image Builder command-line interface.
Prerequisites
- You have a blueprint prepared for the image.
Procedure
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 shows the composer Universally Unique Identifier (UUID).
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 a status value FINISHED. Identify the compose in the list by its UUID.
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.
Verification
After you create your image, you can check the image creation progress using the following commands:
Check the compose status:
$ sudo composer-cli compose status
Download the metadata of the image:
$ sudo composer-cli compose metadata UUID
Download the logs of the image:
$ sudo composer-cli compose logs UUID
The command creates a
.tar
file that contains the logs for the image creation. If the logs are empty, you can check the journal.Check the journal:
$ journalctl | grep osbuild
Check the manifest:
$ sudo cat /var/lib/osbuild-composer/jobs/job_UUID.json
You can find the job_UUID.json in the journal.
Additional resources
4.5. Basic Image Builder command-line commands
The Image Builder command-line interface offers the following subcommands.
Blueprint manipulation
- List all available blueprints
# composer-cli blueprints list
- Show a blueprint contents in the TOML format
# composer-cli blueprints show BLUEPRINT-NAME
- Save (export) blueprint contents in the TOML format into a file
BLUEPRINT-NAME.toml
# composer-cli blueprints save BLUEPRINT-NAME
- Remove a blueprint
# composer-cli blueprints delete BLUEPRINT-NAME
- Push (import) a blueprint file in the TOML format into Image Builder
# composer-cli blueprints push BLUEPRINT-NAME
Composing images from blueprints
- List the available image types
# composer-cli compose types
- Start a compose
# composer-cli compose start BLUEPRINT COMPOSE-TYPE
Replace BLUEPRINT with name of the blueprint to build and COMPOSE-TYPE with the output image type.
- List all composes
# composer-cli compose list
- List all composes and their status
# composer-cli compose status
- Cancel a running compose
# composer-cli compose cancel COMPOSE-UUID
- Delete a finished compose
# composer-cli compose delete COMPOSE-UUID
- Show detailed information about a compose
# composer-cli compose info COMPOSE-UUID
- Download image file of a compose
# composer-cli compose image COMPOSE-UUID
Additional resources
The composer-cli(1) manual page provides a full list of the available subcommands and options:
$ man composer-cli
The
composer-cli
command provides help on the subcommands and options:# composer-cli help
4.6. Image Builder blueprint format
Image Builder blueprints are presented to the user as plain text in the TOML format.
The elements of a typical blueprint file include:
- The blueprint metadata
name = "BLUEPRINT-NAME" description = "LONG FORM DESCRIPTION TEXT" version = "VERSION"
Replace BLUEPRINT-NAME and LONG FORM DESCRIPTION TEXT with a name and description for your blueprint.
Replace VERSION with a version number according to the Semantic Versioning scheme.
This part is present only once for the whole blueprint file.
The entry modules describe the package names and matching version glob to be installed into the image.
The entry group describes a group of packages to be installed into the image. Groups categorize their packages in:
- Mandatory
- Default
Optional
Blueprints installs the mandatory packages. There is no mechanism for selecting optional packages.
- Groups to include in the image
[[groups]] name = "group-name"
Replace group-name with the name of the group, such as anaconda-tools, widget, wheel or users.
- Packages to include in the image
[[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 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 the latest minor version, use format such as 8.*.
Repeat this block for every package to include.
4.7. Supported Image Customizations
A number of image customizations are supported within blueprints. To make use of these options, you must initially configure the customizations in the blueprint and import (push) it to Image Builder.
These customizations are not currently supported within the web console.
- Set the image hostname
[customizations] hostname = "baseimage"
- User specifications for the resulting system image
[[customizations.user]] name = "USER-NAME" description = "USER-DESCRIPTION" password = "PASSWORD-HASH" key = "PUBLIC-SSH-KEY" home = "/home/USER-NAME/" shell = "/usr/bin/bash" groups = ["users", "wheel"] uid = NUMBER gid = NUMBER
NoteThe GID is optional and must already exist in the image, be created by a package, or be created by the blueprint
[[customizations.group]]
entry.ImportantTo generate the hash, you must install python3 on your system. The following command installs the python3 package.
# dnf install python3
Replace PASSWORD-HASH with the actual password hash. To generate the hash, use a command such as:
$ python3 -c 'import crypt,getpass;pw=getpass.getpass();print(crypt.crypt(pw) if (pw==getpass.getpass("Confirm: ")) else exit())'
Replace PUBLIC-SSH-KEY 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.
Repeat this block for every user to include.
- Group specifications for the resulting system image
[[customizations.group]] name = "GROUP-NAME" gid = NUMBER
Repeat this block for every group to include.
- Set an existing users ssh key
[[customizations.sshkey]] user = "root" key = "PUBLIC-SSH-KEY"
NoteThis option is only applicable for existing users. To create a user and set an ssh key, see the User specifications for the resulting system image customization in this section.
- Append a kernel boot parameter option to the defaults
[customizations.kernel] append = "KERNEL-OPTION"
- By default, Image Builder builds a default kernel into the image. But, you can customize the kernel with the following configuration in blueprint
[customizations.kernel] name = "KERNEL-rt"
- Define a kernel name to be used in an image
[customizations.kernel.name] name = "KERNEL-NAME"
- Set the timezone and the Network Time Protocol (NTP) servers for the resulting system image
[customizations.timezone] timezone = "TIMEZONE" ntpservers = "NTP_SERVER"
If you do not set a timezone, the system uses Universal Time, Coordinated (UTC) as default. Setting NTP servers is optional.
- Set the locale settings for the resulting system image
[customizations.locale] languages = ["LANGUAGE"] keyboard = "KEYBOARD"
Setting both language and keyboard options is mandatory. You can add multiple languages. The first language you add will be the primary language and the other languages will be secondary.
- Set the firewall for the resulting system image
[customizations.firewall] port = ["PORTS"]
You can use the numeric ports, or their names from the
/etc/services
file to enable lists.- Customize the firewall services
Review the available firewall services.
$ firewall-cmd --get-services
In the blueprint, under section
customizations.firewall.service
, specify the firewall services that you want to customize.[customizations.firewall.services] enabled = ["SERVICES"] disabled = ["SERVICES"]
The services listed in
firewall.services
are different from the names available in the/etc/services
file.You can optionally customize the firewall services for the system image that you plan to create.
NoteIf you do not want to customize the firewall services, omit the
[customizations.firewall]
and[customizations.firewall.services]
sections from the blueprint.- Set which services to enable during the boot time
[customizations.services] enabled = ["SERVICES"] disabled = ["SERVICES"]
You can control which services to enable during the boot time. Some image types already have services enabled or disabled so that the image works correctly and this setup cannot be overridden.
NoteEach time a build starts, it clones the repository. If you refer to a repository with a large amount of history, it might take a while to clone and use a significant amount of disk space. Also, the clone is temporary and is removed after the RPM package is created.
- Specify a custom filesystem configuration
You can specify a custom filesystem configuration in your blueprints and thus create images with a specific disk layout, instead of using the default layout configuration. By using the non-default layout configuration in your blueprints, you can benefit from:
- security benchmark compliance
- protection against out-of-disk errors
- performance
consistency with existing setups
Customize the filesystem configuration in your blueprint:
[[customizations.filesystem]] mountpoint = "MOUNTPOINT" size = MINIMUM-PARTITION-SIZE
The following
mountpoints
and their sub-directories are supported:-
/
- the root mount point -
/var
-
/home
-
/opt
-
/srv
-
/usr
-
/app
/data
NoteCustomizing mountpoints is only supported from RHEL 8.5 and RHEL 9.0 distributions onward, using the CLI. In early distributions, you can only specify the
root
partition as a mount point and specify thesize
argument as an alias for the image size.If you have more than one partition, you can create images with a customized file system partition on LVM and resize those partitions at runtime. For that, you can specify a customized filesystem configuration in your blueprint and then create images with the desired disk layout. The default filesystem layout remains unchanged - if you use plain images without file system customization, the root partition is resized by
cloud-init
.After you add a file system customization to your blueprint, the file system is converted to a LVM partition.
When you define the MINIMUM-PARTITION-SIZE, there is no default size format. The following values and units are supported: kB to TB and KiB to TiB. For example, you can define the mountpoint size in bytes:
[[customizations.filesystem]] mountpoint = "/var" size = 1073741824
You can also define the mountpoint size using units.
NoteYou can only define the mountpoint size using units for package version provided for RHEL 8.6 and RHEL 9.0 distributions onward.
For example:
[[customizations.filesystem]] mountpoint = "/opt" size = "20 GiB"
-
Additional resources
4.8. Installed Packages
When you create a system image using Image Builder, by default, the system installs a set of base packages. The base list of packages are the members of the comps core
group. By default, Image Builder uses the core dnf
group.
Table 4.1. Default packages to support image type creation
Image type | Default Packages |
---|---|
ami | checkpolicy, chrony, cloud-init, cloud-utils-growpart, @Core, dhcp-client, gdisk, insights-client, kernel, langpacks-en, net-tools, NetworkManager, redhat-release, redhat-release-eula, rng-tools, rsync, selinux-policy-targeted, tar, yum-utils |
openstack | @Core, langpacks-en |
qcow2 | @core, chrony, dnf, kernel, dnf, nfs-utils, dnf-utils, cloud-init, python3-jsonschema, qemu-guest-agent, cloud-utils-growpart, dracut-norescue, tar, tcpdump, rsync, dnf-plugin-spacewalk, rhn-client-tools, rhnlib, rhnsd, rhn-setup, NetworkManager, dhcp-client, cockpit-ws, cockpit-system, subscription-manager-cockpit, redhat-release, redhat-release-eula, rng-tools, insights-client |
tar | policycoreutils, selinux-policy-targeted |
vhd | @Core, langpacks-en |
vmdk | @core, chrony, cloud-init, firewalld, langpacks-en, open-vm-tools, selinux-policy-targeted |
edge-commit | attr, audit, basesystem, bash, bash-completion, chrony, clevis, clevis-dracut, clevis-luks, container-selinux, coreutils,criu, cryptsetup, curl, dnsmasq, dosfstools, dracut-config-generic, dracut-network, e2fsprogs, firewalld, fuse-overlayfs, fwupd, glibc, glibc-minimal-langpack, gnupg2, greenboot, gzip, hostname, ima-evm-utils, iproute, iptables, iputils, keyutils, less, lvm2, NetworkManager, NetworkManager-wifi, NetworkManager-wwan, nss-altfiles, openssh-clients, openssh-server, passwd, pinentry, platform-python, podman, policycoreutils, policycoreutils-python-utils, polkit, procps-ng, redhat-release, rootfiles, rpm, rpm-ostree, rsync, selinux-policy-targeted, setools-console, setup, shadow-utils, shadow-utils, skopeo, slirp4netns, sudo, systemd, tar, tmux, traceroute, usbguard, util-linux, vim-minimal, wpa_supplicant, xz |
edge-container | dnf, dosfstools, e2fsprogs, glibc, lorax-templates-generic, lorax-templates-rhel, lvm2, policycoreutils, python36, python3-iniparse, qemu-img, selinux-policy-targeted, systemd, tar, xfsprogs, xz |
edge-installer | aajohan-comfortaa-fonts, abattis-cantarell-fonts, alsa-firmware, alsa-tools-firmware, anaconda, anaconda-install-env-deps, anaconda-widgets, audit, bind-utils, bitmap-fangsongti-fonts, bzip2, cryptsetup, dbus-x11, dejavu-sans-fonts, dejavu-sans-mono-fonts, device-mapper-persistent-data, dnf, dump, ethtool, fcoe-utils, ftp, gdb-gdbserver, gdisk, gfs2-utils, glibc-all-langpacks, google-noto-sans-cjk-ttc-fonts, gsettings-desktop-schemas, hdparm, hexedit, initscripts, ipmitool, iwl3945-firmware, iwl4965-firmware, iwl6000g2a-firmware, iwl6000g2b-firmware, jomolhari-fonts, kacst-farsi-fonts, kacst-qurn-fonts, kbd, kbd-misc, kdump-anaconda-addon, khmeros-base-fonts, libblockdev-lvm-dbus, libertas-sd8686-firmware, libertas-sd8787-firmware, libertas-usb8388-firmware, libertas-usb8388-olpc-firmware, libibverbs, libreport-plugin-bugzilla, libreport-plugin-reportuploader, libreport-rhel-anaconda-bugzilla, librsvg2, linux-firmware, lklug-fonts, lldpad, lohit-assamese-fonts, lohit-bengali-fonts, lohit-devanagari-fonts, lohit-gujarati-fonts, lohit-gurmukhi-fonts, lohit-kannada-fonts, lohit-odia-fonts, lohit-tamil-fonts, lohit-telugu-fonts, lsof, madan-fonts, metacity, mtr, mt-st, net-tools, nmap-ncat, nm-connection-editor, nss-tools, openssh-server, oscap-anaconda-addon, pciutils, perl-interpreter, pigz, python3-pyatspi, rdma-core, redhat-release-eula, rpm-ostree, rsync, rsyslog, sg3_utils, sil-abyssinica-fonts, sil-padauk-fonts, sil-scheherazade-fonts, smartmontools, smc-meera-fonts, spice-vdagent, strace, system-storage-manager, thai-scalable-waree-fonts, tigervnc-server-minimal, tigervnc-server-module, udisks2, udisks2-iscsi, usbutils, vim-minimal, volume_key, wget, xfsdump, xorg-x11-drivers,xorg-x11-fonts-misc,xorg-x11-server-utils,xorg-x11-server-Xorg, xorg-x11-xauth |
edge-simplified-installer | attr, basesystem, binutils, bsdtar, clevis-dracut, clevis-luks, cloud-utils-growpart, coreos-installer, coreos-installer-dracut, coreutils, device-mapper-multipath, dnsmasq, dosfstools, dracut-live, e2fsprogs, fcoe-utils, fdo-init, gzip, ima-evm-utils, iproute, iptables, iputils, iscsi-initiator-utils, keyutils, lldpad, lvm2, passwd, policycoreutils, policycoreutils-python-utils, procps-ng, rootfiles, setools-console, sudo, traceroute, util-linux |
image-installer | anaconda-dracut, curl, dracut-config-generic, dracut-network, hostname, iwl100-firmware, iwl1000-firmware, iwl105-firmware, iwl135-firmware, iwl2000-firmware, iwl2030-firmware, iwl3160-firmware, iwl5000-firmware, iwl5150-firmware, iwl6000-firmware, iwl6050-firmware, iwl7260-firmware, kernel, less, nfs-utils, openssh-clients, ostree, plymouth, prefixdevname, rng-tools, rpcbind, selinux-policy-targeted, systemd, tar, xfsprogs, xz |
edge-raw-image | dnf, dosfstools, e2fsprogs, glibc, lorax-templates-generic, lorax-templates-rhel, lvm2, policycoreutils, python36, python3-iniparse, qemu-img, selinux-policy-targeted, systemd, tar, xfsprogs, xz |
When you add additional components to your blueprint, you must make sure that the packages in the components you added do not conflict with any other package components, otherwise the system fails to solve dependencies. As a consequence, you are not able to create your customized image.
Additional resources
4.9. Enabled Services
When you configure the custom image, the services enabled are the defaults services for the RHEL release you are running osbuild-composer
from, additionally the services enabled for specific image types.
For example, the .ami
image type enables the services sshd
, chronyd
and cloud-init
and without these services, the custom image does not boot.
Table 4.2. Enabled services to support image type creation
Image type | Enabled Services |
---|---|
ami | sshd, cloud-init, cloud-init-local, cloud-config, cloud-final |
openstack | sshd, cloud-init, cloud-init-local, cloud-config, cloud-final |
qcow2 | cloud-init |
rhel-edge-commit | No extra service enables by default |
tar | No extra service enables by default |
vhd | sshd, chronyd, waagent, cloud-init, cloud-init-local, cloud-config, cloud-final |
vmdk | sshd, chronyd, vmtoolsd, cloud-init |
Note: You can customize which services to enable during the system boot. However, for image types with services enabled by default, the customization does not override this feature.
Additional resources
Chapter 5. 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.
5.1. Accessing Image Builder GUI in the RHEL web console
The cockpit-composer plugin for the RHEL 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 on how to remotely access Image Builder, see Managing systems using the RHEL web console document.
- Log into the web console with credentials for a 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
5.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 web console in a browser.
Procedure
Click Create Blueprint 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 Create.
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 Enter.The search is added to the list of filters under the text entry field, and the list of components below is reduced to those 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 Add in the top left.
-
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.
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 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.
To exit the editing screen, click
Back to Blueprints
in the top left.The Image Builder view opens, listing existing blueprints.
5.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 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 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.
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 Edit Blueprint button that belongs to the blueprint.
The view changes to the blueprint editing screen.
-
Remove unwanted components by clicking their ⫶ button at the far right of its entry in the right pane, and select
Remove
in the menu. 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 Enter.The search is added to the list of filters under the text entry field, and the list of components below is reduced to those 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 select
View
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 Apply Change 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 Enter.The search is added to the list of filters under the text entry field, and the list of components below is reduced to those 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 Add 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 select
Remove
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 Commit button in top right.
A pop-up window with a summary of your changes appears.
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.
In the top left, click Back to Blueprints to exit the editing screen.
The Image Builder view opens, listing existing blueprints.
5.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:# dnf install editor-name
Procedure
- Find out the name of the blueprint: Open the Image Builder (Image builder) tab on the left in the RHEL 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 text editor and add the users and groups.
ImportantRHEL 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 text 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 web console does not show any information that could be used to verify that the changes have been applied, unless you also edited 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.
5.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 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 those 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 Create Image button that belongs to the blueprint.
A pop-up window appears.
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.
Click the name of the blueprint.
A screen with details of the blueprint opens.
Click the Images tab to switch to it. The image that is being created is listed with the status
In 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 Stop button on the right.
- After the image is successfully created, the Stop button is replaced by a Download button. Click this button to download the image to your system.
5.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 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 Add Source button.
Add the desired Source name, the Source path, and the Source Type. The Security field is optional.
- Click Add Source button. The screen shows the available sources window and lists the source you have added.
As a result, the new System source is available and ready to be used or edited.
5.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 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 Create User Account.
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.
- After you have inserted all the desired details, click Create.
The created user account appears showing all the information you have inserted.
- To create further user accounts for the blueprint, repeat the process.
5.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 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 Create User Account.
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.
- After you have inserted all the desired details, click Create.
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
Chapter 6. Creating a boot ISO installer image with Image Builder
You can use Image Builder to create bootable ISO Installer images. These images consist of a tarball that contains a root file system. You can use the bootable ISO image to install the file system to a bare metal server.
Image Builder builds a manifest that creates a boot ISO that contains the commit and a root file system. To create the ISO image, choose the new image type image-installer. Image Builder builds a .tar
file, which contains:
- a standard Anaconda installer ISO
- an embedded RHEL system tarball
- a default kickstart file that installs the commit with minimal default requirements
The created installer ISO image embeds a pre-configured system image that you can install directly to a bare metal server.
6.1. Creating a boot ISO installer image with Image Builder in the command-line interface
This procedure shows how to build a custom boot ISO installer image using the Image Builder command-line interface.
Prerequisites
- You created a blueprint for the image with a user included and pushed it back into Image Builder. See Blueprint customization for users.
Procedure
Create the ISO image:
# composer-cli compose start BLUEPRINT-NAME image-installer
- BLUEPRINT-NAME with name of the blueprint you created
image-installer is the image type
The compose process starts in the background and the UUID of the compose is shown.
Wait until the compose is finished. Note that this may take several minutes.
To check the status of the compose:
# composer-cli compose status
A finished compose shows a status value of FINISHED. Identify the compose in the list by its UUID.
After 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.
As a result, Image Builder builds a
.tar
file that contains the ISO Installer image.
Verification
- Navigate to the folder where you downloaded the image file.
-
Locate the
.tar
image you downloaded. -
Extract the
.tar
content.
You can use the resulting ISO image file on a hard drive or to boot in a virtual machine, for example, in an HTTP Boot or a USB installation.
6.2. Creating a boot ISO installer image with Image Builder in the GUI
You can build a customized boot ISO installer image using Image Builder GUI.
Prerequisites
- You created a blueprint for your image.
Procedure
- Open the Image Builder interface of the RHEL web console in a browser.
- Locate the blueprint that you want to build your image by entering its name or a part of it into the search box at top left, and click Enter.
On the right side of the blueprint, click the Create Image button that belongs to the blueprint.
The Create image dialog wizard opens.
On the Create image dialog wizard, from the Image Type list:
- Select the "RHEL Installer (.iso)" image type.
- Click Create.
Image Builder adds the compose of a RHEL .iso image to the queue.
The image build process take a few minutes to complete.
After the process is complete, you can see the Image build complete status. Image Builder creates the .iso image.
Verification
After the image is successfully created, you can download your image button.
- Click Download to save the "RHEL Installer (.iso)" image to your system.
- Navigate to the folder where you downloaded the "RHEL Installer (.iso)" image.
- Locate the .tar image you downloaded.
- Extract the "RHEL Installer (.iso)" image content.
You can use the resulting ISO image file on a hard drive or to boot in a virtual machine, for example, in an HTTP Boot or a USB installation.
6.3. Installing the ISO image to a bare metal system
This procedure shows how to install the bootable ISO image you created by using Image Builder to a bare metal system, using the command-line interface.
Prerequisites
- You created the bootable ISO image using Image Builder.
- You have downloaded and extracted the bootable ISO image.
You have a 8 GB USB flash drive.
NoteThe ISO size can be bigger depending on the packages that you selected in your blueprint.
Procedure
- Place the bootable ISO image file on a USB flash drive.
- Connect the USB flash drive to the port of the computer you want to boot.
- Boot the ISO image from the USB flash drive.
Perform the steps to install the customized bootable ISO image.
The boot screen shows you the following options:
- Install Red Hat Enterprise Linux 9
- Test this media & install Red Hat Enterprise Linux 9
Additional resources
Chapter 7. Preparing and deploying KVM guest images with Image Builder
Customers can manually create images from an ISO or have a purpose-built image created using Image Builder. This procedure describes steps to create a purpose-built image using Image Builder. This is limited to rhel-guest-image
support to Red Hat Virtualization (RHV).
Creating a customized KVM guest image following involves the following high-level steps:
-
Creating a KVM guest Image
.qcow2
image using Image Builder. - Creating a virtual machine from the KVM guest image.
7.1. Creating customized KVM guest images with Image Builder
This describes steps to create a .qcow2
KVM guest image using Image Builder.
Prerequisites
- You must have root or wheel group user access to the system.
-
The
cockpit-composer
package is installed. - On a RHEL system, you have opened the Image Builder dashboard of Cockpit UI.
Procedure
- Click Create blueprint to create a blueprint. See Creating an Image Builder blueprint in the web console interface.
- Select the components and packages that you want as part of the KVM guest image you are creating.
- Click Commit to commit the changes you made to the blueprint. A small pop-up on the superior right side informs you of the saving progress and then the result of the changes you commited.
- Click the blueprint name link on the left banner.
- Select the tab Images.
- Click Create Image to create your customized image. A pop-up window opens.
- From the Type drop-down menu list, select the `QEMU Image(.qcow2)' image.
- Set the size that you want the image to be when instantiated and click Create.
- A small pop-up on the upper right side of the window informs you that the image creation has been added to the queue. After the image creation process is complete, you can see the Image build complete status.
Verification steps
-
Click the breadcrumbs icon and select the Download option. Image Builder downloads the KVM guest image
.qcow2
file at your default download location.
Additional resources
7.2. Creating a virtual machine from a KVM guest image
To quickly create virtual machines with small footprint on the host, you can use a KVM guest image. This procedure uses a KVM guest image generated by Image Builder as a .qcow2
image format to create a Virtual Machine (VM). KVM guest images created using Image Builder already have cloud-init
installed and enabled.
Prerequisites
-
You created a
.qcow2
image using Image Builder. See Creating an Image Builder blueprint in the web console interface. -
The
qemu-kvm
package is installed on your system. You can check the/dev/kvm
folder is available on your system. -
You have
libvirt
installed on your system. -
You have
virt-install
installed on your system. -
The
genisoimage
utility is installed on your system.
Procedure
-
Move the KVM Guest Image you created using Image Builder to the
/var/lib/libvirt/images
directory and rename the image name torhel-8.4-x86_64-kvm.qcow2
. Create a directory, for example,
cloudinitiso
and navigate to this newly created directory:$ mkdir cloudinitiso $ cd cloudinitiso
Create a file named
meta-data
. Add the following information to this file:instance-id: citest local-hostname: citest-1
Create a file named
user-data
. Add the following information to the file:#cloud-config user: admin password: cilogon chpasswd: {expire: False} ssh_pwauth: True ssh_authorized_keys: - ssh-rsa AAA...fhHQ== your.email@example.com
Where,
-
ssh_authorized_keys
is your SSH public key. You can find your SSH public key in~/.ssh/id_rsa.pub
.
-
Use the
genisoimage
command to create an ISO image that includes theuser-data
andmeta-data
files.# genisoimage -output ciiso.iso -volid cidata -joliet -rock user-data meta-data I: -input-charset not specified, using utf-8 (detected in locale settings) Total translation table size: 0 Total rockridge attributes bytes: 331 Total directory bytes: 0 Path table size(bytes): 10 Max brk space used 0 183 extents written (0 MB)
Create a new VM from the KVM Guest Image using the
virt-install
command. Include the ISO image you created on step 4 as an attachment to the VM image.# virt-install \ --memory 4096 \ --vcpus 4 \ --name mytestcivm \ --disk /var/lib/libvirt/images/rhel-8.4-x86_64-kvm.qcow2,device=disk,bus=virtio,format=qcow2 \ --disk /home/sample/cloudinitiso/ciiso.iso,device=cdrom \ --os-variant rhel8.4 \ --virt-type kvm \ --graphics none \ --import
Where,
- --graphics none - means it is a headless RHEL 8.4 VM.
- --vcpus 4 - means that it uses 4 virtual CPUs.
- --memory 4096 - means it uses 4096 MB RAM.
The VM installation starts:
Starting install... Connected to domain mytestcivm ... [ OK ] Started Execute cloud user/final scripts. [ OK ] Reached target Cloud-init target. Red Hat Enterprise Linux 8.4 Beta (Ootpa) Kernel 4.18.0-221.el8.x86_64 on an x86_64
Verification
-
Log in to the created VM, using
cloud-user
as a username. Your password iscilogon
.
Additional resources
Chapter 8. Preparing and Uploading cloud images with Image Builder
Image Builder can create custom system images ready for use in clouds of various providers. To use your customized RHEL system image in a cloud, create the system image with Image Builder using the respective output type, configure your system for uploading the image, and upload the image to your cloud account. From Red Hat Enterprise Linux 8.3, the ability to push customized image clouds through the Image Builder
application in the RHEL web console is available for a subset of the service providers that we support, such as AWS and Azure clouds. See Pushing images to AWS Cloud AMI and Pushing VHD images to Azure cloud.
8.1. Preparing for uploading AWS AMI images
This describes steps to configure a system for uploading AWS AMI images.
Prerequisites
- You must have an Access Key ID configured in the AWS IAM account manager.
- You must have a writable S3 bucket prepared.
Procedure
Install Python 3 and the
pip
tool:# dnf install python3 # dnf install python3-pip
Install the AWS command-line tools with
pip
:# pip3 install awscli
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]:
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.
Then, to grant permission to access the S3 bucket, create a
vmimport
S3 Role in 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
Additional resources
8.2. Uploading an AMI image to AWS in the CLI
You can use Image Builder to build .ami
images and push them directly to Amazon AWS Cloud service provider using the CLI.
Prerequisites
Procedure
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
,region
. TheIMAGE_KEY
value is the name of your VM Image to be uploaded to EC2.- Save the file as CONFIGURATION-FILE.toml and close the text editor.
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.
NoteYou 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.
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.
Verification
To confirm that the image upload was successful:
- Access EC2 on the menu and choose the correct region in the AWS console. The image must have the "available" status, to indicate that it was successfully uploaded.
- On the dashboard, select your image and click Launch.
Additional Resources
8.3. Pushing images to AWS Cloud AMI
The ability to push the output image that you create to AWS Cloud AMI is available this time. This describes steps to push .ami
images you create using Image Builder to Amazon AWS Cloud service provider.
Prerequisites
Procedure
- Click Create blueprint to create a blueprint. See Creating an Image Builder blueprint in the web console interface.
- Select the components and packages that you want as part of the image you are creating.
Click Commit to commit the changes you made to the blueprint.
A small pop-up on the superior right side informs you of the saving progress and then the result of the changes you commited.
- Click blueprint name link on the left banner.
- Select the tab Images.
Click Create Image to create your customized image.
A pop-up window opens.
- From the "Type" drop-down menu list, select the `"Amazon Machine Image Disk (.ami)"' image.
- Check the "Upload to AWS" check box to upload your image to the AWS Cloud and click Next.
To authenticate your access to AWS, type your "AWS access key ID" and "AWS secret access key" in the corresponding fields. Click Next.
NoteYou 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.
- 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.
Review the information and click Finish.
Optionally, you can click Back to modify any incorrect detail.
NoteYou must have the correct IAM settings for the bucket you are going to send your customized image. We are using 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.
A small pop-up on the superior right side 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.
- 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.
- On the dashboard, select your image and click Launch.
- A new window opens. Choose an instance type according to the resources you need to launch your image. Click Review and Launch.
- Review your instance launch details. You can edit each section if you need to make any change. Click Launch
Before you launch the instance, you must 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 SSH key for more details.Follow the next steps to create a new key pair in EC2 and attach it to the new instance.
- From the drop-down menu list, select "Create a new key pair".
- Enter the name to the new key pair. It generates a new key pair.
- Click "Download Key Pair" to save the new key pair on your local system.
Then, you can click Launch Instance to launch your instance.
You can check the status of the instance, it shows as "Initializing".
- After the instance status is "running", the Connect button becomes available.
Click Connect. A popup window appears with instructions on how to connect using SSH.
- Select the preferred connection method to "A standalone SSH client" and open a terminal.
In the location you store your private key, make sure that your key is publicly viewable for SSH to work. To do so, run the command:
$ chmod 400 <your-instance-name.pem>_
Connect to your instance using its Public DNS:
$ ssh -i "<_your-instance-name.pem_"> ec2-user@<_your-instance-IP-address_>
Type "yes" to confirm that you want to continue connecting.
As a result, you are connected to your instance using SSH.
Verification steps
- Check if you are able to perform any action while connected to your instance using SSH.
8.4. Preparing for uploading Azure VHD images
This describes steps to upload an VHD image to Azure.
Prerequisites
- You must have a usable Azure resource group and storage account.
Procedure
Install python2:
# dnf install python2
Notepython2 package must be installed because since the AZ CLI depends specifically on python 2.7
Import the Microsoft repository key:
# rpm --import https://packages.microsoft.com/keys/microsoft.asc
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'
Install the Azure CLI:
# dnfdownloader azure-cli # rpm -ivh --nodeps azure-cli-2.0.64-1.el7.x86_64.rpm
NoteThe downloaded version of the Azure CLI package may vary depending on the current downloaded version.
Run the Azure CLI:
$ az login
The terminal shows the message 'Note, we have launched a browser for you to login. For old experience with device code, use "az login --use-device-code"' and open a browser where you can login.
NoteIf you are running a remote (SSH) session, the link will not open in the browser. In this case, you can use the link provided and thus be able to login and authenticate your remote session. To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code XXXXXXXXX to authenticate.
List the keys for the storage account in 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 the Azure resource group and storage-account-name with name of the Azure storage account.
NoteYou can list the available resources using the command:
$ az resource list
Make note of value
key1
in the output of the previous command, and assign it to an environment variable:$ KEY1=value
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.
Additional resources
8.5. Uploading VHD images to Azure
This describes steps to upload an VHD image to Azure.
Prerequisites
- Your system must be set up for uploading Azure VHD images.
You must have an Azure VHD image created by Image Builder. Use the
vhd
output type in CLI or Azure Disk Image (.vhd) in GUI when creating the image.NoteWhen creating a
.vhd
image using the CLI, Image Builder writes temporary files to the/var
subdirectory. To avoid the.vhd
image creation to fail, increase the/var
subdirectory capacity to at least 15 to 20 GB free space to ensure availability.
Procedure
Push the image to Azure and create an instance from it:
$ VHD=25ccb8dd-3872-477f-9e3d-c2970cd4bbaf-disk.vhd $ az storage blob upload --account-name $ACCOUNT --container-name $CONTAINER --file $VHD --name $VHD --type page ...
After the upload to the Azure BLOB completes, create an Azure image from it:
$ az image create --resource-group $GROUP --name $VHD --os-type linux --location eastus --source https://$ACCOUNT.blob.core.windows.net/$CONTAINER/$VHD - Running ...
Create an instance either with the 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 ...
-
Use your private key via SSH to access the resulting instance. Log in as
azure-user
.
8.6. Uploading VMDK images to vSphere
Image Builder can generate images suitable for uploading to a VMware ESXi or vSphere system. This describes steps to upload an VMDK image to VMware vSphere.
Prerequisites
-
You must have an VMDK image created by Image Builder. Use the
vmdk
output type in CLI or VMware Virtual Machine Disk (.vmdk) in GUI when creating the image.
Procedure
Upload the image into vSphere via HTTP. Click on
Upload Files
in the vCenter:When you create a VM, on the
Device Configuration
, delete the defaultNew Hard Disk
and use the drop-down to select anExisting Hard Disk
disk image:Make sure you use an
IDE
device as theVirtual Device Node
for the disk you create. The default valueSCSI
results in an unbootable virtual machine.
8.7. Pushing VMware images to vSphere
You can build VMware images and push them directly to your vSphere instance, to avoid having to download the image file and push it manually. This describes steps to push .vmdk
images you create using Image Builder directly to vSphere instances service provider.
Prerequisites
-
You have
root
orwheel
group user access to the system. - You have opened the Image Builder interface of the RHEL web console in a browser.
- You have a vSphere Account.
Procedure
Click Create blueprint.
See Creating an Image Builder blueprint in the web console interface.
- Select the components and packages that you want as part of the image you are creating.
Click Commit to commit the changes you made to the blueprint.
A pop-up on the upper right side informs you of the saving progress and then the result of the changes you commited.
- Click blueprint name link on the left banner.
Select the Customizations tab to create a user account for the blueprint.
- Select the Images tab .
Click Create Image to create your customized image.
The Image type window opens.
In the Image type window:
- From the dropdown menu, select the Type: VMware VSphere (.vmdk).
- Check the Upload to VMware checkbox to upload your image to the vSphere.
- Optional: Set the size of the image you want to instantiate. The minimal default size is 2GB.
- Click Next.
In the Upload to VMware window, under Authentication, enter the following details:
- Username: username of the vSphere account.
- Password: pasword of the vSphere account.
In the Upload to VMware window, under Destination, enter the following details:
- Image name: a name for the image to be uploaded.
- Host: The URL of your VMware vSphere where the image will be uploaded.
- Cluster: The name of the cluster where the image will be uploaded.
- Data center: The name of the datacenter where the image will be uploaded.
- Data store:The name of the Data store where the image will be uploaded.
- Click Next.
In the Review window, review the details about 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.
NoteThe image build and upload processes take a few minutes to complete.
After the process is complete, you can see the Image build complete status.
Verification
After the image status upload is completed successfully, you can create a Virtual Machine (VM) from the image you uploaded and login into it. Follow the steps for that:
- Access VMware vSphere Client.
- Search for the image in the Cluster on the vSphere instance you specified.
You can create a new Virtual Machine from the image you uploaded. For that:
- Select the image you uploaded.
- Click the right button on the selected image.
Click New Virtual Machine.
A New Virtual Machine window opens.
In the New Virtual Machine window, provide the following details:
- Select a creation type: You can choose to create a New Virtual Machine.
- Select a name and a folder: For example, Virtual Machine name: vSphere Virtual Machine and location of your choice inside vSphere Client.
- Select a computer resource: choose a destination computer resource for this operation.
- Select storage: For example, select NFS-Node1
- Select compatibility: The image should be BIOS only.
- Select a guest OS: For example, select Linux and _Red Hat Fedora (64-bit).
- Customize hardware: When you create 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:
- Ready to complete: Review the details and click Finish to create the image.
Navigate to the VMs tab.
- From the list, select the VM you created.
- Click the Start button from the panel. A new window appears, showing the VM image loading.
- Log in with the credentials you created for the blueprint.
You can verify if the packages you added to the blueprint are installed. For example:
$ rpm -qa | grep firefox
Additional resources
8.8. Pushing VHD images to Azure cloud
You can create .vhd
images using Image Builder. Then, you can push the .vhd
images to a Blob Storage of the Azure Cloud service provider.
Prerequisites
- You must have root access to the system.
- You have opened the Image Builder interface of the RHEL web console in a browser.
- You must have a Storage Account created.
- You must have a writable Blob Storage prepared.
Procedure
- Click Create blueprint to create a blueprint. See Creating an Image Builder blueprint in the web console interface.
- Select the components and packages that you want as part of the image you are creating.
Click Commit to commit the changes you made to the blueprint.
A small pop-up on the upper right side informs you of the saving progress and then the result of the changes you commited.
- Click blueprint name link on the left banner.
- Select the tab Images.
Click Create Image to create your customized image.
A pop-up window opens.
-
From the "Type" drop-down menu list, select the
Azure Disk Image (.vhd)
image. - Check the "Upload to Azure" check box to upload your image to the Azure Cloud and click Next.
To authenticate your access to Azure, type your "Storage account" and "Storage access key" in the corresponding fields. Click Next.
You can find your Storage account details in the Settings→Access Key menu list.
- Type a "Image name" to be used for the image file that will be uploaded and the Blob "Storage container" in which the image file you want to push the image into. Click Next.
Review the information you provided and click Finish.
Optionally, you can click Back to modify any incorrect detail.
-
From the "Type" drop-down menu list, select the
A small pop-up on the upper right side displays when the image creation process starts with the message: "Image creation has been added to the queue".
After the image process creation is complete, click the blueprint you created an image from. You can see the "Image build complete" status for the image you created within the
Images
tab.- To access the image you pushed into Azure Cloud, access Azure Portal.
- On the search bar, type Images and select the first entry under Services. You are redirected to the Image dashboard.
Click +Add. You are redirected to the Create an Image dashboard.
Insert the below details:
- Name: Choose a name for your new image.
- Resource Group: Select a resource group.
- Location: Select the location that matches the regions assigned to your storage account. Otherwise you will not be able to select a blob.
- OS Type: Set the OS type to Linux.
- VM Generation: Keep the VM generation set on Gen 1.
Storage Blob: Click Browse on the right of Storage blob input. Use the dialog to find the image you uploaded earlier.
Keep the remaining fields as in the default choice.
- Click Create to create the image. After the image is created, you can see the message "Successfully created image" in the upper right corner.
- Click Refresh to see your new image and open your newly created image.
- Click + Create VM. You are redirected to the Create a virtual machine dashboard.
In the Basic tab, under Project Details, your *Subscription and the Resource Group are already pre-set.
If you want to create a new resource Group
Click Create new.
A pop-up prompts you to create the Resource Group Name container.
Insert a name and click OK.
If you want to keep the Resource Group that is already pre-set.
Under Instance Details, insert:
- Virtual machine name
- Region
- Image: The image you created is pre-selected by default.
Size: Choose a VM size that better suits your needs.
Keep the remaining fields as in the default choice.
Under Administrator account, enter the below details:
- Username: the name of the account administrator.
SSH public key source: from the drop-down menu, select Generate new key pair.
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 SSH key for more details.- Key pair name: insert a name for the key pair.
Under Inbound port rules, select:
- Public inbound ports: Allow selected ports.
- Select inbound ports: Use the default set SSH (22).
- Click Review + Create. You are redirected to the Review + create tab and receive a confirmation that the validation passed.
Review the details and click Create.
Optionally, you can click Previous to fix previous options selected.
A pop-up generates new key pair window opens. Click Download private key and create resources.
Save the key file as "yourKey.pem".
- After the deployment is complete, click Go to resource.
- You are redirected to a new window with your VM details. Select the public IP address on the top right side of the page and copy it to your clipboard.
Now, to create an SSH connection with the VM to connect to the Virtual Machine.
- Open a terminal.
At your prompt, open an SSH connection to your virtual machine. Replace the IP address with the one from your VM, and replace the path to the .pem with the path to where the key file was downloaded.
# ssh -i ./Downloads/yourKey.pem azureuser@10.111.12.123
- You are required to confirm if you want to continue to connect. Type yes to continue.
As a result, the output image you pushed to the Azure Storage Blob is ready to be provisioned.
8.9. Uploading QCOW2 image to OpenStack
Image Builder can generate images suitable for uploading to OpenStack cloud deployments, and starting instances there. This describes steps to upload an QCOW2 image to OpenStack.
Prerequisites
You must have an OpenStack-specific image created by Image Builder. Use the
openstack
output type in CLI or OpenStack Image (.qcow2) in GUI when creating the image.WarningImage Builder also offers a generic QCOW2 image type output format as
qcow2
or QEMU QCOW2 Image (.qcow2). Do not mistake it with the OpenStack image type which is also in the QCOW2 format, but contains further changes specific to OpenStack.
Procedure
Upload the image to OpenStack and start an instance from it. Use the
Images
interface to do this:Start an instance with that image:
-
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
.
8.10. Preparing for uploading images to Alibaba
This section describes steps to verify custom images that you can deploy on Alibaba Cloud. The images will need a specific configuration to boot successfully, because Alibaba Cloud requests the custom images to meet certain requirements before you use it. For this, it is recommended that you use the Alibaba image_check tool.
The custom image verification is an optional task. Image Builder generates images that conform to Alibaba’s requirements.
Prerequisites
- You must have an Alibaba image created by Image Builder.
Procedure
- Connect to the system containing the image you want to check it by the Alibaba image_check tool.
Download the image_check tool:
$ curl -O http://docs-aliyun.cn-hangzhou.oss.aliyun-inc.com/assets/attach/73848/cn_zh/1557459863884/image_check
Change the file permission of the image compliance tool:
# chmod +x image_check
Run the command to start the image compliance tool checkup:
# ./image_check
The tool verifies the system configuration and generates a report that is displayed on your screen. The image_check tool saves this report in the same folder where the image compliance tool is running.
- If any of the Detection Items fail, follow the instructions to correct it. For more information, see link: Detection items section.
Additional resources
8.11. Uploading images to Alibaba
This section describes how to upload an Alibaba image to Object Storage Service (OSS).
Prerequisites
- Your system is set up for uploading Alibaba images.
-
You must have an Alibaba image created by Image Builder. Use the
ami
output type on RHEL 7 or Alibaba on RHEL 8 when creating the image. - You have a bucket. See Creating a bucket.
- You have an active Alibaba Account.
- You activated OSS.
Procedure
- Log in to the OSS console.
- On the left side Bucket menu, select the bucket to which you want to upload an image.
- On the right upper menu, click the Files tab.
Click Upload. A window dialog opens on the right side. Choose the following information:
- Upload To: Choose to upload the file to the Current directory or to a Specified directory.
- File ACL: Choose the type of permission of the uploaded file.
- Click Upload.
- Choose the image you want to upload.
- Click Open.
As a result, the custom image is uploaded to OSS Console.
Additional resources
8.12. Importing images to Alibaba
This section describes how to import an Alibaba image to Elastic Cloud Console (ECS).
Prerequisites
- You have uploaded the image to Object Storage Service (OSS).
Procedure
Log in to the ECS console.
- On the left side menu, click Images.
- On the right upper side, click Import Image. A window dialog opens.
Confirm that you have set up the correct region where the image is located. Enter the following information:
- OSS Object Address: See how to obtain OSS Object Address.
- Image Name:
- Operating System:
- System Disk Size:
- System Architecture:
- Platform: Red Hat
Optionally, provide the following details:
- Image Format: qcow2 or ami, depending on the uploaded image format.
- Image Description:
Add Images of Data Disks:
The address can be determined in the OSS management console after selecting the required bucket in the left menu, select Files section and then click the Details link on the right for the appropriate image. A window will appear on the right side of the screen, showing image details. The OSS object address is in the URL box.
Click OK.
NoteThe importing process time can vary depending on the image size.
As a result, the custom image is imported to ECS Console. You can create an instance from the custom image.
Additional resources
8.13. Creating an instance of a custom image using Alibaba
You can create instances of the custom image using Alibaba ECS Console.
Prerequisites
- You have activated OSS and uploaded your custom image.
- You have successfully imported your image to ECS Console.
Procedure
- Log in to the ECS console.
- On the left side menu, choose Instances.
- In the top corner, click Create Instance. You are redirected to a new window.
- Fill in all the required information. See Creating an instance by using the wizard for more details.
Click Create Instance and confirm the order.
NoteYou can see the option Create Order instead of Create Instance, depending on your subscription.
As a result, you have an active instance ready for deployment.
Additional resources