Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 4. Performing operations with the Image service (glance)

You can create and manage images in the Red Hat OpenStack Services on OpenShift (RHOSO) Image service (glance).

Note

To execute openstack client commands on the cloud, you must specify the name of the cloud detailed in your clouds.yaml file. You can specify the name of the cloud by using one of the following methods:

  • Use the --os-cloud option with each command: 
$ openstack flavor list --os-cloud <cloud_name>
Copy to Clipboard Toggle word wrap

Use this option if you access more than one cloud.

  • Create an environment variable for the cloud name in your bashrc file: 
`export OS_CLOUD=<cloud_name>`
Copy to Clipboard Toggle word wrap

Prerequisites

  • The administrator has created a project for you, and they have provided you with a clouds.yaml file for you to access the cloud.
  • You have installed the python-openstackclient package.

4.1. Creating OS images
Copy link

To create OS images that you can manage in the Image service (glance), you can use Red Hat Enterprise Linux (RHEL) Kernel-based Virtual Machine (KVM) instance images, or you can manually create RHOSO-compatible images in the QCOW2 format by using RHEL ISO files or Windows ISO files.

4.1.1. Virtual machine image formats
Copy link

A virtual machine (VM) image is a file that contains a virtual disk with a bootable OS installed. Red Hat OpenStack Services on OpenShift (RHOSO) supports VM images in different formats.

The disk format of a VM image is the format of the underlying disk image. The container format indicates if the VM image is in a file format that also contains metadata about the VM.

When you add an image to the Image service (glance), you can set the disk or container format for your image to any of the values in the following tables by using the --disk-format and --container-format command options with the openstack image create, glance image-create-via-import, and openstack image set commands. If you are not sure of the container format of your VM image, you can set it to bare.

Expand
Table 4.1. Disk image formats
FormatDescription

aki

Indicates an Amazon kernel image that is stored in the Image service.

ami

Indicates an Amazon machine image that is stored in the Image service.

ari

Indicates an Amazon ramdisk image that is stored in the Image service.

iso

Sector-by-sector copy of the data on a disk, stored in a binary file. Although an ISO file is not normally considered a VM image format, these files contain bootable file systems with an installed operating system, and you use them in the same way as other VM image files.

ploop

A disk format supported and used by Virtuozzo to run OS containers.

qcow2

Supported by QEMU emulator. This format includes QCOW2v3 (sometimes referred to as QCOW3), which requires QEMU 1.1 or higher.

raw

Unstructured disk image format.

vdi

Supported by VirtualBox VM monitor and QEMU emulator.

vhd

Virtual Hard Disk. Used by VM monitors from VMware, VirtualBox, and others.

vhdx

Virtual Hard Disk v2. Disk image format with a larger storage capacity than VHD.

vmdk

Virtual Machine Disk. Disk image format that allows incremental backups of data changes from the time of the last backup.

Expand
Table 4.2. Container image formats
FormatDescription

aki

Indicates an Amazon kernel image that is stored in the Image service.

ami

Indicates an Amazon machine image that is stored in the Image service.

ari

Indicates an Amazon ramdisk image that is stored in the Image service.

bare

Indicates there is no container or metadata envelope for the image.

docker

Indicates a TAR archive of the file system of a Docker container that is stored in the Image service.

ova

Indicates an Open Virtual Appliance (OVA) TAR archive file that is stored in the Image service. This file is stored in the Open Virtualization Format (OVF) container file.

ovf

OVF container file format. Open standard for packaging and distributing virtual appliances or software to be run on virtual machines.

4.1.2. Creating RHEL KVM images
Copy link

Use Red Hat Enterprise Linux (RHEL) Kernel-based Virtual Machine (KVM) instance images to create images that you can manage in the Red Hat OpenStack Services on OpenShift (RHOSO) Image service (glance).

4.1.2.1. Using a RHEL KVM instance image
Copy link

You can use the following Red Hat Enterprise Linux (RHEL) Kernel-based Virtual Machine (KVM) instance image with Red Hat OpenStack Services on OpenShift (RHOSO):

QCOW2 images are configured with cloud-init and must have EC2-compatible metadata services for provisioning Secure Shell (SSH) keys to function correctly.

Ready Windows KVM instance images in QCOW2 format are not available.

Note

For KVM instance images:

  • The root account in the image is deactivated, but sudo access is granted to a special user named cloud-user.
  • There is no root password set for this image.

The root password is locked in /etc/shadow by placing !! in the second field.

For a RHOSO instance, generate an SSH keypair from the RHOSO dashboard or command line, and use that key combination to perform an SSH public authentication to the instance as root user.

When you launch the instance, this public key is injected to it. You can then authenticate by using the private key that you download when you create the keypair.

To create a custom root partition image for bare-metal instances, download the base Red Hat Enterprise Linux KVM instance image, and then upload the image to the Image service (glance).

Procedure

  1. Download the base Red Hat Enterprise Linux KVM instance image from the Customer Portal.

  2. Define DIB_LOCAL_IMAGE as the downloaded image: 

    $ export DIB_LOCAL_IMAGE=rhel-<ver>-x86_64-kvm.qcow2
    Copy to Clipboard Toggle word wrap
    • Replace <ver> with the RHEL version number of the image.

  3. Set your registration information depending on your method of registration:

    • Red Hat Customer Portal: 

      $ export REG_USER='<username>'
$ export REG_PASSWORD='<password>'
$ export REG_AUTO_ATTACH=true
$ export REG_METHOD=portal
$ export https_proxy='<IP_address:port>' (if applicable)
$ export http_proxy='<IP_address:port>' (if applicable)
      Copy to Clipboard Toggle word wrap

    • Red Hat Satellite: 

      $ export REG_USER='<username>'
$ export REG_PASSWORD='<password>'
$ export REG_SAT_URL='<satellite-url>'
$ export REG_ORG='<satellite-org>'
$ export REG_ENV='<satellite-env>'
$ export REG_METHOD=<method>
      Copy to Clipboard Toggle word wrap
    • Replace values in angle brackets <> with the correct values for your Red Hat Customer Portal or Red Hat Satellite registration.

  4. Optional: If you have any offline repositories, you can define DIB_YUM_REPO_CONF as a local repository configuration: 

    $ export DIB_YUM_REPO_CONF=<file-path>
    Copy to Clipboard Toggle word wrap
    • Replace <file-path> with the path to your local repository configuration file.

  5. Use the diskimage-builder tool to extract the kernel as rhel-image.vmlinuz and the initial RAM disk as rhel-image.initrd: 

    $ export DIB_RELEASE=<ver>
$ disk-image-create rhel baremetal \
  -o rhel-image
    Copy to Clipboard Toggle word wrap

  6. Upload the images to the Image service: 

    $ KERNEL_ID=$(openstack image create \
  --file rhel-image.vmlinuz --public \
  --container-format aki --disk-format aki \
  -f value -c id rhel-image.vmlinuz)
$ RAMDISK_ID=$(openstack image create \
  --file rhel-image.initrd --public \
  --container-format ari --disk-format ari \
  -f value -c id rhel-image.initrd)
