Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 3. Working with overcloud images

Red Hat OpenStack Platform (RHOSP) director provides images for the overcloud. The QCOW image in this collection contains a base set of software components that integrate to form various overcloud roles, such as Compute, Controller, and storage nodes. In some situations, you might aim to modify certain aspects of the overcloud image to suit your needs, such as installing additional components to nodes.

You can use the virt-customize tool to modify an existing overcloud image to augment an existing Controller node. For example, use the following procedures to install additional ml2 plugins, Cinder backends, or monitoring agents that do not ship with the initial image.

Important

If you modify the overcloud image to include third-party software and report an issue, Red Hat might request that you reproduce the issue with an unmodified image in accordance with our general third-party support policy: https://access.redhat.com/articles/1067.

3.1. Obtaining the overcloud images

Director requires several disk images to provision overcloud nodes:

  • An introspection kernel and ramdisk - For bare metal system introspection over PXE boot.
  • A deployment kernel and ramdisk - For system provisioning and deployment.
  • An overcloud kernel, ramdisk, and full image - A base overcloud system that director writes to the hard disk of the node.

Procedure

  1. To obtain these images, install the rhosp-director-images and rhosp-director-images-ipa packages:

    Copy to Clipboard Toggle word wrap 
    $ sudo yum install rhosp-director-images rhosp-director-images-ipa

  2. Extract the archives to the images directory on the stack user home, /home/stack/images:

    Copy to Clipboard Toggle word wrap 
    $ cd ~/images
$ for i in /usr/share/rhosp-director-images/overcloud-full-latest-13.0.tar /usr/share/rhosp-director-images/ironic-python-agent-latest-13.0.tar; do tar -xvf $i; done

3.2. Initrd: Modifying the initial ramdisks

Some situations might require that you modify the initial ramdisk. For example, you might require that a certain driver is available when you boot the nodes during the introspection or provisioning processes. In the context of the overcloud, this includes one of the following ramdisks:

  • The introspection ramdisk - ironic-python-agent.initramfs
  • The provisioning ramdisk - overcloud-full.initrd

This procedure adds an additional RPM package to the ironic-python-agent.initramfs ramdisk as an example.

Procedure

  1. Log in as the root user and create a temporary directory for the ramdisk:

    Copy to Clipboard Toggle word wrap 
    # mkdir ~/ipa-tmp
# cd ~/ipa-tmp

  2. Use the skipcpio and cpio commands to extract the ramdisk to the temporary directory:

    Copy to Clipboard Toggle word wrap 
    # /usr/lib/dracut/skipcpio ~/images/ironic-python-agent.initramfs | zcat | cpio -ivd | pax -r

  3. Install an RPM package to the extracted contents:

    Copy to Clipboard Toggle word wrap 
    # rpm2cpio ~/RPMs/python-proliantutils-2.1.7-1.el7ost.noarch.rpm | pax -r

  4. Recreate the new ramdisk:

    Copy to Clipboard Toggle word wrap 
    # find . 2>/dev/null | cpio --quiet -c -o | gzip -8  > /home/stack/images/ironic-python-agent.initramfs
# chown stack: /home/stack/images/ironic-python-agent.initramfs

  5. Verify that the new package now exists in the ramdisk:

    Copy to Clipboard Toggle word wrap 
    # lsinitrd /home/stack/images/ironic-python-agent.initramfs | grep proliant

3.3. QCOW: Installing virt-customize to director

The libguestfs-tools package contains the virt-customize tool.

Procedure

  • Install the libguestfs-tools from the rhel-8-for-x86_64-appstream-eus-rpms repository:

    Copy to Clipboard Toggle word wrap 
    $ sudo yum install libguestfs-tools
Important

If you install the libguestfs-tools package on the undercloud, disable iscsid.socket to avoid port conflicts with the tripleo_iscsid service on the undercloud:

Copy to Clipboard Toggle word wrap 
$ sudo systemctl disable --now iscsid.socket

3.4. QCOW: Inspecting the overcloud image

