Provision Plugins

Hard reboot

Hard reboot is not yet supported by all provision plugins, and therefore the following features may not work with plugins that lack the capability:

restart-with-reboot test key
reboot action of the watchdog test check

Following plugins fully implement hard reboot:

connect (Only when hard-reboot key is defined)
beaker
container
virtual

Hardware requirement support

Below you can find a matrix documenting which hardware requirement are supported by plugins bundled with tmt.

Requirement	`artemis`	`beaker`	`bootc`	`connect`	`container`	`local`	`virtual`
beaker	❌	✅ [1]	❌	❌	❌	❌	❌
boot	✅	❌	❌	❌	❌	❌	❌
compatible	✅	❌	❌	❌	❌	❌	❌
cpu	✅ [2]	✅ [3]	❌	❌	❌	❌	✅ [4]
device	❌	❌	❌	❌	❌	❌	❌
disk	✅ [5]	✅ [6]	❌	❌	❌	❌	✅ [7]
gpu	❌	❌	❌	❌	❌	❌	❌
hostname	✅	✅	❌	❌	❌	❌	❌
iommu	❌	✅ [8]	❌	❌	❌	❌	❌
location	❌	✅ [9]	❌	❌	❌	❌	❌
memory	✅	✅	❌	❌	❌	❌	✅ [10]
network	✅ [11]	❌	❌	❌	❌	❌	❌
system	❌	✅ [12]	❌	❌	❌	❌	❌
tpm	✅	✅	❌	❌	❌	❌	✅ [13]
virtualization	✅	✅ [14]	❌	❌	❌	❌	❌
zcrypt	✅	✅	❌	❌	❌	❌	❌

Common Keys

The following keys are accepted by all plugins of the provision step.

name:

The name of the step phase.

order:

Order in which the phase should be handled.

Default: 50

summary:

Concise summary describing purpose of the phase.

Default: not set

when: RULE

If specified, phase is run only if any rule matches plan context.

Default: not set

artemis

Warning

Please, be aware that the documentation below is a work in progress. We are working on fixing it, adding missing bits and generally making it better. Also, it was originally used for command line help only, therefore the formatting is often suboptimal.

Provision guest using Artemis backend.

Minimal configuration could look like this:

provision:
    how: artemis
    image: Fedora
    api-url: https://your-artemis.com/

Note

The actual value of image depends on what images - or “composes” as Artemis calls them - supports and can deliver.

Note

The api-url can be also given via TMT_PLUGIN_PROVISION_ARTEMIS_API_URL environment variable.

Full configuration example:

provision:
    how: artemis

    # Artemis API
    api-url: https://your-artemis.com/
    api-version: 0.0.32

    # Mandatory environment properties
    image: Fedora

    # Optional environment properties
    arch: aarch64
    pool: optional-pool-name

    # Provisioning process control (optional)
    priority-group: custom-priority-group
    keyname: custom-SSH-key-name

    # Labels to be attached to guest request (optional)
    user-data:
        foo: bar

    # Timeouts and deadlines (optional)
    provision-timeout: 3600
    provision-tick: 10
    api-timeout: 600
    api-retries: 5
    api-retry-backoff-factor: 1

Configuration

See also Common Keys accepted by the plugin.

api-retries: COUNT

How many attempts to use when talking to API, 10 by default.

Default: 10

api-retry-backoff-factor: COUNT

A factor for exponential API retry backoff, 1 by default.

Default: 1

api-timeout: SECONDS

How long to wait for API operations to complete, 10 seconds by default.

Default: 10

api-url: URL

Artemis API URL.

Default: http://127.0.0.1:8001

api-version: X.Y.Z

Artemis API version to use.

Default: 0.0.72

arch: ARCH

Architecture to provision.

Default: x86_64

become: true|false

Whether to run shell scripts in tests, prepare, and finish with sudo.

Default: false

hardware: KEY=VALUE

Add a hardware requirement.

Default: not set

image: COMPOSE

Image (or “compose” in Artemis terminology) to provision.

Default: not set

key: PATH

Private key for login into the guest system.

Default: not set

keyname: NAME

SSH key name.

Default: default

kickstart: KEY=VALUE

Optional Beaker kickstart to use when provisioning the guest.

Default: not set

log-type: console:dump/blob|console:dump/url|console:interactive/url|sys.log:dump/url

Log types the guest must support.

Default: not set

password: PASSWORD

Password for login into the guest system.

Default: not set

pool: NAME

Pool to enforce.

Default: not set

