Chapter 8. Creating flavors for launching instances

An instance flavor is a resource template that specifies the virtual hardware profile for the instance. Cloud users must specify a flavor when they launch an instance.

A flavor can specify the quantity of the following resources the Compute service must allocate to an instance:

  • The number of vCPUs.
  • The RAM, in MB.
  • The root disk, in GB.
  • The virtual storage, including secondary ephemeral storage and swap disk.

You can specify who can use flavors by making the flavor public to all projects, or private to specific projects or domains.

Flavors can use metadata, also referred to as "extra specs", to specify instance hardware support and quotas. The flavor metadata influences the instance placement, resource usage limits, and performance. For a complete list of available metadata properties, see Flavor metadata.

You can also use the flavor metadata keys to find a suitable host aggregate to host the instance, by matching the extra_specs metadata set on the host aggregate. To schedule an instance on a host aggregate, you must scope the flavor metadata by prefixing the extra_specs key with the aggregate_instance_extra_specs: namespace. For more information, see Creating and managing host aggregates.

A Red Hat OpenStack Platform (RHOSP) deployment includes the following set of default public flavors that your cloud users can use.

Table 8.1. Default Flavors

NamevCPUsRAMRoot Disk Size

m1.nano

1

128 MB

1 GB

m1.micro

1

192 MB

1 GB

Note

Behavior set using flavor properties override behavior set using images. When a cloud user launches an instance, the properties of the flavor they specify override the properties of the image they specify.

8.1. Creating a flavor

You can create and manage specialized flavors for specific functionality or behaviors, for example:

  • Change default memory and capacity to suit the underlying hardware needs.
  • Add metadata to force a specific I/O rate for the instance or to match a host aggregate.

Procedure

  1. Create a flavor that specifies the basic resources to make available to an instance: 

    (overcloud)$ openstack flavor create --ram <size_mb> \
 --disk <size_gb> --vcpus <no_vcpus> \
 [--private --project <project_id>] <flavor_name>
    • Replace <size_mb> with the size of RAM to allocate to an instance created with this flavor.
    • Replace <size_gb> with the size of root disk to allocate to an instance created with this flavor.
    • Replace <no_vcpus> with the number of vCPUs to reserve for an instance created with this flavor.

    • Optional: Specify the --private and --project options to make the flavor accessible only by a particular project or group of users. Replace <project_id> with the ID of the project that can use this flavor to create instances. If you do not specify the accessibility, the flavor defaults to public, which means that it is available to all projects.

      Note

      You cannot make a public flavor private after it has been created.

    • Replace <flavor_name> with a unique name for your flavor.

      For more information about flavor arguments, see Flavor arguments.

  2. Optional: To specify flavor metadata, set the required properties by using key-value pairs: 

    (overcloud)$ openstack flavor set \
 --property <key=value> --property <key=value> ... <flavor_name>
    • Replace <key> with the metadata key of the property you want to allocate to an instance that is created with this flavor. For a list of available metadata keys, see Flavor metadata.
    • Replace <value> with the value of the metadata key you want to allocate to an instance that is created with this flavor.

    • Replace <flavor_name> with the name of your flavor.

      For example, an instance that is launched by using the following flavor has two CPU sockets, each with two CPUs: 

      (overcloud)$ openstack flavor set \
 --property hw:cpu_sockets=2 \
 --property hw:cpu_cores=2 processor_topology_flavor

8.2. Flavor arguments

The openstack flavor create command has one positional argument, <flavor_name>, to specify the name of your new flavor.

The following table details the optional arguments that you can specify as required when you create a new flavor.

Table 8.2. Optional flavor arguments

Optional argumentDescription

--id

Unique ID for the flavor. The default value, auto, generates a UUID4 value. You can use this argument to manually specify an integer or UUID4 value.

--ram

(Mandatory) Size of memory to make available to the instance, in MB.

Default: 256 MB

--disk

(Mandatory) Amount of disk space to use for the root (/) partition, in GB. The root disk is an ephemeral disk that the base image is copied into. When an instance boots from a persistent volume, the root disk is not used.