$ openstack image create \
  --file rhel-image.qcow2   --public \
  --container-format bare \
  --disk-format qcow2 \
  --property kernel_id=$KERNEL_ID \
  --property ramdisk_id=$RAMDISK_ID \
  rhel-root-partition-bare-metal-image
    Copy to Clipboard Toggle word wrap

To create a whole-disk user image for bare-metal instances, download the base Red Hat Enterprise Linux KVM instance image, and then upload the image to the Image service (glance).

Procedure

  1. Download the base Red Hat Enterprise Linux KVM instance image from the Customer Portal.

  2. Define DIB_LOCAL_IMAGE as the downloaded image: 

    $ export DIB_LOCAL_IMAGE=rhel-<ver>-x86_64-kvm.qcow2
    Copy to Clipboard Toggle word wrap
    • Replace <ver> with the RHEL version number of the image.

  3. Set your registration information depending on your method of registration:

    • Red Hat Customer Portal: 

      $ export REG_USER='<username>'
$ export REG_PASSWORD='<password>'
$ export REG_AUTO_ATTACH=true
$ export REG_METHOD=portal
$ export https_proxy='<IP_address:port>' (if applicable)
$ export http_proxy='<IP_address:port>' (if applicable)
      Copy to Clipboard Toggle word wrap

    • Red Hat Satellite: 

      $ export REG_USER='<username>'
$ export REG_PASSWORD='<password>'
$ export REG_SAT_URL='<satellite-url>'
$ export REG_ORG='<satellite-org>'
$ export REG_ENV='<satellite-env>'
$ export REG_METHOD=<method>
      Copy to Clipboard Toggle word wrap
    • Replace values in angle brackets <> with the correct values for your Red Hat Customer Portal or Red Hat Satellite registration.

  4. Optional: If you have any offline repositories, you can define DIB_YUM_REPO_CONF as a local repository configuration: 

    $ export DIB_YUM_REPO_CONF=<file-path>
    Copy to Clipboard Toggle word wrap
    • Replace <file-path> with the path to your local repository configuration file.

  5. Upload the image to the Image service: 

    $ openstack image create \
  --file rhel-image.qcow2 --public \
  --container-format bare \
  --disk-format qcow2 \
  rhel-whole-disk-bare-metal-image
    Copy to Clipboard Toggle word wrap

You can create custom Red Hat Enterprise Linux (RHEL) or Windows images in QCOW2 format from ISO files, and upload these images to the Red Hat OpenStack Services on OpenShift (RHOSO) Image service (glance) for use when creating instances.

4.1.3.1. Prerequisites
Copy link

  • A Linux host machine to create an image. This can be any machine on which you can install and run the Linux packages, except for the undercloud or the overcloud.

  • The advanced-virt repository is enabled: 

    $ sudo subscription-manager repos --enable=advanced-virt-for-rhel-<ver>-x86_64-rpms
    Copy to Clipboard Toggle word wrap

  • The virt-manager application is installed to have all packages necessary to create a guest operating system: 

    $ sudo dnf module install -y virt
    Copy to Clipboard Toggle word wrap

  • The libguestfs-tools package is installed to have a set of tools to access and modify virtual machine images: 

    $ sudo dnf install -y libguestfs-tools-c
    Copy to Clipboard Toggle word wrap
  • A RHEL 9 ISO file or a Windows ISO file. For more information about RHEL ISO files, see RHEL 9.0 Binary DVD. If you do not have a Windows ISO file, see the Microsoft Evaluation Center to download an evaluation image.
  • A text editor, if you want to change the kickstart files (RHEL only).
Important

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

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

When you have the prerequisites in place, you can proceed to create a RHEL or Windows image:

You can create a Red Hat OpenStack Services on OpenShift (RHOSO) image in QCOW2 format by using a Red Hat Enterprise Linux (RHEL) 9 ISO file.

Procedure

  1. Log on to your host machine as the root user.

  2. Start the installation by using virt-install: 

    [root@host]# virt-install \
  --virt-type kvm \
  --name <rhel9-cloud-image> \
  --ram <2048> \
  --cdrom </var/lib/libvirt/images/rhel-9.0-x86_64-dvd.iso> \
  --disk <rhel9.qcow2>,format=qcow2,size=<10> \
  --network=bridge:virbr0 \
  --graphics vnc,listen=127.0.0.1 \
  --noautoconsole \
  --os-variant=<rhel9.0>
    Copy to Clipboard Toggle word wrap

    • Replace the values in angle brackets <> with the correct values for your RHEL 9 image.

      This command launches an instance and starts the installation process.

      Note

      If the instance does not launch automatically, run the virt-viewer command to view the console: 

      [root@host]# virt-viewer <rhel9-cloud-image>
      Copy to Clipboard Toggle word wrap

  3. Configure the instance:

    1. At the initial Installer boot menu, select Install Red Hat Enterprise Linux 9.
    2. Choose the appropriate Language and Keyboard options.
    3. When prompted about which type of devices your installation uses, select Auto-detected installation media.
    4. When prompted about which type of installation destination, select Local Standard Disks. For other storage options, select Automatically configure partitioning.
    5. In the Which type of installation would you like? window, choose the Basic Server install, which installs an SSH server.
    6. For network and host name, select eth0 for network and choose a host name for your device. The default host name is localhost.localdomain.
    7. Enter a password in the Root Password field and enter the same password again in the Confirm field.
  4. When the on-screen message confirms that the installation is complete, reboot the instance and log in as the root user.

  5. Update the /etc/sysconfig/network-scripts/ifcfg-eth0 file so that it contains only the following values: 

    TYPE=Ethernet
DEVICE=eth0
ONBOOT=yes
BOOTPROTO=dhcp
NM_CONTROLLED=no
    Copy to Clipboard Toggle word wrap
  6. Reboot the machine.

  7. Register the machine with the Content Delivery Network. 

    # sudo subscription-manager register
# sudo subscription-manager attach \
  --pool=<pool-id>
# sudo subscription-manager repos \
  --enable rhel-9-for-x86_64-baseos-rpms \
  --enable rhel-9-for-x86_64-appstream-rpms
    Copy to Clipboard Toggle word wrap
    • Replace pool-id with a valid pool ID. You can see a list of available pool IDs by running the subscription-manager list --available command.

  8. Update the system: 

    # dnf -y update
    Copy to Clipboard Toggle word wrap

  9. Install the cloud-init packages: 

    # dnf install -y cloud-utils-growpart cloud-init
    Copy to Clipboard Toggle word wrap

  10. Edit the /etc/cloud/cloud.cfg configuration file and add the following content under cloud_init_modules: 

    - resolv-conf
    Copy to Clipboard Toggle word wrap

    The resolv-conf option automatically configures the resolv.conf file when an instance boots for the first time. This file contains information related to the instance such as nameservers, domain, and other options.

  11. Add the following line to /etc/sysconfig/network to avoid issues when accessing the EC2 metadata service: 

    NOZEROCONF=yes
    Copy to Clipboard Toggle word wrap

  12. To ensure that the console messages appear in the Log tab on the dashboard and the nova console-log output, add the following boot option to the /etc/default/grub file: 

    GRUB_CMDLINE_LINUX_DEFAULT="console=tty0 console=ttyS0,115200n8"
    Copy to Clipboard Toggle word wrap

  13. Run the grub2-mkconfig command: 

    # grub2-mkconfig -o /boot/grub2/grub.cfg
    Copy to Clipboard Toggle word wrap

    The output is as follows: 

    Generating grub configuration file ...
