Chapter 5. Composing a RHEL for Edge image using image builder command-line
You can use image builder to create a customized RHEL for Edge image (OSTree commit).
To access image builder and to create your custom RHEL for Edge image, you can either use the RHEL web console interface or the command-line interface.
For Network-based deployments, the workflow to compose RHEL for Edge images using the CLI, involves the following high-level steps:
- Create a blueprint for RHEL for Edge image
- Create a RHEL for Edge Commit image
- Download the RHEL for Edge Commit image
For Non-Network-based deployments, the workflow to compose RHEL for Edge images using the CLI, involves the following high-level steps:
- Create a blueprint for RHEL for Edge image
- Create a blueprint for the RHEL for Edge Installer image
- Create a RHEL for Edge Container image
- Create a RHEL for Edge Installer image
- Download the RHEL for Edge image
To perform the steps, use the composer-cli
package.
To run the composer-cli
commands as non-root, you must be part of the weldr
group or you must have administrator access to the system.
5.1. Network-based deployments workflow
This provides steps on how to build OSTree
commits. These OSTree
commits contain a full operating system, but are not directly bootable. To boot them, you need to deploy them using a Kickstart file.
5.1.1. Creating a RHEL for Edge Commit image blueprint using image builder command-line interface
Create a blueprint for RHEL for Edge Commit image using the CLI.
Prerequisite
You do not have an existing blueprint. To verify that, list the existing blueprints:
$ sudo composer-cli blueprints list
Procedure
Create a plain text file in the TOML format, with the following content:
name = "blueprint-name" description = "blueprint-text-description" version = "0.0.1" modules = [ ] groups = [ ]
Where,
- blueprint-name is the name and blueprint-text-description is the description for your blueprint.
- 0.0.1 is the version number according to the Semantic Versioning scheme.
Modules describe the package name and matching version glob to be installed into the image, for example, the package name = "tmux" and the matching version glob is version = "2.9a".
Notice that currently there are no differences between packages and modules.
Groups are packages groups to be installed into the image, for example the group package anaconda-tools.
At this time, if you do not know the modules and groups, leave them empty.
Include the required packages and customize the other details in the blueprint to suit your requirements.
For every package that you want to include in the blueprint, add the following lines to the file:
[[packages]] name = "package-name" version = "package-version"
Where,
- package-name is the name of the package, such as httpd, gdb-doc, or coreutils.
package-version is the version number of the package that you want to use.
The package-version supports the following dnf version specifications:
- For a specific version, use the exact version number such as 8.0.
- For the latest available version, use the asterisk *.
- For the latest minor version, use formats such as 8.*.
Push (import) the blueprint to the image builder server:
# composer-cli blueprints push blueprint-name.toml
List the existing blueprints to check whether the created blueprint is successfully pushed and exists.
# 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
Additional resources
5.1.2. Creating a RHEL for Edge Commit image using image builder command-line interface
To create a RHEL for Edge Commit image using image builder command-line interface, ensure that you have met the following prerequisites and follow the procedure.
Prerequisites
- You have created a blueprint for RHEL for Edge Commit image.
Procedure
Create the RHEL for Edge Commit image.
# composer-cli compose start blueprint-name image-type
Where,
- blueprint-name is the RHEL for Edge blueprint name.
image-type is
edge-commit
for network-based deployment.A confirmation that the composer process has been added to the queue appears. It also shows a Universally Unique Identifier (UUID) number for the image created. Use the UUID number to track your build. Also keep the UUID number handy for further tasks.
Check the image compose status.
# composer-cli compose status
The output displays the status in the following format:
<UUID> RUNNING date blueprint-name blueprint-version image-type
NoteThe image creation process takes up to 20 minutes to complete.
To interrupt the image creation process, run:
# composer-cli compose cancel <UUID>
To delete an existing image, run:
# composer-cli compose delete <UUID>
After the image is ready, you can download it and use the image on your network deployments.
Additional resources
5.1.3. Creating a RHEL for Edge image update with a parent commit using image builder command-line interface
If you performed a change in an existing blueprint, for example, you added a new package, and want to update an existing RHEL for Edge image with this new package, you can use a parent commit ID to generate an updated RHEL for Edge Commit (.tar) image.
To create a RHEL for Edge image with a parent commit using image builder command line interface, ensure that you have met the following prerequisites and follow the procedure.
Prerequisites
- You have updated an existing blueprint for RHEL for Edge image.
- You have an existing RHEL for Edge image (OSTree commit). See Extracting RHEL for Edge image commit.
Procedure
Create the RHEL for Edge image.
# composer-cli compose start-ostree --ref rhel/8/x86_64/edge --parent parent-OSTree-REF --url _URL blueprint-name image-type
Where,
- --ref is the same path value that you used to build an OSTree repository.
-
--parent is the parent OSTree Ref, for example
rhel/9/x86_64/edge
. - blueprint-name is the RHEL for Edge blueprint name.
-
-url
is the URL to the OSTree repository of the commit to embed in the image, for example, http://10.0.2.2:8080/repository/. image-type is
edge-commit
for network-based deployment.NoteThe
--parent
argument can only be used for the RHEL for Edge Commit (.tar) image type. Using the--url
and--parent
arguments together results in errors with other image types.A confirmation that the composer process has been added to the queue appears. It also shows a Universally Unique Identifier (UUID) number for the image created. Use the UUID number to track your build. Also keep the UUID number handy for further tasks.
Check the image compose status.
# composer-cli compose status
The output displays the status in the following format:
<UUID> RUNNING date blueprint-name blueprint-version image-type
NoteThe image creation process takes a few minutes to complete.
(Optional) To interrupt the image creation process, run:
# composer-cli compose cancel <UUID>
(Optional) To delete an existing image, run:
# composer-cli compose delete <UUID>
After the image creation is complete, to upgrade an existing OSTree deployment, you need:
- Set up a repository. See Deploying a RHEL for Edge image .
- Add this repository as a remote, that is, the http or https endpoint that hosts the OSTree content.
- Pull the new OSTree commit onto their existing running instance. See Deploying RHEL for Edge image updates manually .
5.1.4. Downloading a RHEL for Edge image using the image builder command-line interface
To download a RHEL for Edge image using image builder command line interface, ensure that you have met the following prerequisites and then follow the procedure.
Prerequisites
- You have created a RHEL for Edge image.
Procedure
Review the RHEL for Edge image status.
# composer-cli compose status
The output must display the following:
$ <UUID> FINISHED date blueprint-name blueprint-version image-type
Download the image.
# composer-cli compose image <UUID>
Image builder downloads the image as a
tar
file to the current directory.The UUID number and the image size is displayed alongside.
$ <UUID>-commit.tar: size MB
The image contains a commit and a json
file with information metadata about the repository content.
Additional resources
5.2. Non-network-based deployments workflow
To build a boot ISO image that installs an OSTree-based system using the "RHEL for Edge Container" and the "RHEL for Edge Installer" images and that can be later deployed to a device in disconnected environments, follow the steps.
5.2.1. Creating a RHEL for Edge Container blueprint using image builder CLI
To create a blueprint for RHEL for Edge Container image, perform the following steps:
Procedure
Create a plain text file in the TOML format, with the following content:
name = "blueprint-name" description = "blueprint-text-description" version = "0.0.1" modules = [ ] groups = [ ]
Where,
- blueprint-name is the name and blueprint-text-description is the description for your blueprint.
- 0.0.1 is the version number according to the Semantic Versioning scheme.
Modules describe the package name and matching version glob to be installed into the image, for example, the package name = "tmux" and the matching version glob is version = "2.9a".
Notice that currently there are no differences between packages and modules.
Groups are packages groups to be installed into the image, for example the group package anaconda-tools.
At this time, if you do not know the modules and groups, leave them empty.
Include the required packages and customize the other details in the blueprint to suit your requirements.
For every package that you want to include in the blueprint, add the following lines to the file:
[[packages]] name = "package-name" version = "package-version"
Where,
- package-name is the name of the package, such as httpd, gdb-doc, or coreutils.
package-version is the version number of the package that you want to use.
The package-version supports the following dnf version specifications:
- For a specific version, use the exact version number such as 8.0.
- For the latest available version, use the asterisk *.
- For the latest minor version, use formats such as 8.*.
Push (import) the blueprint to the image builder server:
# composer-cli blueprints push blueprint-name.toml
List the existing blueprints to check whether the created blueprint is successfully pushed and exists.
# 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
Additional resources
5.2.2. Creating a RHEL for Edge Installer blueprint using image builder CLI
You can create a blueprint to build a RHEL for Edge Installer (.iso)
image, and specify user accounts to automatically create one or more users on the system at installation time. See Creating an administrative user account for a RHEL for Edge image blueprint. It creates a user on the system at installation time.
When you create a user in the blueprint with the customizations.user
customization, the blueprint creates the user under the /usr/lib/passwd
directory and the password, under the /usr/etc/shadow
directory. Note that you cannot change the password in further versions of the image in a running system using OSTree
updates. The users you create with blueprints must be used only to gain access to the created system. After you access the system, you need to create users, for example, using the useradd
command.
To create a blueprint for RHEL for Edge Installer image, perform the following steps:
Procedure
Create a plain text file in the TOML format, with the following content:
name = "blueprint-installer" description = "blueprint-for-installer-image" version = "0.0.1" [[customizations.user]] name = "user" description = "account" password = "user-password" key = "user-ssh-key " home = "path" groups = ["user-groups"]
Where,
- blueprint-name is the name and blueprint-text-description is the description for your blueprint.
- 0.0.1 is the version number according to the Semantic Versioning scheme.
Push (import) the blueprint to the image builder server:
# composer-cli blueprints push blueprint-name.toml
List the existing blueprints to check whether the created blueprint is successfully pushed and exists.
# 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
Additional resources
5.2.3. Creating a RHEL for Edge Container image using image builder CLI
To create a RHEL for Edge Container image using image builder command-line interface, ensure that you have met the following prerequisites and follow the procedure.
Prerequisites
- You have created a blueprint for RHEL for Edge Container image.
Procedure
Create the RHEL for Edge Container image.
# composer-cli compose start-ostree --ref rhel/8/x86_64/edge --url URL-OSTree-repository blueprint-name image-type
Where,
-
--ref
is the same value that customer used to build ostree repository -
--url
is the URL to the OSTree repository of the commit to embed in the image. For example, http://10.0.2.2:8080/repository/. See Setting up a web server to install RHEL for Edge image. - blueprint-name is the RHEL for Edge blueprint name.
image-type is
edge-container
for non-network-based deployment.A confirmation that the composer process has been added to the queue appears. It also shows a Universally Unique Identifier (UUID) number for the image created. Use the UUID number to track your build. Also keep the UUID number handy for further tasks.
-
Check the image compose status.
# composer-cli compose status
The output displays the status in the following format:
<UUID> RUNNING date blueprint-name blueprint-version image-type
NoteThe image creation process takes up to 20 minutes to complete.
To interrupt the image creation process, run:
# composer-cli compose cancel <UUID>
To delete an existing image, run:
# composer-cli compose delete <UUID>
After the image is ready, it can be used for non-network deployments. See Creating a RHEL for Edge Container image for non-network-based deployments.
Additional resources
5.2.4. Creating a RHEL for Edge Installer image using command-line interface for non-network-based deployments
To create a RHEL for Edge Installer image that embeds the OSTree
commit, using image builder command-line interface, ensure that you have met the following prerequisites and then follow the procedure.
Prerequisites
- You have created a blueprint for RHEL for Edge Installer image.
- You have created a RHEL for Edge Edge Container image and deployed it using a web server.
Procedure
Begin to create the RHEL for Edge Installer image.
# composer-cli compose start-ostree --ref rhel/8/x86_64/edge --url URL-OSTree-repository blueprint-name image-type
Where,
- ref is the same value that customer used to build ostree repository
- URL-OSTree-repository is the URL to the OSTree repository of the commit to embed in the image. For example, http://10.0.2.2:8080/repository/. See Creating a RHEL for Edge Container image for non-network-based deployments.
- blueprint-name is the RHEL for Edge Installer blueprint name.
image-type is
edge-installer
.A confirmation that the composer process has been added to the queue appears. It also shows a Universally Unique Identifier (UUID) number for the image created. Use the UUID number to track your build. Also keep the UUID number handy for further tasks.
Check the image compose status.
# composer-cli compose status
The command output displays the status in the following format:
<UUID> RUNNING date blueprint-name blueprint-version image-type
NoteThe image creation process takes a few minutes to complete.
To interrupt the image creation process, run:
# composer-cli compose cancel <UUID>
To delete an existing image, run:
# composer-cli compose delete <UUID>
After the image is ready, you can use it for non-network deployments. See Installing the RHEL for Edge image for non-network-based deployments.
5.2.5. Downloading a RHEL for Edge Installer image using the image builder CLI
To download a RHEL for Edge Installer image using image builder command line interface, ensure that you have met the following prerequisites and then follow the procedure.
Prerequisites
- You have created a RHEL for Edge Installer image.
Procedure
Review the RHEL for Edge image status.
# composer-cli compose status
The output must display the following:
$ <UUID> FINISHED date blueprint-name blueprint-version image-type
Download the image.
# composer-cli compose image <UUID>
Image builder downloads the image as an
.iso
file to the current directory.The UUID number and the image size is displayed alongside.
$ <UUID>-boot.iso: size MB
The resulting image is a bootable ISO image.
Additional resources
5.3. Supported image customizations
You can customize your image by adding to your blueprint an additional RPM package, by enabling a service, or by customizing a kernel command line parameter. You can use several image customizations within blueprints. To make use of these options, you must configure the customizations in the blueprint and import (push) it to image builder.
These customizations are not supported when using image builder in the web console.
- Select a package group
[[packages]] name = "package_group_name"
Replace "package_group_name" with the name of the group. For example, "@server with gui".
- 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
The GID is optional and must already exist in the image. Optionally, a package creates it, or the blueprint creates the GID by using the
[[customizations.group]]
entry.ImportantTo generate the
password hash
, you must install python3 on your system.# yum install python3
Replace PASSWORD-HASH with the actual
password hash
. To generate thepassword 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.
You must enter the
name
. You can omit any of the lines that you do not need.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"
NoteThe "Set an existing users SSH key" customization 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.
- 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 use 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 the language and the keyboard options is mandatory. You can add many other 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"]
To enable lists, you can use numeric ports, or their names from the
/etc/services
file.- 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 service-names available in the/etc/services
file.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 to ensure that the image works correctly and this setup cannot be overridden. The
[customizations.services]
customization in the blueprint do not replace these services, but add them to the list of services already present in the image templates.NoteEach time a build starts, it clones the repository of the host system. If you refer to a repository with a large amount of history, it might take some time to clone and it uses a significant amount of disk space. Also, the clone is temporary and the build removes it after it creates the RPM package.
- Specify a custom filesystem configuration
You can specify a custom filesystem configuration in your blueprints and therefore create images with a specific disk layout, instead of 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
- improved performance
consistency with existing setups
To customize the filesystem configuration in your blueprint:
[[customizations.filesystem]] mountpoint = "MOUNTPOINT" size = MINIMUM-PARTITION-SIZE
The blueprint supports the following
mountpoints
and their sub-directories:-
/
- the root mount point -
/var
-
/home
-
/opt
-
/srv
-
/usr
-
/app
-
/data
/boot
- Supported from RHEL 8.7 and RHEL 9.1 onward.NoteCustomizing mount points is only supported from RHEL 8.5 and RHEL 9.0 distributions onward, by using the CLI. In earlier 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 in the customized image, you can create images with a customized file system partition on LVM and resize those partitions at runtime. To do this, you can specify a customized filesystem configuration in your blueprint and therefore create images with the desired disk layout. The default filesystem layout remains unchanged - if you use plain images without file system customization, and
cloud-init
resizes the root partition.NoteFrom 8.6 onward, for the
osbuild-composer-46.1-1.el8
RPM and later version, the physical partitions are no longer available and filesystem customizations create logical volumes.The blueprint automatically converts the file system customization to a LVM partition.
The
MINIMUM-PARTITION-SIZE
value has no default size format. The blueprint customization supports the following values and units: kB to TB and KiB to TiB. For example, you can define the mount point size in bytes:[[customizations.filesystem]] mountpoint = "/var" size = 1073741824
You can also define the mount point size by using units.
NoteYou can only define the mount point size by using units for the package version provided for RHEL 8.6 and RHEL 9.0 distributions onward.
For example:
[[customizations.filesystem]] mountpoint = "/opt" size = "20 GiB" or [[customizations.filesystem]] mountpoint = "/boot" size = "1 GiB"
-
Additional resources