Note

Creation of an instance with a flavor that has --disk set to 0 requires that the instance boots from volume.

Default: 0 GB

--ephemeral

Amount of disk space to use for the ephemeral disks, in GB. Defaults to 0 GB, which means that no secondary ephemeral disk is created. Ephemeral disks offer machine local disk storage linked to the lifecycle of the instance. Ephemeral disks are not included in any snapshots. This disk is destroyed and all data is lost when the instance is deleted.

Default: 0 GB

--swap

Swap disk size in MB. Do not specify swap in a flavor if the Compute service back end storage is not local storage.

Default: 0 GB

--vcpus

(Mandatory) Number of virtual CPUs for the instance.

Default: 1

--public

The flavor is available to all projects. By default, a flavor is public and available to all projects.

--private

The flavor is only available to the projects specified by using the --project option. If you create a private flavor but add no projects to it then the flavor is only available to the cloud administrator.

--property

Metadata, or "extra specs", specified by using key-value pairs in the following format:

--property <key=value>

Repeat this option to set multiple properties.

--project

Specifies the project that can use the private flavor. You must use this argument with the --private option. If you do not specify any projects, the flavor is visible only to the admin user.

Repeat this option to allow access to multiple projects.

--project-domain

Specifies the project domain that can use the private flavor. You must use this argument with the --private option.

Repeat this option to allow access to multiple project domains.

--description

Description of the flavor. Limited to 65535 characters in length. You can use only printable characters.

8.3. Flavor metadata

Use the --property option to specify flavor metadata when you create a flavor. Flavor metadata is also referred to as extra specs. Flavor metadata determines instance hardware support and quotas, which influence instance placement, instance limits, and performance.

Instance resource usage

Use the property keys in the following table to configure limits on CPU, memory and disk I/O usage by instances.

Table 8.3. Flavor metadata for resource usage

KeyDescription

quota:cpu_shares

Specifies the proportional weighted share of CPU time for the domain. Defaults to the OS provided defaults. The Compute scheduler weighs this value relative to the setting of this property on other instances in the same domain. For example, an instance that is configured with quota:cpu_shares=2048 is allocated double the CPU time as an instance that is configured with quota:cpu_shares=1024.

quota:cpu_period

Specifies the period of time within which to enforce the cpu_quota, in microseconds. Within the cpu_period, each vCPU cannot consume more than cpu_quota of runtime. Set to a value in the range 1000 – 1000000. Set to 0 to disable.

quota:cpu_quota

Specifies the maximum allowed bandwidth for the vCPU in each cpu_period, in microseconds:

  • Set to a value in the range 1000 – 18446744073709551.
  • Set to 0 to disable.
  • Set to a negative value to allow infinite bandwidth.

You can use cpu_quota and cpu_period to ensure that all vCPUs run at the same speed. For example, you can use the following flavor to launch an instance that can consume a maximum of only 50% CPU of a physical CPU computing capability: 

$ openstack flavor set cpu_limits_flavor \
  --property quota:cpu_quota=10000 \
  --property quota:cpu_period=20000

Instance disk tuning

Use the property keys in the following table to tune the instance disk performance.

Note

The Compute service applies the following quality of service settings to storage that the Compute service has provisioned, such as ephemeral storage. To tune the performance of Block Storage (cinder) volumes, you must also configure Quality-of-Service (QOS) values for the volume type. For more information, see Use Quality-of-Service Specifications in the Storage Guide.

Table 8.4. Flavor metadata for disk tuning

KeyDescription

quota:disk_read_bytes_sec

Specifies the maximum disk reads available to an instance, in bytes per second.

quota:disk_read_iops_sec

Specifies the maximum disk reads available to an instance, in IOPS.

quota:disk_write_bytes_sec

Specifies the maximum disk writes available to an instance, in bytes per second.

quota:disk_write_iops_sec

Specifies the maximum disk writes available to an instance, in IOPS.

quota:disk_total_bytes_sec

Specifies the maximum I/O operations available to an instance, in bytes per second.

quota:disk_total_iops_sec