Found linux image: /boot/vmlinuz-3.10.0-229.9.2.el9.x86_64
Found initrd image: /boot/initramfs-3.10.0-229.9.2.el9.x86_64.img
Found linux image: /boot/vmlinuz-3.10.0-121.el9.x86_64
Found initrd image: /boot/initramfs-3.10.0-121.el9.x86_64.img
Found linux image: /boot/vmlinuz-0-rescue-b82a3044fb384a3f9aeacf883474428b
Found initrd image: /boot/initramfs-0-rescue-b82a3044fb384a3f9aeacf883474428b.img
done
    Copy to Clipboard Toggle word wrap

  14. Deregister the instance so that the resulting image does not contain the subscription details for this instance: 

    # subscription-manager repos --disable=*
# subscription-manager unregister
# dnf clean all
    Copy to Clipboard Toggle word wrap

  15. Power off the instance: 

    # poweroff
    Copy to Clipboard Toggle word wrap

  16. Reset and clean the image by using the virt-sysprep command so that it can be used to create instances without issues: 

    [root@host]# virt-sysprep -d <rhel9-cloud-image>
    Copy to Clipboard Toggle word wrap

  17. Reduce the image size by converting any free space in the disk image back to free space in the host: 

    [root@host]# virt-sparsify \
  --compress <rhel9.qcow2> <rhel9-cloud.qcow2>
    Copy to Clipboard Toggle word wrap

    This command creates a new <rhel9-cloud.qcow2> file in the location from where the command is run.

    Note

    You must manually resize the partitions of instances based on the image in accordance with the disk space in the flavor that is applied to the instance.

The <rhel9-cloud.qcow2> image file is ready to be uploaded to the Image service. For more information about uploading this image to your RHOSO deployment, see Uploading images to the Image service.

4.1.3.3. Creating a Windows image
Copy link

You can create a Red Hat OpenStack Services on OpenShift (RHOSO) image in QCOW2 format by using a Windows ISO file.

Procedure

  1. Log on to your host machine as the root user.

  2. Start the installation by using virt-install: 

    [root@host]# virt-install \
    --name=<windows-image> \
    --disk size=<size> \
    --cdrom=<file-path-to-windows-iso-file> \
    --os-type=windows \
    --network=bridge:virbr0 \
    --graphics spice \
    --ram=<ram>
    Copy to Clipboard Toggle word wrap

    • Replace the values in angle brackets <> withe the correct values for your Windows image.

      Note

      The --os-type=windows parameter ensures that the clock is configured correctly for the Windows instance and enables its Hyper-V enlightenment features. You must also set os_type=windows in the image metadata before uploading the image to the Image service (glance).

  3. The virt-install command saves the instance image as /var/lib/libvirt/images/<windows-image>.qcow2 by default. If you want to keep the instance image elsewhere, change the parameter of the --disk option: 

    --disk path=<file-name>,size=<size>
    Copy to Clipboard Toggle word wrap

    • Replace <file-name> with the name of the file that stores the instance image, and optionally its path. For example, path=win8.qcow2,size=8 creates an 8 GB file named win8.qcow2 in the current working directory.

      Note

      If the instance does not launch automatically, run the virt-viewer command to view the console: 

      [root@host]# virt-viewer <windows-image>
      Copy to Clipboard Toggle word wrap

      For more information about how to install Windows, see the Microsoft documentation.

  4. To allow the newly-installed Windows system to use the virtualized hardware, you might need to install VirtIO drivers. For more information, see Installing KVM paravirtualized drivers for Windows virtual machines in Configuring and managing virtualization.

  5. To complete the configuration, download and run Cloudbase-Init on the Windows system. At the end of the installation of Cloudbase-Init, select the Run Sysprep and Shutdown checkboxes. The Sysprep tool makes the instance unique by generating an OS ID, which is used by certain Microsoft services.

    Important

    Red Hat does not provide technical support for Cloudbase-Init. If you encounter an issue, see Contact Cloudbase Solutions.

    When the Windows system shuts down, the <windows-image.qcow2> image file is ready to be uploaded to the Image service. For more information about uploading this image to your RHOSO deployment, see Uploading images to the Image service.

4.1.4. Creating an image for UEFI Secure Boot
Copy link

If your Red Hat OpenStack Services on OpenShift (RHOSO) deployment contains UEFI Secure Boot Compute nodes, you can create a Secure Boot image that cloud users can use to launch Secure Boot instances.

Procedure

  1. Create a new image for UEFI Secure Boot: 

    $ openstack image create \
--file <base_image_file> \
--container-format <container_format> \
--disk-format <disk_format> \
uefi_secure_boot_image
    Copy to Clipboard Toggle word wrap
    • Replace <base_image_file> with an image file that supports UEFI and the GUID Partition Table (GPT) standard, and includes an EFI system partition.
    • Replace <container_format> with one of the following container formats: none, ami, ari, aki, bare, ovf, ova, docker
    • Replace <disk_format> with one of the following disk formats: none, ami, ari, aki, vhd, vhdx, vmdk, raw, qcow2, vdi, iso, ploop.

  2. If the default machine type is not q35, then set the machine type to q35: 

    $ openstack image set --property hw_machine_type=q35 uefi_secure_boot_image
    Copy to Clipboard Toggle word wrap

  3. Specify that the instance must be scheduled on a UEFI Secure Boot host: 

    $ openstack image set \
 --property hw_firmware_type=uefi \
 --property os_secure_boot=required \
 uefi_secure_boot_image
    Copy to Clipboard Toggle word wrap

4.1.5. Metadata properties for virtual hardware
Copy link

The Compute service (nova) has deprecated support for using libosinfo data to set default device models. Instead, use the following image metadata properties to configure the optimal virtual hardware for an instance:

  • os_distro
  • os_version
  • hw_cdrom_bus
  • hw_disk_bus
  • hw_scsi_model
  • hw_vif_model
  • hw_video_model
  • hypervisor_type

4.2. Uploading, importing, and managing images
Copy link

Manage images and the properties and formats of images that you upload, import, or store in the Red Hat OpenStack Services on OpenShift (RHOSO) Image service (glance).

4.2.1. Uploading images to the Image service
Copy link

You can upload an image to the OpenStack Image service (glance) by using the openstack image create command with the --property option.