port: PORT

Use specific port to connect to.

Default: not set

post-install-script: SCRIPT|URL

If set, the script provided or fetched will be executed.

Default: not set

priority-group: NAME

Provisioning priority group.

Default: default-priority

provision-tick: SECONDS

How often check Artemis API for provisioning status, 60 seconds by default.

Default: 60

provision-timeout: SECONDS

How long to wait for provisioning to complete, 600 seconds by default.

Default: 600

role: ROLE

Marks related guests so that common actions can be applied to all such guests at once.

Default: not set

skip-prepare-verify-ssh: true|false

If set, skip verifiction of SSH connection in prepare state.

Default: false

ssh-option: OPTION

Specify an additional SSH option. Value is passed to SSH’s -o option, see ssh_config(5) for supported options. Can be specified multiple times.

Default: not set

user: USERNAME

Username to use for all guest operations.

Default: root

user-data: KEY=VALUE

Optional data to attach to guest.

Default: not set

watchdog-dispatch-delay: SECONDS

How long (seconds) before the guest “is-alive” watchdog is dispatched. The dispatch timer starts once the guest is successfully provisioned.

Default: not set

watchdog-period-delay: SECONDS

How often (seconds) check that the guest “is-alive”.

Default: not set

virtual.testcloud

Warning

Please, be aware that the documentation below is a work in progress. We are working on fixing it, adding missing bits and generally making it better. Also, it was originally used for command line help only, therefore the formatting is often suboptimal.

Local virtual machine using testcloud library.

Minimal config which uses the latest Fedora image:

provision:
    how: virtual

Here’s a full config example:

provision:
    how: virtual
    image: fedora
    user: root
    memory: 2048

As the image use fedora for the latest released Fedora compose, fedora-rawhide for the latest Rawhide compose, short aliases such as fedora-32, f-32 or f32 for specific release or a full url to the qcow2 image for example from https://kojipkgs.fedoraproject.org/compose/.

Short names are also provided for centos, centos-stream, alma, rocky, oracle, debian and ubuntu (e.g. centos-8 or c8).

Note

The non-rpm distros are not fully supported yet in tmt as the package installation is performed solely using dnf/yum and rpm. But you should be able the login to the provisioned guest and start experimenting. Full support is coming in the future :)

Supported Fedora CoreOS images are:

fedora-coreos
fedora-coreos-stable
fedora-coreos-testing
fedora-coreos-next

Use the full path for images stored on local disk, for example:

/var/tmp/images/Fedora-Cloud-Base-31-1.9.x86_64.qcow2

In addition to the qcow2 format, Vagrant boxes can be used as well, testcloud will take care of unpacking the image for you.

Configuration

See also Common Keys accepted by the plugin.

arch: x86_64|aarch64|s390x|ppc64le

What architecture to virtualize, host arch by default.

Default: x86_64

become: true|false

Whether to run shell scripts in tests, prepare, and finish with sudo.

Default: false

connection: session|system

What session type to use, ‘session’ by default.

Default: session

disk: SIZE

Specify disk size in GB, 10 GB by default.

Default: not set

hardware: KEY=VALUE

Add a hardware requirement.

Default: not set

image: IMAGE

Select image to be used. Provide a short name, full path to a local file or a complete url.

Default: fedora

key: PATH

Private key for login into the guest system.

Default: not set

list-local-images: true|false

List locally available images.

Default: false

memory: SIZE

Set available memory in MB, 2048 MB by default.

Default: not set

password: PASSWORD

Password for login into the guest system.

Default: not set

port: PORT

Use specific port to connect to.

Default: not set

role: ROLE

Marks related guests so that common actions can be applied to all such guests at once.

Default: not set

ssh-option: OPTION

Specify an additional SSH option. Value is passed to SSH’s -o option, see ssh_config(5) for supported options. Can be specified multiple times.

Default: not set

user: USERNAME

Username to use for all guest operations.

Default: root

bootc

Warning

Please, be aware that the documentation below is a work in progress. We are working on fixing it, adding missing bits and generally making it better. Also, it was originally used for command line help only, therefore the formatting is often suboptimal.

Provision a local virtual machine using a bootc container image

Minimal config which uses the CentOS Stream 9 bootc image:

provision:
    how: bootc
    container-image: quay.io/centos-bootc/centos-bootc:stream9
    rootfs: xfs

Here’s a config example using a Containerfile:

