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
Image properties can be used to provide additional information to Ironic (even when Nova is not used)
Some important points to keep in mind:
In order to allow custom image properties, Glance must be configured with
the glance-api.conf
setting allow_additional_image_properties
set
to True. (This is the default setting.)
The glance-api.conf
setting image_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.
Glance reserves properties namespaced with the os_glance
prefix
for its own use and will refuse attempts by API users to set or
change them.
You can use a plugin to the interoperable image import process to set specific properties on non-admin images imported into Glance. See Copying existing-image in multiple stores 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
have hw_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.
Here is a list of useful image properties and the values they expect.
architecture
str
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. We strongly recommend using
the architecture data vocabulary defined by the libosinfo project for this purpose.
One of:
aarch64
- ARM 64-bit
alpha
- DEC 64-bit RISC
armv7l
- ARM Cortex-A7 MPCore
cris
- Ethernet, Token Ring, AXis—Code Reduced Instruction Set
ia64
- Itanium
lm32
- Lattice Micro32
m68k
- Motorola 68000
microblaze
- Xilinx 32-bit FPGA (Big Endian)
microblazeel
- Xilinx 32-bit FPGA (Little 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)
s390x
- S/390 64-bit
sh4eb
- SuperH SH-4 (Big Endian)
sparc64
- Scalable Processor Architecture, 64-bit
unicore32
- Microprocessor Research and Development Center RISC Unicore32
x86_64
- 64-bit extension of IA-32
xtensaeb
- Tensilica Xtensa configurable microprocessor core (Big Endian)
hypervisor_type
str
The hypervisor type. Note that qemu
is used for both QEMU and KVM
hypervisor types.
One of:
hyperv
ironic
lxc
qemu
uml
vmware
xen
.
instance_uuid
str
For snapshot images, this is the UUID of the server used to create this image. The value must be a valid server UUID.
img_config_drive
str
Specifies whether the image needs a config drive.
One of:
mandatory
optional
(default if property is not used)
img_type
str
Specifies the partitioning type of the image. The default value is
partition
if the kernel_id
/ramdisk_id
properties are present,
otherwise whole-disk
.
One of:
whole-disk
- an image with a partition table embedded.
partition
- an image with only the root partition without a partition
table.
Note
This property is currently only recognized by Ironic.
kernel_id
str
The ID of an image stored in the Image service that should be used as the kernel when booting an AMI-style image. The value must be a valid image ID
os_admin_user
str
The name of the user with admin privileges.
The value must be a valid username (defaults to root
for Linux guests and
Administrator
for Windows guests).
os_distro
str
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.
One of:
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``.
rocky
- Rocky Linux. Do not use Rocky
or rockylinux
.
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
or windoze
.
os_version
str
The operating system version as specified by the distributor.
The value must be a valid version number (for example, 11.10
).
os_secure_boot
str
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 hw_machine_type=hyperv-gen2
image property. Linux
guests will also require bootloader’s digital signature provided as
os_secure_boot_signature
and
hypervisor_version_requires'>=10.0'
image properties.
One of:
required
- Enable the Secure Boot feature.
disabled
or optional
- (default if property not used) Disable the
Secure Boot feature.
os_shutdown_timeout
int
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.
ramdisk_id
The ID of image stored in the Image service that should be used as the ramdisk when booting an AMI-style image.
The value must be a valid image ID.
rootfs_uuid
For whole-disk images (see img_type
above), the UUID of the root
partition.
This property is used by Ironic when configuring software RAID.
trait:<trait_name>
str
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:
trait:HW_CPU_X86_AVX2=required
trait:STORAGE_DISK_SSD=required
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.
The only valid value is required
. Any other value is invalid.
One of:
required
- <trait_name> is required on the resource provider that
represents the compute node on which the image is launched.
vm_mode
str
The virtual machine mode. This represents the host/guest ABI (application binary interface) used for the virtual machine.
One of:
hvm
- Fully virtualized. This is the mode used by QEMU and KVM.
xen
- Xen 3.0 paravirtualized.
uml
- User Mode Linux paravirtualized.
exe
- Executables in containers. This is the mode used by LXC.
hw_cpu_sockets
int
The preferred number of sockets to expose to the guest.
Only supported by the libvirt driver.
hw_cpu_cores
int
The preferred number of cores to expose to the guest.
Only supported by the libvirt driver.
hw_cpu_threads
int
The preferred number of threads to expose to the guest.
Only supported by the libvirt driver.
hw_cpu_policy
str
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.
Only supported by the libvirt driver.
One of:
shared
- (default if property not specified) The guest vCPUs will be
allowed to freely float across host pCPUs, albeit potentially constrained
by NUMA policy.
dedicated
- The guest vCPUs will be strictly pinned to a set of
host pCPUs. In the absence of an explicit vCPU topology request, the
drivers typically expose all vCPUs as sockets with one core and one
thread. When strict CPU pinning is in effect the guest CPU topology
will be setup to match the topology of the CPUs to which it is pinned.
This option implies an overcommit ratio of 1.0. For example, if a two
vCPU guest is pinned to a single host core with two threads, then the
guest will get a topology of one socket, one core, two threads.
hw_cpu_thread_policy
str
Further refine hw_cpu_policy=dedicated
by stating how hardware CPU
threads in a simultaneous multithreading-based (SMT) architecture be
used. SMT-based architectures include Intel processors with
Hyper-Threading technology. In these architectures, processor cores
share a number of components with one or more other cores. Cores in
such architectures are commonly referred to as hardware threads, while
the cores that a given core share components with are known as thread
siblings.
Only supported by the libvirt driver.
One of:
prefer
- (default if property not specified) The host may or may not
have an SMT architecture. Where an SMT architecture is present, thread
siblings are preferred.
isolate
- The host must not have an SMT architecture or must
emulate a non-SMT architecture. If the host does not have an SMT
architecture, each vCPU is placed on a different core as expected. If
the host does have an SMT architecture - that is, one or more cores
have thread siblings - then each vCPU is placed on a different
physical core. No vCPUs from other guests are placed on the same core.
All but one thread sibling on each utilized core is therefore
guaranteed to be unusable.
require
- The host must have an SMT architecture. Each vCPU is
allocated on thread siblings. If the host does not have an SMT
architecture, then it is not used. If the host has an SMT
architecture, but not enough cores with free thread siblings are
available, then scheduling fails.
hw_cdrom_bus
str
Specifies the type of disk controller to attach CD-ROM devices to.
As for hw_disk_bus
.
Only supported by the libvirt driver.
hw_disk_bus
str
Specifies the type of disk controller to attach disk devices to.
Only supported by the libvirt driver.
Options depend on the value of nova’s virt_type config option:
For qemu
and kvm
: one of scsi
, virtio
,
uml
, xen
, ide
, usb
, or lxc
.
For xen
: one of xen
or ide
.
For uml
: must be uml
.
For lxc
: must be lxc
.
For parallels
: one of ide
or scsi
.
hw_firmware_type
Specifies the type of firmware with which to boot the guest.
Only supported by the libvirt driver.
One of:
bios
uefi
hw_mem_encryption
bool
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.
Only supported by the libvirt driver.
hw_pointer_model
str
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.
Only supported by the libvirt driver.
One of:
usbtablet
hw_rng_model
str
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:
The generator device is disabled.
/dev/urandom
is used as the default entropy source. To
specify a physical hardwre RNG device, use the following option in
the nova.conf
file:
rng_dev_path=/dev/hwrng
The use of a hardware random number generator must be configured in a
flavor’s extra_specs by setting hw_rng:allowed
to True in the
flavor definition.
Only supported by the libvirt driver.
One of:
virtio
Other supported device.
hw_time_hpet
bool
Adds support for the High Precision Event Timer (HPET) for x86 guests
in the libvirt driver when hypervisor_type=qemu
and
architecture=i686
or architecture=x86_64
. The timer can be
enabled by setting hw_time_hpet=true
. By default HPET remains
disabled.
Only supported by the libvirt driver.
hw_machine_type
str
For libvirt: 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.
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 machine
tag).
For hyper-V: Acceptable values are either hyperv-gen1
or
hyperv-gen2
.
Only supported by the libvirt and Hyper-V drivers.
os_type
str
The operating system installed on the image. The libvirt
API 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.
Only supported by the libvirt driver.
One of:
linux
windows
hw_scsi_model
str
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.
Only supported by the libvirt driver.
One of:
virtio-scsi
hw_serial_port_count
int
Specifies the count of serial ports that should be provided. If
hw:serial_port_count
is not set in the flavor’s extra_specs, then
any count is permitted. If hw:serial_port_count
is set, then this
provides the default serial port count. It is permitted to override the
default serial port count, but only with a lower value.
Only supported by the libvirt driver.
hw_video_model
str
The graphic device model presented to the guest. none
disables the
graphics device in the guest and should generally be used when using GPU
passthrough.
One of:
vga
cirrus
vmvga
xen
qxl
virtio
gop
none
bochs
Only supported by the libvirt driver.
hw_video_ram
int
Maximum RAM in MB 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
.
Only supported by the libvirt driver.
hw_watchdog_action
str
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.
Only supported by the libvirt driver.
One of:
disabled
- (default) 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.
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.
os_command_line
str
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
).
Only supported by the libvirt driver.
hw_vif_model
str
Specifies the model of virtual network interface device to use.
Only supported by the libvirt driver and VMware API drivers.
The valid options depend on the configured hypervisor.
KVM
and QEMU
: e1000
, e1000e
, ne2k_pci
, pcnet
,
rtl8139
, virtio
and vmxnet3
.
VMware: e1000
, e1000e
, VirtualE1000
, VirtualE1000e
,
VirtualPCNet32
, VirtualVmxnet
and VirtualVmxnet3
.
Xen: e1000
, netfront
, ne2k_pci
, pcnet
, and
rtl8139
.
hw_vif_multiqueue_enabled
bool
If true
, this enables the virtio-net multiqueue
feature. In
this case, the driver sets the number of queues equal to the number
of guest vCPUs. This makes the network performance scale across a
number of vCPUs.
Only supported by the libvirt driver.
hw_boot_menu
bool
If true
, enables the BIOS bootmenu. In cases where both the image
metadata and Extra Spec are set, the Extra Spec setting is used. This
allows for flexibility in setting/overriding the default behavior as
needed.
Only supported by the libvirt driver.
hw_pmu
bool
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
.
Only supported by the libvirt driver.
img_hide_hypervisor_id
bool
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 true
may allow such drivers to load and work.
Only supported by the libvirt driver.
vmware_adaptertype
str
The virtual SCSI or IDE controller used by the hypervisor.
Only supported by the VMWare API driver.
One of:
lsiLogic
lsiLogicsas
busLogic
ide
paraVirtual
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
.
See thinkvirt.com for supported
values.
Only supported by the VMWare API driver.
vmware_image_version
int
Currently unused.
instance_type_rxtx_factor
float
Deprecated and currently unused.
auto_disk_config
bool
Deprecated and currently unused.
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.