Procedure

  • Use the openstack image create command with the property option to upload an image.

    For example: 

    $ openstack image create --name <name> \
    --is-public true --disk-format <qcow2> \
    --container-format <bare> \
    --file </path/to/image> \
    --property <os_version>=<11.10>
    Copy to Clipboard Toggle word wrap
    • Replace <name> with a descriptive name for your image.
    • Replace <disk-format> with one of the following disk formats: none, ami, ari, aki, vhd, vhdx, vmdk, raw, qcow2, vdi, iso, ploop.
    • Replace <container-format> with one of the following container formats: none, ami, ari, aki, bare, ovf, ova, docker.
    • Replace </path/to/image> with the file path to your image file.
    • Replace <os_version> and <11.10> with the key-value pair of the property you want to associate to your image. You can use the --property option multiple times with different key-value pairs you want to associate to your image.

4.2.2. Image service image import methods
Copy link

You can import images to the Image service (glance) by using the following methods:

  • Use the web-download (default) method to import images from a URI.
  • Use the copy-image method to copy an existing image to other Image service back ends that are in your deployment. Use this import method only if multiple Image service back ends are enabled in your deployment.

The web-download method is enabled by default, but the administrator configures other import methods. You can run the openstack image import info command to list available import options.

4.2.2.1. Importing an image from a remote URI
Copy link

You can use the web-download image import method to copy an image from a remote URI to the OpenStack Image service (glance).

The Image service web-download method uses a two-stage process to perform the import:

  1. The web-download method creates an image record.
  2. The web-download method retrieves the image from the specified URI.

The URI is subject to optional allowlist and blocklist filtering.

If the Inject Image Metadata plugin is enabled in your Red Hat OpenStack Services on OpenShift (RHOSO) deployment, the plugin might inject metadata properties to the image. These metadata properties determine which Compute nodes the image instances are launched on.

Procedure

  • Create an image and specify the URI of the image to import: 

    $ glance image-create-via-import \
    --container-format <container_format> \
    --disk-format <disk_format> \
    --name <name> \
    --import-method web-download \
    --uri <uri>
    Copy to Clipboard Toggle word wrap
    • Replace <container_format> with one of the following container formats: none, ami, ari, aki, bare, ovf, ova, docker
    • Replace <disk_format> with one of the following disk formats: none, ami, ari, aki, vhd, vhdx, vmdk, raw, qcow2, vdi, iso, ploop.
    • Replace <name> with a descriptive name for your image.
    • Replace <uri> with the URI of your image.

Verification

  • Check the availability of the image: 

    $ openstack image show <image-id>
    Copy to Clipboard Toggle word wrap
    • Replace <image-id> with the image ID you provided during image creation.

4.2.2.2. Importing an image from a local volume
Copy link

The glance-direct image import method creates an image record, which generates an image ID. When you upload an image to the Image service (glance) from a local volume, the image is stored in a staging area and becomes active when it passes any configured checks.

Note

The glance-direct method requires a shared staging area when used in a highly available (HA) configuration. If you upload images by using the glance-direct import method, the upload can fail in a HA environment if a shared staging area is not present. In a HA active-active environment, API calls are distributed to the Image service controllers. The download API call can be sent to a different controller than the API call to upload the image.

The glance-direct image import method uses three different calls to import an image:

  • openstack image create
  • openstack image stage
  • openstack image import

You can use the glance image-create-via-import command to perform all three of the glance-direct calls in one command.

Procedure

  1. Use the glance image-create-via-import command to import a local image: 

    $ glance image-create-via-import \
    --container-format <container-format> \
    --disk-format <disk-format> \
    --name <name> \
    --file </path/to/image>
    Copy to Clipboard Toggle word wrap
    • Replace <container-format> with one of the following container formats: none, ami, ari, aki, bare, ovf, ova, docker
    • Replace <disk-format> with one of the following disk formats: none, ami, ari, aki, vhd, vhdx, vmdk, raw, qcow2, vdi, iso, ploop.
    • Replace <name> with a descriptive name for your image.

    • Replace </path/to/image> with the file path to your image file.

      When the image moves from the staging area to the back-end storage location, the image is listed. However, it might take some time for the image to become active.

Verification

  • Check the availability of the image: 

    $ openstack image show <image-id>
    Copy to Clipboard Toggle word wrap
    • Replace <image-id> with the image ID you provided during image creation.

4.2.3. Converting the format of an image
Copy link

When you import an image to the Image service (glance), you can convert the image to a different format if your administrator has configured the Image Conversion plugin with a preferred format for images in your Red Hat OpenStack Services on OpenShift (RHOSO) deployment.

For example,if you import a QCOW2 image to the Image service and the Image Conversion plugin is configured to the preferred format of RAW, your QCOW2 image is converted to the RAW format when you import it.

You can trigger image conversion only when you import an image. It does not run when you upload an image.

When you import an image to the Image service, the bits of the image are stored in a particular format in a temporary location. When you activate the Image Conversion plugin, the image is converted to the target format and moved to a final storage destination. When the task is finished, the Image service deletes the temporary location. The Image service does not retain the format that you initially uploaded.

Procedure

  • Convert the format of an image by using the web-download or glance-direct import method:

    • Convert the format by using the glance image-create-via-import command with web-download: 

      $ glance image-create-via-import \
    --disk-format <qcow2> \
    --container-format <bare> \
    --name <name> \
    --visibility public \
    --import-method web-download \
    --uri __<http://server/image.qcow2>__
      Copy to Clipboard Toggle word wrap
      • Replace <disk-format> with one of the following disk formats: none, ami, ari, aki, vhd, vhdx, vmdk, raw, qcow2, vdi, iso, ploop.
      • Replace <container-format> with one of the following container formats: none, ami, ari, aki, bare, ovf, ova, docker
      • Replace <name> with a descriptive name for your image.
      • Replace <http://server/image.qcow2> with the URI of your image.

    • Convert the format by using the glance-direct image import method: 

      $ glance image-create-via-import \
    --disk-format <qcow2> \
    --container-format <bare>
    --name <name>
    --visibility public
    --file <local_file.qcow2>
      Copy to Clipboard Toggle word wrap
      • Replace <local_file.qcow2> with your image file.

To launch instances from images that are stored in Red Hat Ceph Storage more efficiently, the image format must be RAW. If your administrator has enabled the Image Conversion plugin for your Red Hat OpenStack Services on OpenShift (RHOSO) deployment, your QCOW2 images are automatically converted to RAW format when you import them to the Image service. Alternatively, you can convert the image manually.

Procedure

  1. When you convert an image to RAW format, the RAW image is larger in size than the original QCOW2 image file. Run the following command before the conversion to determine the final RAW image size: 

    $ qemu-img info <image_id>.qcow2
    Copy to Clipboard Toggle word wrap
    • Replace <image_id> with the ID of your QCOW2 image.

  2. Convert the image from QCOW2 to RAW format: 

    $ qemu-img convert -p -f qcow2 -O raw <image_id>.qcow2 <image_id>.raw
    Copy to Clipboard Toggle word wrap

4.2.3.2. Storing an image in RAW format
Copy link

With the GlanceImageImportPlugins parameter enabled, run the following command to store a previously created image in RAW format: 

$ glance image-create-via-import \
    --disk-format qcow2 \
    --container-format bare \
    --name <name> \
    --visibility public \
    --import-method web-download \
    --uri <http://server/image.qcow2>