provision:
    how: bootc
    container-file: "./my-custom-image.containerfile"
    container-file-workdir: .
    image-builder: quay.io/centos-bootc/bootc-image-builder:stream9
    rootfs: ext4
    disk: 100

Another config example using an image that already includes tmt dependencies:

provision:
    how: bootc
    add-tmt-dependencies: false
    container-image: localhost/my-image-with-deps
    rootfs: btrfs

This plugin is an extension of the virtual.testcloud plugin. Essentially, it takes a container image as input, builds a bootc disk image from the container image, then uses the virtual.testcloud plugin to create a virtual machine using the bootc disk image.

The bootc disk creation requires running podman as root. The plugin will automatically check if the current podman connection is rootless. If it is, a podman machine will be spun up and used to build the bootc disk.

Configuration

See also Common Keys accepted by the plugin.

add-tmt-dependencies: true|false

Add tmt dependencies to the supplied container image or image built from the supplied Containerfile. This will cause a derived image to be built from the supplied image.

Default: true

arch: x86_64|aarch64|s390x|ppc64le

What architecture to virtualize, host arch by default.

Default: x86_64

become: true|false

Whether to run shell scripts in tests, prepare, and finish with sudo.

Default: false

connection: session|system

What session type to use, ‘session’ by default.

Default: session

container-file: CONTAINER_FILE

Select container file to be used to build a container image that is then used by bootc image builder to create a disk image.

Cannot be used with container-image.

Default: not set

container-file-workdir: CONTAINER_FILE_WORKDIR

Select working directory for the podman build invocation.

Default: .

container-image: CONTAINER_IMAGE

Select container image to be used to build a bootc disk. This takes priority over Containerfile.

Default: not set

disk: SIZE

Specify disk size in GB, 10 GB by default.

Default: not set

hardware: KEY=VALUE

Add a hardware requirement.

Default: not set

image: IMAGE

Select image to be used. Provide a short name, full path to a local file or a complete url.

Default: fedora

image-builder: IMAGE_BUILDER

The full repo:tag url of the bootc image builder image to use for building the bootc disk image.

Default: quay.io/centos-bootc/bootc-image-builder:latest

key: PATH

Private key for login into the guest system.

Default: not set

list-local-images: true|false

List locally available images.

Default: false

memory: SIZE

Set available memory in MB, 2048 MB by default.

Default: not set

password: PASSWORD

Password for login into the guest system.

Default: not set

port: PORT

Use specific port to connect to.

Default: not set

role: ROLE

Marks related guests so that common actions can be applied to all such guests at once.

Default: not set

rootfs: ext4|xfs|btrfs

Select root filesystem type. Overrides the default from the source container.

Default: xfs

ssh-option: OPTION

Specify an additional SSH option. Value is passed to SSH’s -o option, see ssh_config(5) for supported options. Can be specified multiple times.

Default: not set

user: USERNAME

Username to use for all guest operations.

Default: root

connect

Warning

Please, be aware that the documentation below is a work in progress. We are working on fixing it, adding missing bits and generally making it better. Also, it was originally used for command line help only, therefore the formatting is often suboptimal.

Connect to a provisioned guest using SSH.

Private key authentication:

provision:
    how: connect
    guest: host.example.org
    user: root
    key: /home/psss/.ssh/example_rsa

Password authentication:

provision:
    how: connect
    guest: host.example.org
    user: root
    password: secret

User defaults to root, so if you have private key correctly set the minimal configuration can look like this:

provision:
    how: connect
    guest: host.example.org

Configuration

See also Common Keys accepted by the plugin.

become: true|false

Whether to run shell scripts in tests, prepare, and finish with sudo.

Default: false

guest: GUEST

Select remote host to connect to (hostname or ip).

Default: not set

hard-reboot: COMMAND

If specified, the command, executed on the runner, would be used for hard reboot of the guest.

Default: not set

hardware: KEY=VALUE

Add a hardware requirement.

Default: not set

key: PATH

Private key for login into the guest system.

Default: not set

password: PASSWORD

Password for login into the guest system.

Default: not set

port: PORT

Use specific port to connect to.

Default: not set

role: ROLE

Marks related guests so that common actions can be applied to all such guests at once.

Default: not set

soft-reboot: COMMAND

If specified, the command, executed on the runner, would be used for soft reboot of the guest.

Default: not set

ssh-option: OPTION

Specify an additional SSH option. Value is passed to SSH’s -o option, see ssh_config(5) for supported options. Can be specified multiple times.

Default: not set

user: USERNAME

Username to use for all guest operations.

Default: root

local

