Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 3. Overcloud Images

The Red Hat OpenStack Platform director provides images for the Overcloud. The QCOW image in this collection contains a base set of software components that integrate together 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 installing additional components to nodes.

This document describes a series of actions to use the virt-customize tool to modify an existing Overcloud image to augment an existing Controller node. For example, you can use these procedures to install additional ml2 plugins, Cinder backends, or monitoring agents not shipped with the initial image.

3.1. Obtaining the Overcloud Images
Copy link

The director requires several disk images for provisioning Overcloud nodes. This includes:

  • A discovery kernel and ramdisk - Used for bare metal system discovery over PXE boot.
  • A deployment kernel and ramdisk - Used for system provisioning and deployment.
  • An Overcloud kernel, ramdisk, and full image - A base Overcloud system that is written to the node’s hard disk.

Obtain these images from the Red Hat OpenStack Platform downloads page on the Red Hat Customer Portal at https://access.redhat.com/downloads/content/191/ver=7/rhel---7/7/x86_64/product-downloads. This location on the Customer Portal contains the images in TAR archives. Download these image archives to the images directory on the stack user’s home on the directory host (/home/stack/images/) and extract the images from the archives: 

$ cd ~/images
$ for tarfile in *.tar; do tar -xf $tarfile; done
Copy to Clipboard Toggle word wrap

3.2. Installing virt-customize to the director
Copy link

The libguestfs-tools package contains the virt-customize tool. Install the libguestfs-tools from the rhel-7-server-rpms repository: 

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

3.3. Inspecting the Overcloud Image
Copy link

You might aim to explore the contents of the overcloud-full.qcow2. Create a virtual machine instance using either the qemu-system-x86_64 command: 

$ sudo qemu-system-x86_64 --kernel overcloud-full.vmlinuz --initrd overcloud-full.initrd -m 1024 --append root=/dev/sda --enable-kvm overcloud-full.qcow2
Copy to Clipboard Toggle word wrap

Or using the following boot options in virt-manager:

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

3.4. Setting the Root Password
Copy link

Set the password for the root user on image: 

$ virt-customize -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
Copy to Clipboard Toggle word wrap

This provides administration-level access for your nodes through the console.

3.5. Registering the Image
Copy link

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

$ virt-customize -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
Copy to Clipboard Toggle word wrap

Make sure to replace the [username] and [password] with your Red Hat customer account details. This runs the following command on the image: 

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

This registers your Overcloud image to the Red Hat Content Delivery Network:

Find a list of pool ID from your account’s subscriptions: 

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

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

$ virt-customize -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
Copy to Clipboard Toggle word wrap

Make sure to replace the [subscription-pool] with your chosen subscription pool ID. This runs the following command on the image: 

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

This adds the pool to the image, which allows you to enable Red Hat repositories with the following command: 

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

3.7. Copying a Custom Repository File
Copy link

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

$ cat opendaylight.repo

[opendaylight]
name=OpenDaylight Repository
baseurl=https://nexus.opendaylight.org/content/repositories/opendaylight-yum-epel-6-x86_64/
gpgcheck=0
Copy to Clipboard Toggle word wrap

Copy the repository file on to the image: 

$ virt-customize -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
Copy to Clipboard Toggle word wrap

The --copy-in 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 aim to install is supported.

3.8. Installing RPMs
Copy link

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

$ virt-customize -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
Copy to Clipboard Toggle word wrap

The --install option allows you to specify a package to install.

3.9. Cleaning the Subscription Pool
Copy link

After installing the necessary packages to customize the image, we now remove our subscriptions and unregister the image: 

$ virt-customize -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
Copy to Clipboard Toggle word wrap

This removes all subscription pools from the image.

3.10. Unregistering the Image
Copy link

Finally, unregister the image. This is so the Overcloud deployment process can deploy the image to your nodes and register each of them individually. 

$ virt-customize -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
Copy to Clipboard Toggle word wrap

3.11. Uploading the Images to the Director
Copy link

After modifying the image, upload it to the director. Make sure to source the stackrc file so that you can access the director from the command line: 

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

This uploads the following images into the director: bm-deploy-kernel, bm-deploy-ramdisk, overcloud-full, overcloud-full-initrd, and overcloud-full-vmlinuz. These are the images for deployment and the Overcloud. The script also installs the discovery images on the director’s PXE server. View a list of the images in the CLI using the following command: 

$ 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 |
+--------------------------------------+------------------------+
Copy to Clipboard Toggle word wrap

This list will not show the discovery PXE images (discovery-ramdisk.*). The director copies these files to /httpboot. 

[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 discoverd.ipxe
-rwxr-xr-x. 1 root   root     5027584 Sep 10 16:32 discovery.kernel
-rw-r--r--. 1 root   root   150230861 Sep 10 16:32 discovery.ramdisk
drwxr-xr-x. 2 ironic ironic      4096 Sep 19 02:45 pxelinux.cfg
Copy to Clipboard Toggle word wrap
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