Copy to Clipboard Toggle word wrap
  • Replace <name> with the name of the image; this is the name that will appear in openstack image list.
  • Replace <http://server/image.qcow2> with the location and file name of the QCOW2 image.
Note

This command example creates the image record and imports it by using the web-download method.

4.2.4. Updating image properties
Copy link

You can update the properties of an image you have stored in the Image service (glance) by using the openstack image set command with the --property option.

Procedure

  • Use the openstack image set command with the --property option to update an image.

    For example: 

    $ openstack image set <image-id> \
    --property <architecture>=<x86_64>
    Copy to Clipboard Toggle word wrap
    • Replace <image-id> with the ID of the image you want to update.
    • Replace <architecture> and <x86_64> with the key-value pair of the property you want to update for your image. You can use the --property option multiple times with different key-value pairs you want to associate to your image.

4.2.5. Hiding or unhiding images
Copy link

You can hide public images from normal listings presented to cloud users. For example, you can hide obsolete CentOS 7 images and show only the latest version to simplify the user experience. By default, project administrators and project members can delete images. Cloud users can discover and use hidden images.

To create a hidden image, add the --hidden argument to the openstack image create command.

Procedure

  • Hide an image: 

    $ openstack image set <image_id> --hidden 'true'
    Copy to Clipboard Toggle word wrap

  • Unhide an image: 

    $ openstack image set <image_id> --hidden 'false'
    Copy to Clipboard Toggle word wrap

  • List hidden images: 

    $ openstack image list --hidden 'true'
    Copy to Clipboard Toggle word wrap

4.2.6. Deleting images from the Image service
Copy link

Use the openstack image delete command to delete one or more images that you do not need to store in the Image service (glance). By default, project administrators and project members can delete images.

Procedure

  • Delete one or more images: 

    $ openstack image delete <image-id> [<image-id> ...]
    Copy to Clipboard Toggle word wrap

    • Replace <image-id> with the ID of the image you want to delete.

      Warning

      The openstack image delete command permanently deletes the image and all copies of the image, as well as the image instance and metadata.

When you configure the Image service (glance) to use Red Hat Ceph Storage as a back end, you can import image data from a local file system or a web server to multiple Ceph Storage clusters.

You can import an image from a web server to multiple stores at once. If the image is not available on a web server, you can import the image from a local file system to the central store, and then copy it to other stores.

Important

Always store an image copy on the central site, even if there are no instances using the image at the central location.

4.3.1. Importing image data to a single store
Copy link

You can use the Image service (glance) to import image data to a single store.

Procedure

  1. Import image data to a single store: 

    $ glance image-create-via-import \
--container-format bare \
--name <image-name> \
--import-method web-download \
--uri <uri> \
--store <store>
    Copy to Clipboard Toggle word wrap
    • Replace <image-name> with the name of the image you want to import.
    • Replace <uri> with the URI of the image.

    • Replace <store> with the name of the store to which you want to copy the image data.

      Note

      If you do not include the options of --stores, --all-stores, or --store in the command, the Image service creates the image in the central store.

  2. Verify that the image data was added to specific stores: 

    $ openstack image show <image-id> | grep stores
    Copy to Clipboard Toggle word wrap

    • Replace <image-id> with the ID of the original image.

      The output displays a comma-delimited list of stores.

4.3.2. Importing image data to multiple stores
Copy link

Because the default setting of the --allow-failure parameter is true, you do not need to include the parameter in the command if it is acceptable for some stores to fail to import the image data.

Note

This procedure does not require all stores to successfully import the image data.

Procedure

  • Import image data to multiple, specified stores: 

    $ glance image-create-via-import \
--container-format bare \
--name <image-name> \
--import-method web-download \
--uri <uri> \
--stores <store-1>,<store-2>,<store-3>
    Copy to Clipboard Toggle word wrap
    • Replace <image-name> with the name of the image you want to import.
    • Replace <uri> with the URI of the image.
    • Replace <store-1>, <store-2>, and <store-3> with the names of the stores to which you want to import the image data.
    • Alternatively, replace --stores with --all-stores true to upload the image to all the stores.

This procedure requires all stores to successfully import the image data.

Procedure

  • Import image data to multiple, specified stores: 

    $ glance image-create-via-import \
--container-format bare \
--name <image-name> \
--import-method web-download \
--uri <uri> \
--stores <store-1>,<store-2>,<store-3>
    Copy to Clipboard Toggle word wrap
    • Replace <image-name> with the name of the image you want to import.
    • Replace <uri> with the URI of the image.
    • Replace <store-1>, <store-2>, and <store-3> with the names of stores to which you want to copy the image data.

    • Alternatively, replace --stores with --all-stores true to upload the image to all the stores.

      Note

      With the --allow-failure parameter set to false, the Image service (glance) does not ignore stores that fail to import the image data. You can view the list of failed stores with the image property os_glance_failed_import. For more information, see Section 4.3.4, “Checking the progress of the image import operation”.

Verification

  • Verify that the image data was added to specific stores: 

    $ openstack image show <image-id> | grep stores
    Copy to Clipboard Toggle word wrap

    Replace <image-id> with the ID of the original existing image.

    The output displays a comma-delimited list of stores.

The image import workflow sequentially imports image data into stores. The size of the image, the number of stores, and the network speed between the central site and the edge sites impact how long it takes for the image import operation to complete.

You can follow the progress of the image import by looking at two image properties, which appear in notifications sent during the image import operation:

  • The os_glance_importing_to_stores property lists the stores that have not imported the image data. At the beginning of the import, all requested stores show up in the list. Each time a store successfully imports the image data, the Image service removes the store from the list.
  • The os_glance_failed_import property lists the stores that fail to import the image data. This list is empty at the beginning of the image import operation.
Note

In the following procedure, the environment has three Red Hat Ceph Storage clusters: the central store and two stores at the edge, dcn0 and dcn1.

Procedure

  1. Verify that the image data was added to specific stores: 

    $ openstack image show <image-id>
    Copy to Clipboard Toggle word wrap

    • Replace <image-id> with the ID of the original image.

      The output displays a comma-delimited list of stores similar to the following example snippet: 

      | os_glance_failed_import       |
| os_glance_importing_to_stores | central,dcn0,dcn1
| status                        | importing
      Copy to Clipboard Toggle word wrap

  2. Monitor the status of the image import operation. When you precede a command with watch, the command output refreshes every two seconds. 

    $ watch openstack image show <image-id>
    Copy to Clipboard Toggle word wrap

    • Replace <image-id> with the ID of the original image.

      The status of the operation changes as the image import operation progresses: 

      | os_glance_failed_import       |
| os_glance_importing_to_stores | dcn0,dcn1
| status                        | importing
      Copy to Clipboard Toggle word wrap

      Output that shows that an image failed to import resembles the following example: 

      | os_glance_failed_import       | dcn0
| os_glance_importing_to_stores | dcn1
| status                        | importing
      Copy to Clipboard Toggle word wrap

      After the operation completes, the status changes to active: 

      | os_glance_failed_import       | dcn0
| os_glance_importing_to_stores |
| status                        | active
      Copy to Clipboard Toggle word wrap