Warning

Please, be aware that the documentation below is a work in progress. We are working on fixing it, adding missing bits and generally making it better. Also, it was originally used for command line help only, therefore the formatting is often suboptimal.

Use local host for test execution.

Warning

In general, it is not recommended to run tests on your local machine as there might be security risks. Run only those tests which you know are safe so that you don’t destroy your laptop ;-)

From tmt version 1.38, the --feeling-safe option or the TMT_FEELING_SAFE=1 environment variable is required in order to use the local provision plugin.

Example config:

provision:
    how: local

Note that tmt run is expected to be executed under a regular user. If there are admin rights required (for example in the prepare step) you might be asked for a sudo password.

Configuration

See also Common Keys accepted by the plugin.

become: true|false

Whether to run shell scripts in tests, prepare, and finish with sudo.

Default: false

hardware: KEY=VALUE

Add a hardware requirement.

Default: not set

role: ROLE

Marks related guests so that common actions can be applied to all such guests at once.

Default: not set

beaker

Warning

Please, be aware that the documentation below is a work in progress. We are working on fixing it, adding missing bits and generally making it better. Also, it was originally used for command line help only, therefore the formatting is often suboptimal.

Provision guest on Beaker system using mrack.

Minimal configuration could look like this:

provision:
    how: beaker
    image: fedora

Configuration

See also Common Keys accepted by the plugin.

api-session-refresh-tick: SECONDS

How often should Beaker session be refreshed to pick up-to-date Kerberos ticket, 3600 seconds by default.

Default: 3600

arch: ARCH

Architecture to provision.

Default: x86_64

beaker-job-group: GROUPNAME

If set, Beaker jobs will be submitted on behalf of GROUPNAME.

Default: not set

beaker-job-owner: USERNAME

If set, Beaker jobs will be submitted on behalf of USERNAME. Submitting user must be a submission delegate for the USERNAME.

Default: not set

become: true|false

Whether to run shell scripts in tests, prepare, and finish with sudo.

Default: false

hardware: KEY=VALUE

Add a hardware requirement.

Default: not set

image: COMPOSE

Image (distro or “compose” in Beaker terminology) to provision.

Default: fedora

key: PATH

Private key for login into the guest system.

Default: not set

kickstart: KEY=VALUE

Optional Beaker kickstart to use when provisioning the guest.

Default: not set

password: PASSWORD

Password for login into the guest system.

Default: not set

port: PORT

Use specific port to connect to.

Default: not set

provision-tick: SECONDS

How often check Beaker for provisioning status, 60 seconds by default.

Default: 60

provision-timeout: SECONDS

How long to wait for provisioning to complete, 3600 seconds by default.

Default: 3600

public-key: PUBKEY

Public keys to add among authorized SSH keys.

Default: not set

role: ROLE

Marks related guests so that common actions can be applied to all such guests at once.

Default: not set

ssh-option: OPTION

Specify an additional SSH option. Value is passed to SSH’s -o option, see ssh_config(5) for supported options. Can be specified multiple times.

Default: not set

user: USERNAME

Username to use for all guest operations.

Default: root

whiteboard: WHITEBOARD

Text description of the beaker job which is displayed in the list of jobs.

Default: not set

container

Warning

Please, be aware that the documentation below is a work in progress. We are working on fixing it, adding missing bits and generally making it better. Also, it was originally used for command line help only, therefore the formatting is often suboptimal.

Create a new container using podman.

Example config:

provision:
    how: container
    image: fedora:latest

In order to always pull the fresh container image use pull: true.

In order to run the container with different user as the default root, use user: USER.

Configuration

See also Common Keys accepted by the plugin.

become: true|false

Whether to run shell scripts in tests, prepare, and finish with sudo.

Default: false

container: NAME

Name or id of an existing container to be used.

Default: not set

force-pull: true|false

Force pulling a fresh container image.

Default: false

hardware: KEY=VALUE

Add a hardware requirement.

Default: not set

image: IMAGE

Select image to use. Short name or complete url.

Default: fedora

pull-attempts: COUNT

How many times to try pulling the image, 5 attempts by default.

Default: 5

pull-interval: SECONDS

How long to wait before a new pull attempt, 5 seconds by default.

Default: 5

role: ROLE

Marks related guests so that common actions can be applied to all such guests at once.

Default: not set

stop-time: SECONDS

How long to wait before forcibly stopping the container, 1 seconds by default.

Default: 1

user: USERNAME

Username to use for all guest operations.

Default: root