How to build fedora system images using Image Builder

Here in this article we will look Customised System Image Builder tool which can be used to build custom system images in different formats. We will be installing the OS Image Builder tool and use the CLI interface to build a custom image using a blueprint definition of the custom image.

Table of Contents

Test Environment

Fedora 35 workstation

What is Image Builder

Image Builder tool helps in creating deployment ready customised system images like installation disks, virtual machines, cloud specific images or others. It 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. This service is provided by the osbuild-composer package. We can interact with this service either using the composer-cli tool or GUI plugin for web console.

What is Blueprint

Blueprint is customised system image definition written in plain text as Tom’s Obvious, Minimal Language (TOML) format. It defines the listing of the packages and other customisation that would be part of the system image.

What is Compose

Compose is nothing but the individual builds of a system image based on particular version of a particular blueprint.

What is Customisation

Customisation are specifications for the system, which are not packages. This includes users, groups, and SSH keys.

If you are interested in watching the video. Here is the YouTube video on the same step by step procedure outlined below.

Procedure

Step1: Install Image Builder tool

As a first step let’s install the Image Build tool along with other packages as shown below.

[admin@fedser ~]$ sudo dnf install osbuild-composer composer-cli cockpit-composer bash-completion
...
Installed:
  clevis-18-4.fc35.x86_64                                clevis-luks-18-4.fc35.x86_64                       clevis-pin-tpm2-0.5.0-1.fc35.x86_64              
  cockpit-268.1-1.fc35.x86_64                            cockpit-bridge-268.1-1.fc35.x86_64                 cockpit-composer-31-1.fc35.noarch                
  cockpit-networkmanager-268.1-1.fc35.noarch             cockpit-packagekit-268.1-1.fc35.noarch             cockpit-storaged-268.1-1.fc35.noarch             
  cockpit-system-268.1-1.fc35.noarch                     cockpit-ws-268.1-1.fc35.x86_64                     device-mapper-multipath-0.8.6-5.fc35.x86_64      
  device-mapper-multipath-libs-0.8.6-5.fc35.x86_64       gnome-software-rpm-ostree-41.0-6.fc35.x86_64       jose-11-3.fc35.x86_64                            
  jq-1.6-10.fc35.x86_64                                  libjose-11-3.fc35.x86_64                           libluksmeta-9-12.fc35.x86_64                     
  luksmeta-9-12.fc35.x86_64                              oniguruma-6.9.8-1.fc35.x86_64                      openssl-1:1.1.1l-2.fc35.x86_64                   
  osbuild-54-2.fc35.noarch                               osbuild-composer-50-1.fc35.x86_64                  osbuild-composer-core-50-1.fc35.x86_64           
  osbuild-composer-dnf-json-50-1.fc35.x86_64             osbuild-composer-worker-50-1.fc35.x86_64           osbuild-luks2-54-2.fc35.noarch                   
  osbuild-lvm2-54-2.fc35.noarch                          osbuild-ostree-54-2.fc35.noarch                    osbuild-selinux-54-2.fc35.noarch                 
  python3-attrs-21.2.0-4.fc35.noarch                     python3-jsonschema-3.2.0-12.fc35.noarch            python3-osbuild-54-2.fc35.noarch                 
  python3-psutil-5.8.0-12.fc35.x86_64                    python3-pyrsistent-0.18.1-1.fc35.x86_64            python3-tracer-0.7.8-1.fc35.noarch               
  reportd-0.7.4-7.fc35.x86_64                            rpm-ostree-2022.8-1.fc35.x86_64                    rpm-ostree-libs-2022.8-1.fc35.x86_64             
  skopeo-1:1.7.0-1.fc35.x86_64                           sscg-3.0.2-6.fc35.x86_64                           tpm2-tools-5.2-1.fc35.x86_64                     
  tracer-common-0.7.8-1.fc35.noarch                      udisks2-lvm2-2.9.3-1.fc35.x86_64                   weldr-client-35.5-1.fc35.x86_64

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

Here is the default location of the repository files once the package is installed.

[admin@fedser ~]$ ls -ltr /usr/share/osbuild-composer/repositories
total 48
-rw-r--r--. 1 root root 15520 Apr 20 17:57 fedora-36.json
-rw-r--r--. 1 root root 15520 Apr 20 17:57 fedora-35.json
-rw-r--r--. 1 root root 15520 Apr 20 17:57 fedora-34.json

Step2: Enable service on startup

We will enable this Image builder service to started using the socket when its called as shown below.

[admin@fedser ~]$ sudo systemctl enable --now osbuild-composer.socket
Created symlink /etc/systemd/system/sockets.target.wants/osbuild-composer.socket → /usr/lib/systemd/system/osbuild-composer.socket.
[admin@fedser ~]$ sudo systemctl enable --now cockpit.socket
Created symlink /etc/systemd/system/sockets.target.wants/cockpit.socket → /usr/lib/systemd/system/cockpit.socket.

Step3: List Supported Image formats

Ones the packages are installed, let’s use the composer cli tool to list the types for system images formats that can be created as shown below.

[admin@fedser ~]$ sudo composer-cli compose types
ami
fedora-iot-commit
oci
openstack
qcow2
vhd
vmdk

Step4: Create Image Builder Blueprint using CLI

Let’s create a blupeprint definition file as shown below in which we are defining two packages to be installed by default which are nginx and sscg in our custom system image that we will be creating in further steps below.

[admin@fedser ~]$ mkdir imagebuilder; cd imagebuilder
[admin@fedser imagebuilder]$ cat fed36-customized.toml 
name = "fed36-customized"
description = "custom fedora 36 image"
version = "0.0.1"
modules = []
groups = []
[[packages]]
name = "nginx"
version = "*"
[[packages]]
name = "sscg"
version = "*"

Now, we will need to push this blueprint as shown below and validate its available in the list of blueprints.

[admin@fedser imagebuilder]$ sudo composer-cli blueprints push fed36-customized.toml 
[admin@fedser imagebuilder]$ sudo composer-cli blueprints list
fed36-customized

Make sure the components and versions listed in the blueprint and their dependencies are valid.

[admin@fedser imagebuilder]$ sudo composer-cli blueprints depsolve fed36-customized

Step5: Create System Image using the blueprint

Now, let’s create our customised system image of type vmdk as shown below. Once the command is triggered it will take few minutes for the image to be created.
You can track the status of the image creating using the below commands.

[admin@fedser imagebuilder]$ sudo composer-cli compose start fed36-customized vmdk
Compose 248b7555-c132-4341-9860-de0ede726249 added to the queue

Check the compose status.

[admin@fedser imagebuilder]$ sudo composer-cli compose status
248b7555-c132-4341-9860-de0ede726249 RUNNING  Thu May 12 18:07:20 2022 fed36-customized 0.0.1 vmdk

[admin@fedser imagebuilder]$ sudo composer-cli compose status
248b7555-c132-4341-9860-de0ede726249 FINISHED Thu May 12 18:15:54 2022 fed36-customized 0.0.1 vmdk             2147483648

Step6: Download the System Image

Once the customised system image creation is completed. You can download the image using the below command.

[admin@fedser imagebuilder]$ sudo composer-cli compose image 248b7555-c132-4341-9860-de0ede726249
[sudo] password for admin: 
248b7555-c132-4341-9860-de0ede726249-disk.vmdk

This downloaded image now can be used to create your customised Fedora OS based virtual machine in VMware.

You can refer to the following user guide documentation for more information on the Image Builder tool.

Hope you enjoyed reading this article. Thank you..

How to build fedora system images using Image Builder