4.3.5. Managing image import failures
Copy link

You can manage failures of the image import operation by using the --allow-failure parameter:

  • If the value of the --allow-failure parameter to true, the image status becomes active after the first store successfully imports the data. This is the default setting. You can view a list of stores that failed to import the image data by using the os_glance_failed_import image property.
  • If you set the value of the --allow-failure parameter to false, the image status only becomes active after all specified stores successfully import the data. Failure of any store to import the image data results in an image status of failed. The image is not imported into any of the specified stores.

4.3.6. Copying an image to specific stores
Copy link

Use the following procedure to copy image data to one or more specific stores.

Procedure

  1. Copy image data to one or more specific stores.

    • Copy image data to a single store: 

      $ openstack image import <image_id> \
--store <store_id>\
--import-method copy-image
      Copy to Clipboard Toggle word wrap
      • Replace <image_id> with the name of the image you want to copy.
      • Replace <store_id> with the name of the stores to which you want to copy the image data.

    • Copy image data to specific stores: 

      $ openstack image import <image-id> \
--stores <store-1>,<store-2> \
--import-method copy-image
      Copy to Clipboard Toggle word wrap
      • Replace <store-1> and <store-2> with the names of the stores to which you want to copy the image data.

  2. Confirm that the image data successfully replicated to the specified stores: 

    $ openstack image list --include-stores
    Copy to Clipboard Toggle word wrap

    For information about how to check the status of the image import operation, see Section 4.3.4, “Checking the progress of the image import operation”.

4.3.7. Copying an image to multiple stores
Copy link

You can use the Image service (glance) to copy image data to multiple Red Hat Ceph Storage stores at the edge by using the image import workflow.

Note

The image must be present at the central site before you copy it to any edge sites. Only the image owner or project administrator can copy existing images to newly added stores.

You can copy existing image data either by setting --all-stores to true or by specifying specific stores to receive the image data.

  • The default setting for the --all-stores option is false. If --all-stores is false, you must specify which stores receive the image data by using --stores <store-1>,<store-2>. If the image data is already present in any of the specified stores, the request fails.
  • If you set all-stores to true, and the image data already exists in some of the stores, then those stores are excluded from the list.

After you specify which stores receive the image data, the Image service copies data from the central site to a staging area. Then, the Image service imports the image data by using the image import workflow.

Important

Avoid closely timed copy-image operations for the same image because they can cause race conditions and unexpected results. Existing image data remains as it is, but copying data to new stores fails.

4.3.8. Copying an image to all stores
Copy link

Use the following procedure to copy image data to all available stores.

Procedure

  1. Copy image data to all available stores: 

    $ openstack image import <image-id> \
--all-stores true \
--import-method copy-image
    Copy to Clipboard Toggle word wrap
    • Replace <image-id> with the ID of the image you want to copy.

  2. Confirm that the image data successfully replicated to all available stores: 

    $ openstack image list --include-stores
    Copy to Clipboard Toggle word wrap

    For information about how to check the status of the image import operation, see Section 4.3.4, “Checking the progress of the image import operation”.

4.3.9. Deleting an image from a specific store
Copy link

Delete an existing image copy on a specific store by using the Red Hat OpenStack Services on OpenShift (RHOSO) Image service (glance).

Procedure

  • Delete an image from a specific store: 

    $ openstack image delete --store <store-id> <image-id>
    Copy to Clipboard Toggle word wrap
  • Replace <store-id> with the name of the store on which the image copy should be deleted.
  • Replace <image-id> with the ID of the image you want to delete.
Warning

The openstack image delete --store <store-id> command permanently deletes the image across all the sites. All image copies are deleted, as well as the image instance and metadata.

Although an image can be present on multiple sites, there is only a single Universal Unique Identifier (UUID) for a given image. The image metadata contains the locations of each copy. For example, an image present on two edge sites is exposed as a single UUID with three locations: the central site and the two edge sites.

Procedure

  1. Show the sites on which a copy of the image exists: 

    $ openstack image show ID | grep "stores"

| stores |  default_backend,dcn1,dcn2
    Copy to Clipboard Toggle word wrap

    In the example, the image is present on the central site, the default_backend, and on the two edge sites dcn1 and dcn2.

  2. Alternatively, you can run the openstack image list command with the --include-stores option to see the sites where the images exist: 

    $ openstack image list --include-stores

| ID                                   | Name    | Stores

| 2bd882e7-1da0-4078-97fe-f1bb81f61b00 | cirros | default_backend,dcn1,dcn2
    Copy to Clipboard Toggle word wrap

  3. List the image location properties to show the details of each location: 

    $ openstack image show ID -c properties

| properties |

(--- cut ---)
locations='[{'url': 'rbd://79b70c32-df46-4741-93c0-8118ae2ae284/images/2bd882e7-1da0-4078-97fe-f1bb81f61b00/snap', 'metadata': {'store': 'default_backend'}}, {'url': 'rbd://63df2767-8ddb-4e06-8186-8c155334f487/images/2bd882e7-1da0-4078-97fe-f1bb81f61b00/snap', 'metadata': {'store': 'dcn1'}}, {'url': 'rbd://1b324138-2ef9-4ef9-bd9e-aa7e6d6ead78/images/2bd882e7-1da0-4078-97fe-f1bb81f61b00/snap', 'metadata': {'store': 'dcn2'}}]',
(--- cut --)
    Copy to Clipboard Toggle word wrap

    The image properties show the different Ceph RBD URIs for the location of each image.

    In the example, the central image location URI is: 

    rbd://79b70c32-df46-4741-93c0-8118ae2ae284/images/2bd882e7-1da0-4078-97fe-f1bb81f61b00/snap', 'metadata': {'store': 'default_backend'}}
    Copy to Clipboard Toggle word wrap

    The URI is composed of the following data:

    • 79b70c32-df46-4741-93c0-8118ae2ae284 corresponds to the central Ceph FSID. Each Ceph cluster has a unique FSID.
    • The default value for all sites is images, which corresponds to the Ceph pool on which the images are stored.
    • 2bd882e7-1da0-4078-97fe-f1bb81f61b00 corresponds to the image UUID. The UUID is the same for a given image regardless of its location.
    • The metadata shows the glance store to which this location maps. In this example, it maps to the default_backend, which is the central hub site.

4.4. Image service command options and properties
Copy link

You can use optional arguments, properties, and property keys with the openstack image create, glance image-create-via-import, and openstack image set commands.

4.4.1. Image service command options
Copy link

You can use the following optional arguments with the openstack image create, glance image-create-via-import, and openstack image set commands.

Expand
Table 4.3. Command options
Specific toOptionDescription

All

--architecture <ARCHITECTURE>

Operating system architecture as specified in https://docs.openstack.org/glance/latest/user/common-image-properties.html#architecture

All

--protected [True_False]

If true, image will not be deletable.

All

--name <NAME>

Descriptive name for the image

All

--instance-uuid <INSTANCE_UUID>

Metadata that can be used to record which instance this image is associated with. (Informational only, does not create an instance snapshot.)

All

--min-disk <MIN_DISK>