Specifies the maximum I/O operations available to an instance, in IOPS.

Instance network traffic bandwidth

Use the property keys in the following table to configure bandwidth limits on the instance network traffic by configuring the VIF I/O options.

Note

The quota :vif_* properties are deprecated. Instead, you should use the Networking (neutron) service Quality of Service (QoS) policies. For more information about QoS policies, see Configuring Quality of Service (QoS) policies in the Networking Guide. The quota:vif_* properties are only supported when you use the ML2/OVS mechanism driver with NeutronOVSFirewallDriver set to iptables_hybrid.

Table 8.5. Flavor metadata for bandwidth limits

KeyDescription

quota:vif_inbound_average

(Deprecated) Specifies the required average bit rate on the traffic incoming to the instance, in kbps.

quota:vif_inbound_burst

(Deprecated) Specifies the maximum amount of incoming traffic that can be burst at peak speed, in KB.

quota:vif_inbound_peak

(Deprecated) Specifies the maximum rate at which the instance can receive incoming traffic, in kbps.

quota:vif_outbound_average

(Deprecated) Specifies the required average bit rate on the traffic outgoing from the instance, in kbps.

quota:vif_outbound_burst

(Deprecated) Specifies the maximum amount of outgoing traffic that can be burst at peak speed, in KB.

quota:vif_outbound_peak

(Deprecated) Specifies the maximum rate at which the instance can send outgoing traffic, in kbps.

Hardware video RAM

Use the property key in the following table to configure limits on the instance RAM to use for video devices.

Table 8.6. Flavor metadata for video devices

KeyDescription

hw_video:ram_max_mb

Specifies the maximum RAM to use for video devices, in MB. Use with the hw_video_ram image property. hw_video_ram must be less than or equal to hw_video:ram_max_mb.

Watchdog behavior

Use the property key in the following table to enable the virtual hardware watchdog device on the instance.

Table 8.7. Flavor metadata for watchdog behavior

KeyDescription

hw:watchdog_action

Specify to enable the virtual hardware watchdog device and set its behavior. Watchdog devices perform the configured action if the instance hangs or fails. The watchdog uses the i6300esb device, which emulates a PCI Intel 6300ESB. If hw:watchdog_action is not specified, the watchdog is disabled.

Set to one of the following valid values:

  • disabled: (Default) The device is not attached.
  • reset: Force instance reset.
  • poweroff: Force instance shut down.
  • pause: Pause the instance.

  • none: Enable the watchdog, but do nothing if the instance hangs or fails.  

    Note

    Watchdog behavior that you set by using the properties of a specific image override behavior that you set by using flavors.

Random number generator

Use the property keys in the following table to enable the random number generator device on the instance.

Table 8.8. Flavor metadata for random number generator

KeyDescription

hw_rng:allowed

Set to True to enable the random number generator device that is added to the instance through its image properties.

hw_rng:rate_bytes

Specifies the maximum number of bytes that the instance can read from the entropy of the host, per period.

hw_rng:rate_period

Specifies the duration of the read period in milliseconds.

Virtual Performance Monitoring Unit (vPMU)

Use the property key in the following table to enable the vPMU for the instance.

Table 8.9. Flavor metadata for vPMU

KeyDescription

hw:pmu

Set to True to enable a vPMU for the instance.

Tools such as perf use the vPMU on the instance to provide more accurate information to profile and monitor instance performance. For realtime workloads, the emulation of a vPMU can introduce additional latency which might be undesirable. If the telemetry it provides is not required, set hw:pmu=False.

Instance CPU topology

Use the property keys in the following table to define the topology of the processors in the instance.

Table 8.10. Flavor metadata for CPU topology

KeyDescription

hw:cpu_sockets

Specifies the preferred number of sockets for the instance.

Default: the number of vCPUs requested

hw:cpu_cores

Specifies the preferred number of cores per socket for the instance.

Default: 1

hw:cpu_threads

Specifies the preferred number of threads per core for the instance.

Default: 1

hw:cpu_max_sockets

Specifies the maximum number of sockets that users can select for their instances by using image properties.