Before you can review the contents of the overcloud-full.qcow2 image, you must create a virtual machine that uses this image.

Procedure

  1. To create a virtual machine instance that uses the overcloud-full.qcow2 image, use the guestmount command:

    Copy to Clipboard Toggle word wrap 
    $ mkdir ~/overcloud-full
$ guestmount -a overcloud-full.qcow2 -i --ro ~/overcloud-full

    You can review the contents of the QCOW2 image in ~/overcloud-full.

  2. Alternatively, you can use virt-manager to create a virtual machine with the following boot options:

    • Kernel path: /overcloud-full.vmlinuz
    • initrd path: /overcloud-full.initrd
    • Kernel arguments: root=/dev/sda

3.5. QCOW: Setting the root password

Set the root password to provide administrator-level access for your nodes through the console.

Procedure

  • Set the password for the root user on image:

    Copy to Clipboard Toggle word wrap 
    $ virt-customize --selinux-relabel -a overcloud-full.qcow2 --root-password password:test
[  0.0] Examining the guest ...
[ 18.0] Setting a random seed
[ 18.0] Setting passwords
[ 19.0] Finishing off

3.6. QCOW: Registering the image

Register your overcloud image to the Red Hat Content Delivery Network.

Procedure

  1. Register your image temporarily to enable Red Hat repositories relevant to your customizations:

    Copy to Clipboard Toggle word wrap 
    $ virt-customize --selinux-relabel -a overcloud-full.qcow2 --run-command 'subscription-manager register --username=[username] --password=[password]'
[  0.0] Examining the guest ...
[ 10.0] Setting a random seed
[ 10.0] Running: subscription-manager register --username=[username] --password=[password]
[ 24.0] Finishing off

  2. Replace the [username] and [password] with your Red Hat customer account details. This runs the following command on the image:

    Copy to Clipboard Toggle word wrap 
    subscription-manager register --username=[username] --password=[password]

3.7. QCOW: Attaching a subscription and enabling Red Hat repositories

Procedure

  1. Find a list of pool ID from your account subscriptions:

    Copy to Clipboard Toggle word wrap 
    $ sudo subscription-manager list

  2. Choose a subscription pool ID and attach it to the image:

    Copy to Clipboard Toggle word wrap 
    $ virt-customize --selinux-relabel -a overcloud-full.qcow2 --run-command 'subscription-manager attach --pool [subscription-pool]'
[  0.0] Examining the guest ...
[ 12.0] Setting a random seed
[ 12.0] Running: subscription-manager attach --pool [subscription-pool]
[ 52.0] Finishing off

  3. Replace the [subscription-pool] with your chosen subscription pool ID:

    Copy to Clipboard Toggle word wrap 
    subscription-manager attach --pool [subscription-pool]

    This adds the pool to the image so that you can enable the repositories.

  4. Enable the Red Hat repositories:

    Copy to Clipboard Toggle word wrap 
    $ subscription-manager repos --enable=[repo-id]

3.8. QCOW: Copying a custom repository file

Adding third-party software to the image requires additional repositories. The following is an example repo file that contains configuration to use the OpenDaylight repository content.

Procedure

  1. List the contents of the opendaylight.repo file:

    Copy to Clipboard Toggle word wrap 
    $ cat opendaylight.repo

[opendaylight]
name=OpenDaylight Repository
baseurl=https://nexus.opendaylight.org/content/repositories/opendaylight-yum-epel-6-x86_64/
gpgcheck=0

  2. Copy the repository file on to the image:

    Copy to Clipboard Toggle word wrap 
    $ virt-customize --selinux-relabel -a overcloud-full.qcow2 --upload opendaylight.repo:/etc/yum.repos.d/
[  0.0] Examining the guest ...
[ 12.0] Setting a random seed
[ 12.0] Copying: opendaylight.repo to /etc/yum.repos.d/
[ 13.0] Finishing off

    The --upload option copies the repository file to /etc/yum.repos.d/ on the overcloud image.