Amount of disk space (in GB) required to boot image.

All

--visibility <VISIBILITY>

Scope of image accessibility. Valid values: public, private, community, shared

All

--kernel-id <KERNEL_ID>

ID of image stored in the Image service (glance) that should be used as the kernel when booting an AMI-style image.

All

--os-version <OS_VERSION>

Operating system version as specified by the distributor

All

--disk-format <DISK_FORMAT>

Format of the disk. Valid values: none, ami, ari, aki, vhd, vhdx, vmdk, raw, qcow2, vdi, iso, ploop

All

--os-distro <OS_DISTRO>

Common name of operating system distribution as specified in https://docs.openstack.org/glance/latest/user/common-image-properties.html#os-distro

All

--owner <OWNER>

Owner of the image

All

--ramdisk-id <RAMDISK_ID>

ID of image stored in the Image service that should be used as the ramdisk when booting an AMI-style image.

All

--min-ram <MIN_RAM>

Amount of RAM (in MB) required to boot image.

All

--container-format <CONTAINER_FORMAT>

Format of the container. Valid values: none, ami, ari, aki, bare, ovf, ova, docker

All

--property <key=value>

Arbitrary property to associate with image. May be used multiple times.

openstack image create

--tags <TAGS> [<TAGS> ...]

List of strings related to the image

openstack image create

--id <ID>

An identifier for the image

openstack image set

--remove-property

Key name of arbitrary property to remove from the image.

4.4.2. Image properties and property keys
Copy link

You can use the following keys with the property option for with the openstack image create, glance image-create-via-import, and openstack image set commands.

Expand
Table 4.4. Property keys
Specific toKeyDescriptionSupported values

All

architecture

The CPU architecture that must be supported by the hypervisor. For example, x86_64, arm, or ppc64. Run uname -m to get the architecture of a machine.

  • aarch - ARM 64-bit
  • alpha - DEC 64-bit RISC
  • armv7l - ARM Cortex-A7 MPCore
  • cris- Ethernet, Token Ring, AXis-Code Reduced Instruction Set
  • i686 - Intel sixth-generation x86 (P6 micro architecture)
  • ia64 - Itanium
  • lm32 - Lattice Micro32
  • m68k - Motorola 68000
  • microblaze - Xilinx 32-bit FPGA (Big Endian)
  • microblazeel - Xilinx 32-bit FPGA (Little Endian)
  • mips - MIPS 32-bit RISC (Big Endian)
  • mipsel - MIPS 32-bit RISC (Little Endian)
  • mips64 - MIPS 64-bit RISC (Big Endian)
  • mips64el - MIPS 64-bit RISC (Little Endian)
  • openrisc - OpenCores RISC
  • parisc - HP Precision Architecture RISC
  • parisc64 - HP Precision Architecture 64-bit RISC
  • ppc - PowerPC 32-bit
  • ppc64 - PowerPC 64-bit
  • ppcemb - PowerPC (Embedded 32-bit)
  • s390 - IBM Enterprise Systems Architecture/390
  • s390x - S/390 64-bit
  • sh4 - SuperH SH-4 (Little Endian)
  • sh4eb - SuperH SH-4 (Big Endian)
  • sparc - Scalable Processor Architecture, 32-bit
  • sparc64 - Scalable Processor Architecture, 64-bit
  • unicore32 - Microprocessor Research and Development Center RISC Unicore32
  • x86_64 - 64-bit extension of IA-32
  • xtensa - Tensilica Xtensa configurable microprocessor core
  • xtensaeb - Tensilica Xtensa configurable microprocessor core (Big Endian)

All

hypervisor_type

The hypervisor type.

kvm, vmware

All

instance_uuid

For snapshot images, this is the UUID of the server used to create this image.

Valid server UUID

All

kernel_id

The ID of an image stored in the Image Service that should be used as the kernel when booting an AMI-style image.

Valid image ID

All

os_distro

The common name of the operating system distribution in lowercase.

  • arch - Arch Linux. Do not use archlinux or org.archlinux.
  • centos - Community Enterprise Operating System. Do not use org.centos or CentOS.
  • debian - Debian. Do not use Debian or org.debian.
  • fedora - Fedora. Do not use Fedora, org.fedora, or org.fedoraproject.
  • freebsd - FreeBSD. Do not use org.freebsd, freeBSD, or FreeBSD.
  • gentoo - Gentoo Linux. Do not use Gentoo or org.gentoo.
  • mandrake - Mandrakelinux (MandrakeSoft) distribution. Do not use mandrakelinux or MandrakeLinux.
  • mandriva - Mandriva Linux. Do not use mandrivalinux.
  • mes - Mandriva Enterprise Server. Do not use mandrivaent or mandrivaES.
  • msdos - Microsoft Disc Operating System. Do not use ms-dos.
  • netbsd - NetBSD. Do not use NetBSD or org.netbsd.
  • netware - Novell NetWare. Do not use novell or NetWare.
  • openbsd - OpenBSD. Do not use OpenBSD or org.openbsd.
  • opensolaris - OpenSolaris. Do not use OpenSolaris or org.opensolaris.
  • opensuse - openSUSE. Do not use suse, SuSE, or org.opensuse.
  • rhel - Red Hat Enterprise Linux. Do not use redhat, RedHat, or com.redhat.
  • sled - SUSE Linux Enterprise Desktop. Do not use com.suse.
  • ubuntu - Ubuntu. Do not use Ubuntu, com.ubuntu, org.ubuntu, or canonical.
  • windows - Microsoft Windows. Do not use com.microsoft.server.

All

os_version

The operating system version as specified by the distributor.

Version number (for example, "11.10")

All

ramdisk_id

The ID of image stored in the Image Service that should be used as the ramdisk when booting an AMI-style image.

Valid image ID

All

vm_mode

The virtual machine mode. This represents the host/guest ABI (application binary interface) used for the virtual machine.

hvm-Fully virtualized. This is the mode used by QEMU and KVM.

libvirt API driver

hw_cdrom_bus

Specifies the type of disk controller to attach CD-ROM devices to.

scsi, virtio, ide, or usb. If you specify iscsi, you must set the hw_scsi_model parameter to virtio-scsi.

libvirt API driver

hw_disk_bus

Specifies the type of disk controller to attach disk devices to.

scsi, virtio, ide, or usb. Note that if using iscsi, the hw_scsi_model needs to be set to virtio-scsi.

libvirt API driver

hw_firmware_type

Specifies the type of firmware to use to boot the instance.

Set to one of the following valid values:

  • bios
  • uefi

libvirt API driver

hw_machine_type

Enables booting an ARM system using the specified machine type. If an ARM image is used and its machine type is not explicitly specified, then Compute uses the virt machine type as the default for ARMv7 and AArch64.

Valid types can be viewed by using the virsh capabilities command. The machine types are displayed in the machine tag.

libvirt API driver

hw_numa_nodes

Number of NUMA nodes to expose to the instance (does not override flavor definition).

Integer.

libvirt API driver

hw_numa_cpus.0

Mapping of vCPUs N-M to NUMA node 0 (does not override flavor definition).