Example: hw:cpu_max_sockets=2

hw:cpu_max_cores

Specifies the maximum number of cores per socket that users can select for their instances by using image properties.

hw:cpu_max_threads

Specifies the maximum number of threads per core that users can select for their instances by using image properties.

Serial ports

Use the property key in the following table to configure the number of serial ports per instance.

Table 8.11. Flavor metadata for serial ports

KeyDescription

hw:serial_port_count

Maximum serial ports per instance.

CPU pinning policy

By default, instance virtual CPUs (vCPUs) are sockets with one core and one thread. You can use properties to create flavors that pin the vCPUs of instances to the physical CPU cores (pCPUs) of the host. You can also configure the behavior of hardware CPU threads in a simultaneous multithreading (SMT) architecture where one or more cores have thread siblings.

Use the property keys in the following table to define the CPU pinning policy of the instance.

Table 8.12. Flavor metadata for CPU pinning

KeyDescription

hw:cpu_policy

Specifies the CPU policy to use. Set to one of the following valid values:

  • shared: (Default) The instance vCPUs float across host pCPUs.
  • dedicated: Pin the instance vCPUs to a set of host pCPUs. This creates an instance CPU topology that matches the topology of the CPUs to which the instance is pinned. This option implies an overcommit ratio of 1.0.

hw:cpu_thread_policy

Specifies the CPU thread policy to use when hw:cpu_policy=dedicated. Set to one of the following valid values:

  • prefer: (Default) The host might or might not have an SMT architecture. If an SMT architecture is present, the Compute scheduler gives preference to thread siblings.

  • isolate: The host must not have an SMT architecture or must emulate a non-SMT architecture. This policy ensures that the Compute scheduler places the instance on a host without SMT by requesting hosts that do not report the HW_CPU_HYPERTHREADING trait. It is also possible to request this trait explicitly by using the following property: 

    --property trait:HW_CPU_HYPERTHREADING=forbidden

    If the host does not have an SMT architecture, the Compute service places each vCPU on a different core as expected. If the host does have an SMT architecture, then the behaviour is determined by the configuration of the [workarounds]/disable_fallback_pcpu_query parameter:

    • True: The host with an SMT architecture is not used and scheduling fails.
    • False: The Compute service places each vCPU on a different physical core. The Compute service does not place vCPUs from other instances on the same core. All but one thread sibling on each used core is therefore guaranteed to be unusable.

  • require: The host must have an SMT architecture. This policy ensures that the Compute scheduler places the instance on a host with SMT by requesting hosts that report the HW_CPU_HYPERTHREADING trait. It is also possible to request this trait explicitly by using the following property: 

    --property trait:HW_CPU_HYPERTHREADING=required

    The Compute service allocates each vCPU 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.

Instance PCI NUMA affinity policy

Use the property key in the following table to create flavors that specify the NUMA affinity policy for PCI passthrough devices and SR-IOV interfaces.

Table 8.13. Flavor metadata for PCI NUMA affinity policy

KeyDescription

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 this 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.

Instance NUMA topology

You can use properties to create flavors that define the host NUMA placement for the instance vCPU threads, and the allocation of instance vCPUs and memory from the host NUMA nodes.

Defining a NUMA topology for the instance improves the performance of the instance OS for flavors whose memory and vCPU allocations are larger than the size of NUMA nodes in the Compute hosts.

The Compute scheduler uses these properties to determine a suitable host for the instance. For example, a cloud user launches an instance by using the following flavor: 

$ openstack flavor set numa_top_flavor \
  --property hw:numa_nodes=2 \
  --property hw:numa_cpus.0=0,1,2,3,4,5 \
  --property hw:numa_cpus.1=6,7 \
  --property hw:numa_mem.0=3072 \
  --property hw:numa_mem.1=1024

The Compute scheduler searches for a host that has two NUMA nodes, one with 3GB of RAM and the ability to run six CPUs, and the other with 1GB of RAM and two CPUS. If a host has a single NUMA node with capability to run eight CPUs and 4GB of RAM, the Compute scheduler does not consider it a valid match.

Note

