Hardware

As a tester I want to specify detailed hardware requirements for the guest on which the tests will be executed.

As part of the provision step it is possible to use the hardware key to specify additional requirements for the testing environment. This provides a generic and an extensible way to write down essential hardware requirements. For example one consistent way how to specify at least 2 GB of RAM for all supported provisioners.

Introduction

Individual requirements are provided as a simple key: value pairs, for example the minimum amount of memory, or the related information is grouped under a common parent, for example cores or model under the cpu key.

Comparison operators

The value part of the constraint follows the schema [operator] actual-value. The operator is optional, it may be any of the following: =, !=, >, >=, <, >=, ~ (regex match), and !~ (regex not matches). When operator is omitted, = is assumed.

Note

It is highly recommended to wrap values with single or double quotes, i.e. memory: '>= 8 GiB' rather than memory: >= 8 GiB. This should prevent any unexpected processing by parsers loading the fmf content. Without explicit quotes, some operators might lead to unexpected outcome.

# This...
memory: '8 GB'
# ... is the same as this:
memory: '= 8 GB'

# Optional operators at the start of the value
memory: '!= 8 GB'
memory: '> 8 GB'
memory: '>= 8 GB'
memory: '< 8 GB'
memory: '<= 8 GB'

Search

Regular expressions can be used for selected fields such as the cpu model name or hostname. Use ~ for positive and !~ for negative regular expressions at the beginning of the string. Any leading or trailing white space from the search string is removed.

Please note, that the full extent of regular expressions might not be supported across all provision implementations. The .* notation, however, should be supported everywhere:

# Search for processors using a cpu model name
cpu:
    model-name: "~ AMD"

# Select guests with a non-matching hostname
hostname: "!~ kvm-01.*"

Logic operators

When multiple environment requirements are provided the provision implementation should attempt to satisfy all of them. It is also possible to write this explicitly using the and operator containing a list of dictionaries with individual requirements. When the or operator is used, any of the alternatives provided in the list should be sufficient:

# By default exact value expected, these are equivalent:
cpu:
    model: 37
cpu:
    model: '= 37'

# Using advanced logic operators
and:
  - cpu:
        family: 15
  - or:
      - cpu:
            model: 65
      - cpu:
            model: 67
      - cpu:
            model: 69

Units

The pint library is used for processing various units, both decimal and binary prefixes can be used:

1 MB = 1 000 000 B
1 MiB = 1 048 576 B

Notes

The implementation for this common hardware key is in progress. Features under this section marked as implemented are already supported by the artemis plugin. Support in other provision plugins is on the way. Check individual plugin documentation for additional information on the hardware requirement support.

Note

Some plugins may require additional configuration. For example, Artemis can provision machines with disks of a particular size, but to do so, Artemis maintainers must configure disk sizes for various AWS / OpenStack / Azure flavors. The constraint is supported and implemented, but it will not deliver the required virtual machine when the plugin’s backend, the Artemis deployment, isn’t configured correctly.

Note

Some plugins may support requirements that are impossible to satisfy, e.g. the local plugin can support the cpu.family requirement, but it is hard-locked to the CPU of one’s own machine.

Examples:

# Use the artemis plugin to provision the latest Fedora on
# a guest with the x86_64 architecture and 8 GB of memory
provision:
    how: artemis
    image: fedora
    hardware:
        arch: x86_64
        memory: 8 GB

arch

Select the desired architecture

Examples:

# Architecture (any of well-known short architecture names,
# for example aarch64, i386, ppc64, ppc64le, s390x, x86_64)
arch: x86_64

Status: implemented

boot

Features related to machine boot

Examples:

# Guest with BIOS
boot:
    method: bios

# Guest with UEFI
boot:
    method: uefi

Status: implemented

compatible

Select guest based on given compatibility

Note

This is a draft, the story is not implemented yet.

Pick only guests compatible with given operating system distribution. See the context dimension definitions for the list of supported values of the distro key. Must be a list of strings.

Examples:

# Select a guest compatible with both rhel-8 and rhel-9
compatible:
    distro:
      - rhel-8
      - rhel-9

Status: idea

cpu

Choose system according to the processor features

Examples:

# Processor-related stuff grouped together
cpu:
    # The total number of various CPU components in the system.
    sockets: 1
    cores: 4
    threads: 8

    # Ther number of various CPU components per their parent.
    cores-per-socket: 4
    threads-per-core: 2

    # The total number of logical CPUs.
    processors: 8

    # CPU model name. Usually reported as such by /proc/cpuinfo or lscpu.
    model-name: Intel(R) Core(TM) i7-10610U CPU @ 1.80GHz
    # CPU model number.
    model: 142
    # CPU family name.
    family-name: Comet Lake
    # CPU family number.
    family: 6

    # CPU flag(s) as reported with /proc/cpuinfo
    # Field applies an implicit "and" to listed flags
    # Supported operators: "=" and "!="
    flag:
      - avx
      - avx2
      - "!= smep"

Status: implemented

disk

Choose the disk size

Examples:

# Disk group used to allow possible future extensions
disk:
  - size: 500 GB

# Multiple disks can be requested as well
disk:
  - size: '>= 2 GB'
  - size: '>= 20 GB'

Status: implemented

hostname

Select specific guest by its hostname

Examples:

# Choose machine with given hostname
hostname: kvm-01.lab.us-east-2.company.com

# Hostname matching a regular expression
hostname: "~ kvm-01.*"

# Hostname not matching a regular expression
hostname: "!~ kvm-01.*"

Status: implemented

memory

Select the desired amount of memory

Examples:

# Require an exact amount of memory
memory: 8 GB

# Pick a guest with at least 8 GB
memory: ">= 8 GB"

Status: implemented

network

Select guests with given network devices

Note

This is a draft, the story is not implemented yet.

Examples:

# Select by vendor and device name
network:
  - type: eth
    vendor-name: ~ ^Broadcom
    device-name: ~ ^NetXtreme II BCM

Status: idea

system

Select machine with given system attributes

Note

This is a draft, the story is not implemented yet.

Use the vendor key to choose system by specific vendor, model to provide system’s model name, numa-nodes to select systems with a given number of NUMA nodes.

Examples:

system:
    vendor: HPE
    model: ProLiant DL385 Gen10
    numa-nodes: '>= 2'

Status: idea

tpm

Require the Trusted Platform Module features

Note

This is a draft, the story is not implemented yet.

Use the version key to select the desired tpm version, its value must be a string.

Examples:

tpm:
    version: "2.0"

Status: idea

virtualization

Features related to virtualization

This section allows to select guests which are virtualized or support virtualization. Use the hypervisor key to select specific implementation, for example hyperv, kvm, nitro, powerkvm, powervm, vmware or xen.

Examples:

# Require a guest which supports virtualization
virtualization:
    is-supported: true

# Ask for a virtualized guest using kvm hypervisor
virtualization:
    is-virtualized: true
    hypervisor: kvm

Status: implemented