Useful image properties¶
You can set image properties that can be consumed by other services to affect the behavior of those other services. For example:
Image properties can be used to override specific behaviors defined for Nova flavors
Image properties can be used to affect the behavior of the Nova scheduler
Image properties can be used to affect the behavior of particular Nova hypervisors
Using image properties¶
Some important points to keep in mind:
In order to allow custom image properties, Glance must be configured with the
glance-api.conf
settingallow_additional_image_properties
set to True. (This is the default setting.)The
glance-api.conf
settingimage_property_quota
should be sufficiently high to allow any additional desired properties. (The default is 128.)You can use Glance property protections to control access to specific image properties, should that be desirable. See the Property Protections section of this Guide for more information.
You can use a plugin to the interoperable image import process to set specific properties on non-admin images imported into Glance. See Customizing the image import process for more information. See the original spec, Inject metadata properties automatically to non-admin images for a discussion of the use case addressed by this plugin.
The Nova ImagePropertiesFilter, enabled by default in the Compute Service, consumes image properties to determine proper scheduling of builds to compute hosts. See the Compute schedulers section of the Nova Configuration Guide for more information.
Nova has a setting,
non_inheritable_image_properties
, that allows you to specify which image properties from the image a virtual machine was booted from will not be propagated to a snapshot image of that virtual machine. See the Configuration Options section of the Nova Configuration Guide for more information.Some properties recognized by Nova may have no effect unless a corresponding property is enabled in the server flavor. For example, the
hw_rng_model
image property has no effect unless the Nova flavor has been configured to havehw_rng:allowed
set to True in the flavor’s extra_specs.In a mixed hypervisor environment, the Compute Service uses the
hypervisor_type
image property to match images to the correct hypervisor type.Depending upon what hypervisors are in use in your Nova installation, there may be other image properties that these hypervisors can consume to affect their behavior. Read through the configuration information for your hypervisors in the Hypervisors section of the Nova Configuration Guide for more information.
In particular, the VMware hypervisor driver requires that particular image properties be set for optimal functioning. See the VMware vSphere section of the Nova Configuration Guide for more information.
Image property keys and values¶
Here is a list of useful image properties and the values they expect.
Specific to |
Key |
Description |
Supported values |
---|---|---|---|
All |
|
The CPU architecture that must be supported by the hypervisor. For
example, |
|
All |
|
The hypervisor type. Note that |
|
All |
|
Optional property allows created servers to have a different bandwidth
cap than that defined in the network they are attached to. This factor
is multiplied by the |
Float (default value is |
All |
|
For snapshot images, this is the UUID of the server used to create this image. |
Valid server UUID |
All |
|
Specifies whether the image needs a config drive. |
|
All |
|
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 |
|
The common name of the operating system distribution in lowercase (uses the same data vocabulary as the libosinfo project). Specify only a recognized value for this field. Deprecated values are listed to assist you in searching for the recognized value. |
|
All |
|
The operating system version as specified by the distributor. |
Valid version number (for example, |
All |
|
Secure Boot is a security standard. When the instance starts, Secure Boot first examines software such as firmware and OS by their signature and only allows them to run if the signatures are valid. For Hyper-V: Images must be prepared as Generation 2 VMs. Instance must
also contain |
|
All |
|
By default, guests will be given 60 seconds to perform a graceful shutdown. After that, the VM is powered off. This property allows overriding the amount of time (unit: seconds) to allow a guest OS to cleanly shut down before power off. A value of 0 (zero) means the guest will be powered off immediately with no opportunity for guest OS clean-up. |
Integer value (in seconds) with a minimum of 0 (zero). Default is 60. |
All |
|
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 |
|
Added in the Rocky release. Functionality is similar to traits specified in flavor extra specs. Traits allow specifying a server to build on a compute node with the set of traits specified in the image. The traits are associated with the resource provider that represents the compute node in the Placement API. The syntax of specifying traits is trait:<trait_name>=value, for example:
The nova scheduler will pass required traits specified on the image to the Placement API to include only resource providers that can satisfy the required traits. Traits for the resource providers can be managed using the osc-placement plugin. Image traits are used by the nova scheduler even in cases of volume backed instances, if the volume source is an image with traits. |
Only valid value is
|
All |
|
The virtual machine mode. This represents the host/guest ABI (application binary interface) used for the virtual machine. |
|
libvirt API driver |
|
The preferred number of sockets to expose to the guest. |
Integer. |
libvirt API driver |
|
The preferred number of cores to expose to the guest. |
Integer. |
libvirt API driver |
|
The preferred number of threads to expose to the guest. |
Integer. |
libvirt API driver |
|
Used to pin the virtual CPUs (vCPUs) of instances to the host’s physical CPU cores (pCPUs). Host aggregates should be used to separate these pinned instances from unpinned instances as the latter will not respect the resourcing requirements of the former. |
|
libvirt API driver |
|
Further refine |
|
libvirt API driver |
|
Specifies the type of disk controller to attach CD-ROM devices to. |
As for |
libvirt API driver |
|
Specifies the type of disk controller to attach disk devices to. |
Options depend on the value of nova’s virt_type config option:
|
libvirt API driver |
|
Specifies the type of firmware with which to boot the guest. |
One of |
libvirt API driver |
|
Enables encryption of guest memory at the hardware level, if there are compute hosts available which support this. See nova’s documentation on configuration of the KVM hypervisor for more details. |
|
libvirt API driver |
|
Input devices that allow interaction with a graphical framebuffer, for example to provide a graphic tablet for absolute cursor movement. Currently only supported by the KVM/QEMU hypervisor configuration and VNC or SPICE consoles must be enabled. |
|
libvirt API driver |
|
Adds a random-number generator device to the image’s instances. This image property by itself does not guarantee that a hardware RNG will be used; it expresses a preference that may or may not be satisfied depending upon Nova configuration. The cloud administrator can enable and control device behavior by configuring the instance’s flavor. By default:
rng_dev_path=/dev/hwrng
|
|
libvirt API driver |
|
Adds support for the High Precision Event Timer (HPET) for x86 guests
in the libvirt driver when |
|
libvirt API driver, Hyper-V driver |
|
For libvirt: Enables booting an ARM system using the specified machine
type. By default, if an ARM image is used and its type is not specified,
Compute uses For Hyper-V: Specifies whether the Hyper-V instance will be a generation 1 or generation 2 VM. By default, if the property is not provided, the instances will be generation 1 VMs. If the image is specific for generation 2 VMs but the property is not provided accordingly, the instance will fail to boot. |
For libvirt: Valid types can be viewed by using the
virsh capabilities command (machine types are displayed in
the For hyper-V: Acceptable values are either |
libvirt API driver, XenAPI driver |
|
The operating system installed on the image. The |
|
libvirt API driver |
|
Enables the use of VirtIO SCSI ( |
|
libvirt API driver |
|
Specifies the count of serial ports that should be provided. If
|
Integer |
libvirt API driver |
|
The graphic device model presented to the guest. hw_video_model=none disables the graphics device in the guest and should generally be used when using gpu passthrough. |
|
libvirt API driver |
|
Maximum RAM for the video image. Used only if a |
Integer in MB (for example, |
libvirt API driver |
|
Enables a virtual hardware watchdog device that carries out the
specified action if the server hangs. The watchdog uses the
|
|
libvirt API driver |
|
The kernel command line to be used by the |
|
libvirt API driver and VMware API driver |
|
Specifies the model of virtual network interface device to use. |
|
libvirt API driver |
|
If |
|
libvirt API driver |
|
If |
|
libvirt API driver |
|
Controls emulation of a virtual performance monitoring unit (vPMU) in the guest. To reduce latency in realtime workloads disable the vPMU by setting hw_pmu=false. |
|
libvirt API driver |
|
Some hypervisors add a signature to their guests. While the presence
of the signature can enable some paravirtualization features on the
guest, it can also have the effect of preventing some drivers from
loading. Hiding the signature by setting this property to |
|
VMware API driver |
|
The virtual SCSI or IDE controller used by the hypervisor. |
|
VMware API driver |
|
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 |
See thinkvirt.com. |
VMware API driver |
|
Currently unused. |
|
XenAPI driver |
|
If |
|