NUMA topologies defined by a flavor cannot be overridden by NUMA topologies defined by the image. The Compute service raises an ImageNUMATopologyForbidden error if the image NUMA topology conflicts with the flavor NUMA topology.

Caution

You cannot use this feature to constrain instances to specific host CPUs or NUMA nodes. Use this feature only after you complete extensive testing and performance measurements. You can use the hw:pci_numa_affinity_policy property instead.

Use the property keys in the following table to define the instance NUMA topology.

Table 8.14. Flavor metadata for NUMA topology

KeyDescription

hw:numa_nodes

Specifies the number of host NUMA nodes to restrict execution of instance vCPU threads to. If not specified, the vCPU threads can run on any number of the available host NUMA nodes.

hw:numa_cpus.N

A comma-separated list of instance vCPUs to map to instance NUMA node N. If this key is not specified, vCPUs are evenly divided among available NUMA nodes.

N starts from 0. Use *.N values with caution, and only if you have at least two NUMA nodes.

This property is valid only if you have set hw:numa_nodes, and is required only if the NUMA nodes of the instance have an asymmetrical allocation of CPUs and RAM, which is important for some NFV workloads.

hw:numa_mem.N

The number of MB of instance memory to map to instance NUMA node N. If this key is not specified, memory is evenly divided among available NUMA nodes.

N starts from 0. Use *.N values with caution, and only if you have at least two NUMA nodes.

This property is valid only if you have set hw:numa_nodes, and is required only if the NUMA nodes of the instance have an asymmetrical allocation of CPUs and RAM, which is important for some NFV workloads.

Warning

If the combined values of hw:numa_cpus.N or hw:numa_mem.N are greater than the available number of CPUs or memory respectively, the Compute service raises an exception.

Instance memory encryption

Use the property key in the following table to enable encryption of instance memory.

Table 8.15. Flavor metadata for memory encryption

KeyDescription

hw:mem_encryption

Set to True to request memory encryption for the instance. For more information, see Configuring AMD SEV Compute nodes to provide memory encryption for instances.

CPU real-time policy

Use the property keys in the following table to define the real-time policy of the processors in the instance.

Note
  • Although most of your instance vCPUs can run with a real-time policy, you must mark at least one vCPU as non-real-time to use for both non-real-time guest processes and emulator overhead processes.
  • To use this extra spec, you must enable pinned CPUs.

Table 8.16. Flavor metadata for CPU real-time policy

KeyDescription

hw:cpu_realtime

Set to yes to create a flavor that assigns a real-time policy to the instance vCPUs.

Default: no

hw:cpu_realtime_mask

Specifies the vCPUs to not assign a real-time policy to. You must prepend the mask value with a caret symbol (^). The following example indicates that all vCPUs except vCPUs 0 and 1 have a real-time policy: 

$ openstack flavor set <flavor> \
 --property hw:cpu_realtime="yes" \
 --property hw:cpu_realtime_mask=^0-1
Note

If the hw_cpu_realtime_mask property is set on the image then it takes precedence over the hw:cpu_realtime_mask property set on the flavor.

Emulator threads policy

You can assign a pCPU to an instance to use for emulator threads. Emulator threads are emulator processes that are not directly related to the instance. A dedicated emulator thread pCPU is required for real-time workloads. To use the emulator threads policy, you must enable pinned CPUs by setting the following property: 

--property hw:cpu_policy=dedicated

Use the property key in the following table to define the emulator threads policy of the instance.

Table 8.17. Flavor metadata for the emulator threads policy

KeyDescription

hw:emulator_threads_policy

Specifies the emulator threads policy to use for instances. Set to one of the following valid values:

  • share: The emulator thread floats across the pCPUs defined in the NovaComputeCpuSharedSet heat parameter. If NovaComputeCpuSharedSet is not configured, then the emulator thread floats across the pinned CPUs that are associated with the instance.
  • isolate: Reserves an additional dedicated pCPU per instance for the emulator thread. Use this policy with caution, as it is prohibitively resource intensive.
  • unset: (Default) The emulator thread policy is not enabled, and the emulator thread floats across the pinned CPUs associated with the instance.