Comma-separated list of integers.

libvirt API driver

hw_numa_cpus.1

Mapping of vCPUs N-M to NUMA node 1 (does not override flavor definition).

Comma-separated list of integers.

libvirt API driver

hw_numa_mem.0

Mapping N MB of RAM to NUMA node 0 (does not override flavor definition).

Integer

libvirt API driver

hw_numa_mem.1

Mapping N MB of RAM to NUMA node 1 (does not override flavor definition).

Integer

libvirt API driver

hw_pci_numa_affinity_policy

Specifies the NUMA affinity policy for PCI passthrough devices and SR-IOV interfaces.

Set to one of the following valid values:

  • required: The Compute service creates an instance that requests a PCI device only when at least one of the NUMA nodes of the instance has affinity with the PCI device. This option provides the best performance.
  • preferred: The Compute service attempts a best effort selection of PCI devices based on NUMA affinity. If affinity is not possible, then the Compute service schedules the instance on a NUMA node that has no affinity with the PCI device.

  • legacy: (Default) The Compute service creates instances that request a PCI device in one of the following cases:

    • The PCI device has affinity with at least one of the NUMA nodes.
    • The PCI devices do not provide information about their NUMA affinities.

libvirt API driver

hw_qemu_guest_agent

Guest agent support. If set to yes, and if qemu-ga is also installed, file systems can be quiesced (frozen) and snapshots created automatically.

yes / no

libvirt API driver

hw_rng_model

Adds a random number generator (RNG) device to instances launched with this image.

The instance flavor enables the RNG device by default. To disable the RNG device, the administrator must set hw_rng:allowed to False on the flavor.

The default entropy source is /dev/random. To specify a hardware RNG device, set rng_dev_path to /dev/hwrng in your Compute environment file.

virtio, or other supported device.

libvirt API driver

hw_scsi_model

Enables the use of VirtIO SCSI (virtio-scsi) to provide block device access for compute instances; by default, instances use VirtIO Block (virtio-blk). VirtIO SCSI is a para-virtualized SCSI controller device that provides improved scalability and performance, and supports advanced SCSI hardware.

virtio-scsi

libvirt API driver

hw_tpm_model

Set to the model of TPM device to use. Ignored if hw:tpm_version is not configured.

  • tpm-tis: (Default) TPM Interface Specification.
  • tpm-crb: Command-Response Buffer. Compatible only with TPM version 2.0.

libvirt API driver

hw_tpm_version

Set to the version of TPM to use. TPM version 2.0 is the only supported version.

2.0

libvirt API driver

hw_video_model

The video device driver for the display device to use in virtual machine instances.

Set to one of the following values to specify the supported driver to use:

  • virtio - (Default) Recommended Driver for the virtual machine display device, supported by most architectures. The VirtIO GPU driver is included in RHEL-7 and later, and Linux kernel versions 4.4 and later. If an instance kernel has the VirtIO GPU driver, then the instance can use all the VirtIO GPU features. If an instance kernel does not have the VirtIO GPU driver, the VirtIO GPU device gracefully falls back to VGA compatibility mode, which provides a working display for the instance.
  • qxl - Deprecated Driver for Spice or noVNC environments that is no longer maintained.
  • cirrus - Legacy driver, supported only for backward compatibility. Do not use for new instances.
  • vga - Use this driver for IBM Power environments.
  • bochs - Use this driver for instances that boot with UEFI. In some cases, you can use this driver for instances that boot with BIOS, such as when the instance does not depend on direct VGA hardware access.
  • gop - Not supported for QEMU/KVM environments.
  • xen - Not supported for KVM environments.
  • vmvga - Legacy driver, do not use.
  • none - Use this value to disable emulated graphics or video in virtual GPU (vGPU) instances where the driver is configured separately.

libvirt API driver

hw_video_ram

Maximum RAM for the video image. Used only if a hw_video:ram_max_mb value has been set in the flavor’s extra_specs and that value is higher than the value set in hw_video_ram.

Integer in MB (for example, 64)

libvirt API driver

hw_viommu_model

Adds a virtual IOMMU device to guests on x86 hosts that use the Q35 machine type.

intel, smmuv3, virtio, auto. The default value is auto, which automatically selects virtio.

libvirt API driver

hw_watchdog_action

Enables a virtual hardware watchdog device that carries out the specified action if the server hangs. The watchdog uses the i6300esb device (emulating a PCI Intel 6300ESB). If hw_watchdog_action is not specified, the watchdog is disabled.

  • disabled-The device is not attached. Allows the user to disable the watchdog for the image, even if it has been enabled using the image’s flavor. The default value for this parameter is disabled.
  • reset-Forcefully reset the guest.
  • poweroff-Forcefully power off the guest.
  • pause-Pause the guest.
  • none-Only enable the watchdog; do nothing if the server hangs.

libvirt API driver

os_command_line

The kernel command line to be used by the libvirt driver, instead of the default. For Linux Containers(LXC), the value is used as arguments for initialization. This key is valid only for Amazon kernel, ramdisk, or machine images (aki, ari, or ami).

 

libvirt API driver

os_secure_boot

Use to create an instance that is protected with UEFI Secure Boot.

Set to one of the following valid values:

  • required: Enables Secure Boot for instances launched with this image. The instance is only launched if the Compute service locates a host that can support Secure Boot. If no host is found, the Compute service returns a "No valid host" error.
  • disabled: Disables Secure Boot for instances launched with this image. Disabled by default.
  • optional: Enables Secure Boot for instances launched with this image only when the Compute service determines that the host can support Secure Boot.

libvirt API driver and VMware API driver

hw_vif_model

Specifies the model of virtual network interface device to use.

The valid options depend on the configured hypervisor.

  • KVM and QEMU: e1000, ne2k_pci, pcnet, rtl8139, and virtio.
  • VMware: e1000, e1000e, VirtualE1000, VirtualE1000e, VirtualPCNet32, VirtualSriovEthernetCard, and VirtualVmxnet.
  • Xen: e1000, netfront, ne2k_pci, pcnet, and rtl8139.

VMware API driver

vmware_adaptertype

The virtual SCSI or IDE controller used by the hypervisor.

lsiLogic, busLogic, or ide

VMware API driver

vmware_ostype

A VMware GuestID which describes the operating system installed in the image. This value is passed to the hypervisor when creating a virtual machine. If not specified, the key defaults to otherGuest.

For more information, see Images with VMware vSphere.

VMware API driver

vmware_image_version

Currently unused.

1

XenAPI driver

auto_disk_config

If true, the root partition on the disk is automatically resized before the instance boots. This value is only taken into account by the Compute service when using a Xen-based hypervisor with the XenAPI driver. The Compute service will only attempt to resize if there is a single partition on the image, and only if the partition is in ext3 or ext4 format.

true / false

libvirt API driver and XenAPI driver

os_type

The operating system installed on the image. The XenAPI driver contains logic that takes different actions depending on the value of the os_type parameter of the image. For example, for os_type=windows images, it creates a FAT32-based swap partition instead of a Linux swap partition, and it limits the injected host name to less than 16 characters.

linux or windows

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