Important: Red Hat does not offer support for software from non-certified vendors. Check with your Red Hat support representative that the software you want to install is supported.

3.9. QCOW: Installing RPMs

Procedure

  • Use the virt-customize command to install packages to the image:

    Copy to Clipboard Toggle word wrap 
    $ virt-customize --selinux-relabel -a overcloud-full.qcow2 --install opendaylight
[  0.0] Examining the guest ...
[ 11.0] Setting a random seed
[ 11.0] Installing packages: opendaylight
[ 91.0] Finishing off

    Use the --install option to specify a package to install.

3.10. QCOW: Cleaning the subscription pool

Procedure

  • After you install the necessary packages to customize the image, remove the subscription pools and unregister the image:

    Copy to Clipboard Toggle word wrap 
    $ virt-customize --selinux-relabel -a overcloud-full.qcow2 --run-command 'subscription-manager remove --all'
[  0.0] Examining the guest ...
[ 12.0] Setting a random seed
[ 12.0] Running: subscription-manager remove --all
[ 18.0] Finishing off

3.11. QCOW: Unregistering the image

Procedure

  • Unregister the image so that the overcloud deployment process can deploy the image to your nodes and register each of them individually:

    Copy to Clipboard Toggle word wrap 
    $ virt-customize --selinux-relabel -a overcloud-full.qcow2 --run-command 'subscription-manager unregister'
[  0.0] Examining the guest ...
[ 11.0] Setting a random seed
[ 11.0] Running: subscription-manager unregister
[ 17.0] Finishing off

3.12. QCOW: Reset the machine ID

Procedure

  • Reset the machine ID for the image so that machines that use this image do not use duplicate machine IDs:

    Copy to Clipboard Toggle word wrap 
    $ virt-sysprep --operation machine-id -a overcloud-full.qcow2

3.13. Uploading the images to director

After you modify the image, you need to upload it to director.

Procedure

  1. Source the stackrc file so that you can access director from the command line:

    Copy to Clipboard Toggle word wrap 
    $ source stackrc

  2. Upload the default director images to use for deploying the overcloud:

    Copy to Clipboard Toggle word wrap 
    $ openstack overcloud image upload --image-path /home/stack/images/

    This uploads the following images into the director:

    • bm-deploy-kernel
    • bm-deploy-ramdisk
    • overcloud-full
    • overcloud-full-initrd

    • overcloud-full-vmlinuz

      The script also installs the introspection images on the directors PXE server.

  3. View a list of the images in the CLI:

    Copy to Clipboard Toggle word wrap 
    $ openstack image list
+--------------------------------------+------------------------+
| ID                                   | Name                   |
+--------------------------------------+------------------------+
| 765a46af-4417-4592-91e5-a300ead3faf6 | bm-deploy-ramdisk      |
| 09b40e3d-0382-4925-a356-3a4b4f36b514 | bm-deploy-kernel       |
| ef793cd0-e65c-456a-a675-63cd57610bd5 | overcloud-full         |
| 9a51a6cb-4670-40de-b64b-b70f4dd44152 | overcloud-full-initrd  |
| 4f7e33f4-d617-47c1-b36f-cbe90f132e5d | overcloud-full-vmlinuz |
+--------------------------------------+------------------------+

    This list does not show the introspection PXE images (agent.*). Director copies these files to /httpboot.

    Copy to Clipboard Toggle word wrap 
    [stack@host1 ~]$ ls /httpboot -l
total 151636
-rw-r--r--. 1 ironic ironic       269 Sep 19 02:43 boot.ipxe
-rw-r--r--. 1 root   root         252 Sep 10 15:35 inspector.ipxe
-rwxr-xr-x. 1 root   root     5027584 Sep 10 16:32 agent.kernel
-rw-r--r--. 1 root   root   150230861 Sep 10 16:32 agent.ramdisk
drwxr-xr-x. 2 ironic ironic      4096 Sep 19 02:45 pxelinux.cfg
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat, Inc.