Instance memory page size

Use the property keys in the following table to create an instance with an explicit memory page size.

Table 8.18. Flavor metadata for memory page size

KeyDescription

hw:mem_page_size

Specifies the size of large pages to use to back the instances. Use of this option creates an implicit NUMA topology of 1 NUMA node unless otherwise specified by hw:numa_nodes. Set to one of the following valid values:

  • large: Selects a page size larger than the smallest page size supported on the host, which can be 2 MB or 1 GB on x86_64 systems.
  • small: Selects the smallest page size supported on the host. On x86_64 systems this is 4 kB (normal pages).
  • any: Selects the largest available huge page size, as determined by the libvirt driver.
  • <pagesize>: (String) Sets an explicit page size if the workload has specific requirements. Use an integer value for the page size in KB, or any standard suffix. For example: 4KB, 2MB, 2048, 1GB.
  • unset: (Default) Large pages are not used to back instances and no implicit NUMA topology is generated.

PCI passthrough

Use the property key in the following table to attach a physical PCI device, such as a graphics card or a network device, to an instance. For more information about using PCI passthrough, see Configuring PCI passthrough.

Table 8.19. Flavor metadata for PCI passthrough

KeyDescription

pci_passthrough:alias

Specifies the PCI device to assign to an instance by using the following format: 

<alias>:<count>
  • Replace <alias> with the alias that corresponds to a particular PCI device class.
  • Replace <count> with the number of PCI devices of type <alias> to assign to the instance.

Hypervisor signature

Use the property key in the following table to hide the hypervisor signature from the instance.

Table 8.20. Flavor metadata for hiding hypervisor signature

KeyDescription

hide_hypervisor_id

Set to True to hide the hypervisor signature from the instance, to allow all drivers to load and work on the instance.

Instance resource traits

Each resource provider has a set of traits. Traits are the qualitative aspects of a resource provider, for example, the type of storage disk, or the Intel CPU instruction set extension. An instance can specify which of these traits it requires.

The traits that you can specify are defined in the os-traits library. Example traits include the following:

  • COMPUTE_TRUSTED_CERTS
  • COMPUTE_NET_ATTACH_INTERFACE_WITH_TAG
  • COMPUTE_IMAGE_TYPE_RAW
  • HW_CPU_X86_AVX
  • HW_CPU_X86_AVX512VL
  • HW_CPU_X86_AVX512CD

For details about how to use the os-traits library, see https://docs.openstack.org/os-traits/latest/user/index.html.

Use the property key in the following table to define the resource traits of the instance.

Table 8.21. Flavor metadata for resource traits

KeyDescription

trait:<trait_name>

Specifies Compute node traits. Set the trait to one of the following valid values:

  • required: The Compute node selected to host the instance must have the trait.
  • forbidden: The Compute node selected to host the instance must not have the trait.

Example: 

$ openstack flavor set --property trait:HW_CPU_X86_AVX512BW=required avx512-flavor

Instance bare-metal resource class

Use the property key in the following table to request a bare-metal resource class for an instance.

Table 8.22. Flavor metadata for bare-metal resource class

KeyDescription

resources:<resource_class_name>

Use this property to specify standard bare-metal resource classes to override the values of, or to specify custom bare-metal resource classes that the instance requires.

The standard resource classes that you can override are VCPU, MEMORY_MB and DISK_GB. To prevent the Compute scheduler from using the bare-metal flavor properties for scheduling instance, set the value of the standard resource classes to 0.

The name of custom resource classes must start with CUSTOM_. To determine the name of a custom resource class that corresponds to a resource class of a Bare Metal service node, convert the resource class to uppercase, replace all punctuation with an underscore, and prefix with CUSTOM_.

For example, to schedule instances on a node that has --resource-class baremetal.SMALL, create the following flavor: 

$ openstack flavor set \
 --property resources:CUSTOM_BAREMETAL_SMALL=1 \
 --property resources:VCPU=0 --property resources:MEMORY_MB=0 \
 --property resources:DISK_GB=0 compute-small