Provision Plugins

Describes what environment is needed for testing and how it should be provisioned. There are several provision plugins supporting multiple ways to provision the environment for testing, for example:

virtual.testcloud
container
connect
local
artemis

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
artemis

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`	`mock`	`virtual`
beaker	❌	✅ [1]	❌	❌	❌	❌	❌	❌
boot	✅	❌	❌	❌	❌	❌	❌	❌
compatible	✅	❌	❌	❌	❌	❌	❌	❌
cpu	✅ [2]	✅ [3]	❌	❌	❌	❌	❌	✅ [4]
device	❌	✅ [5]	❌	❌	❌	❌	❌	❌
disk	✅ [6]	✅ [7]	❌	❌	❌	❌	❌	✅ [8]
gpu	❌	❌	❌	❌	❌	❌	❌	❌
hostname	✅	✅	❌	❌	❌	❌	❌	❌
iommu	❌	✅ [9]	❌	❌	❌	❌	❌	❌
location	❌	✅ [10]	❌	❌	❌	❌	❌	❌
memory	✅	✅	❌	❌	❌	❌	❌	✅ [11]
network	✅ [12]	❌	❌	❌	❌	❌	❌	❌
system	❌	✅ [13]	❌	❌	❌	❌	❌	❌
tpm	✅	✅	❌	❌	❌	❌	❌	✅ [14]
virtualization	✅	✅ [15]	❌	❌	❌	❌	❌	❌
zcrypt	✅	✅	❌	❌	❌	❌	❌	❌

SSH options

When communicating with guests over SSH, tmt adds several SSH options by default to relevant commands:

# Try establishing connection multiple times before giving up.
ConnectionAttempts=5
ConnectTimeout=60

# Prevent SSH from disconnecting if no data has been
# received from the server for a long time.
ServerAliveInterval=5
ServerAliveCountMax=60

Additional SSH options can be specified either via ssh-option key of respective plugins, or by setting TMT_SSH_* environment variables; see Command Variables for details.

Common Keys

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

name

The name of the step phase.

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_NAME

In plan metadata:

name:

On command-line:

--name ...
export TMT_PLUGIN_PROVISION_ARTEMIS_NAME=...

order

Order in which the phase should be handled.

Default: 50

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_ORDER

In plan metadata:

order:

On command-line:

--order ...
export TMT_PLUGIN_PROVISION_ARTEMIS_ORDER=...

summary

Concise summary describing purpose of the phase.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_SUMMARY

In plan metadata:

summary:

On command-line:

--summary ...
export TMT_PLUGIN_PROVISION_ARTEMIS_SUMMARY=...

when

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

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_WHEN

In plan metadata:

when: RULE

On command-line:

--when RULE
export TMT_PLUGIN_PROVISION_ARTEMIS_WHEN=RULE

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.

Reserve a machine using the Artemis service. Users can specify many requirements, mostly regarding the desired OS, RAM, disk size and more. Most of the HW specifications defined in the Hardware are supported. Including the kickstart.

Artemis takes machines from AWS, OpenStack, Beaker or Azure. By default, Artemis handles the selection of a cloud provider to its best abilities and the required specification. However, it is possible to specify the keyword pool and select the desired cloud provider.

Artemis project: https://gitlab.com/testing-farm/artemis

Minimal configuration could look like this:

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

Note

When used together with the Testing Farm infrastructure some of the options from the first example below will be filled for you by the Testing Farm service.

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.

ansible

Ansible configuration for individual guest inventory generation.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_ANSIBLE

In plan metadata:

ansible:

On command-line:

--ansible ...
export TMT_PLUGIN_PROVISION_ARTEMIS_ANSIBLE=...

api-retries

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

Default: 10

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_API_RETRIES

In plan metadata:

api-retries: COUNT

On command-line:

--api-retries COUNT
export TMT_PLUGIN_PROVISION_ARTEMIS_API_RETRIES=COUNT

api-retry-backoff-factor

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

Default: 1

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_API_RETRY_BACKOFF_FACTOR

In plan metadata:

api-retry-backoff-factor: COUNT

On command-line:

--api-retry-backoff-factor COUNT
export TMT_PLUGIN_PROVISION_ARTEMIS_API_RETRY_BACKOFF_FACTOR=COUNT

api-timeout

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

Default: 10

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_API_TIMEOUT

In plan metadata:

api-timeout: SECONDS

On command-line:

--api-timeout SECONDS
export TMT_PLUGIN_PROVISION_ARTEMIS_API_TIMEOUT=SECONDS

api-url

Artemis API URL.

Default: http://127.0.0.1:8001

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_API_URL

In plan metadata:

api-url: URL

On command-line:

--api-url URL
export TMT_PLUGIN_PROVISION_ARTEMIS_API_URL=URL

api-version

Artemis API version to use.

Default: 0.0.74

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_API_VERSION

In plan metadata:

api-version: X.Y.Z

On command-line:

--api-version X.Y.Z
export TMT_PLUGIN_PROVISION_ARTEMIS_API_VERSION=X.Y.Z

arch

Architecture to provision.

Default: x86_64

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_ARCH

In plan metadata:

arch: ARCH

On command-line:

--arch ARCH
export TMT_PLUGIN_PROVISION_ARTEMIS_ARCH=ARCH

become

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

Default: false

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_BECOME

In plan metadata:

become: true|false

On command-line:

--become
export TMT_PLUGIN_PROVISION_ARTEMIS_BECOME=1|0

environment

Environment variables to be defined for this guest. These will be available during test execution and can be used to customize behavior on a per-guest basis. Note that variables defined here can be overridden by test-level environment variables.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_ENVIRONMENT

In plan metadata:

environment: KEY=VALUE

On command-line:

--environment KEY=VALUE
export TMT_PLUGIN_PROVISION_ARTEMIS_ENVIRONMENT=KEY=VALUE

hardware

Hardware requirements the provisioned guest must satisfy.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_HARDWARE

In plan metadata:

hardware: KEY=VALUE

On command-line:

--hardware KEY=VALUE
export TMT_PLUGIN_PROVISION_ARTEMIS_HARDWARE=KEY=VALUE

image

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

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_IMAGE

In plan metadata:

image: COMPOSE

On command-line:

--image COMPOSE
export TMT_PLUGIN_PROVISION_ARTEMIS_IMAGE=COMPOSE

key

Private key to use as SSH identity for key-based authentication.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_KEY

In plan metadata:

key: PATH

On command-line:

--key PATH
export TMT_PLUGIN_PROVISION_ARTEMIS_KEY=PATH

keyname

SSH key name.

Default: master-key

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_KEYNAME

In plan metadata:

keyname: NAME

On command-line:

--keyname NAME
export TMT_PLUGIN_PROVISION_ARTEMIS_KEYNAME=NAME

kickstart

Optional Beaker kickstart to use when provisioning the guest.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_KICKSTART

In plan metadata:

kickstart: KEY=VALUE

On command-line:

--kickstart KEY=VALUE
export TMT_PLUGIN_PROVISION_ARTEMIS_KICKSTART=KEY=VALUE

log-type

Log types the guest must support.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_LOG_TYPE

In plan metadata:

log-type: console:dump/blob|console:dump/url|console:interactive/url|sys.log:dump/url|flasher-debug:dump/url|flasher-debug:dump/blob|flasher-event:dump/url|flasher-event:dump/blob|anaconda.log:dump/blob|storage.log:dump/blob|program.log:dump/blob|packaging.log:dump/blob|ks.cfg:dump/blob

On command-line:

--log-type 'console:dump/blob|console:dump/url|console:interactive/url|sys.log:dump/url|flasher-debug:dump/url|flasher-debug:dump/blob|flasher-event:dump/url|flasher-event:dump/blob|anaconda.log:dump/blob|storage.log:dump/blob|program.log:dump/blob|packaging.log:dump/blob|ks.cfg:dump/blob'
export TMT_PLUGIN_PROVISION_ARTEMIS_LOG_TYPE='console:dump/blob|console:dump/url|console:interactive/url|sys.log:dump/url|flasher-debug:dump/url|flasher-debug:dump/blob|flasher-event:dump/url|flasher-event:dump/blob|anaconda.log:dump/blob|storage.log:dump/blob|program.log:dump/blob|packaging.log:dump/blob|ks.cfg:dump/blob'

password

Password to use for password-based authentication.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_PASSWORD

In plan metadata:

password: PASSWORD

On command-line:

--password PASSWORD
export TMT_PLUGIN_PROVISION_ARTEMIS_PASSWORD=PASSWORD

pool

Pool to enforce.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_POOL

In plan metadata:

pool: NAME

On command-line:

--pool NAME
export TMT_PLUGIN_PROVISION_ARTEMIS_POOL=NAME

port

Port to use for SSH connections instead of the default one.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_PORT

In plan metadata:

port: PORT

On command-line:

--port PORT
export TMT_PLUGIN_PROVISION_ARTEMIS_PORT=PORT

post-install-script

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

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_POST_INSTALL_SCRIPT

In plan metadata:

post-install-script: SCRIPT|URL

On command-line:

--post-install-script 'SCRIPT|URL'
export TMT_PLUGIN_PROVISION_ARTEMIS_POST_INSTALL_SCRIPT='SCRIPT|URL'

priority-group

Provisioning priority group.

Default: default-priority

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_PRIORITY_GROUP

In plan metadata:

priority-group: NAME

On command-line:

--priority-group NAME
export TMT_PLUGIN_PROVISION_ARTEMIS_PRIORITY_GROUP=NAME

provision-tick

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

Default: 60

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_PROVISION_TICK

In plan metadata:

provision-tick: SECONDS

On command-line:

--provision-tick SECONDS
export TMT_PLUGIN_PROVISION_ARTEMIS_PROVISION_TICK=SECONDS

provision-timeout

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

Default: 600

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_PROVISION_TIMEOUT

In plan metadata:

provision-timeout: SECONDS

On command-line:

--provision-timeout SECONDS
export TMT_PLUGIN_PROVISION_ARTEMIS_PROVISION_TIMEOUT=SECONDS

role

Marks guests with the same purpose so that common actions can be applied to all such guests at once.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_ROLE

In plan metadata:

role: NAME

On command-line:

--role NAME
export TMT_PLUGIN_PROVISION_ARTEMIS_ROLE=NAME

skip-prepare-verify-ssh

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

Default: false

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_SKIP_PREPARE_VERIFY_SSH

In plan metadata:

skip-prepare-verify-ssh: true|false

On command-line:

--skip-prepare-verify-ssh
export TMT_PLUGIN_PROVISION_ARTEMIS_SKIP_PREPARE_VERIFY_SSH=1|0

ssh-option

Additional SSH option. Value is passed to the -o option of ssh, see ssh_config(5) for supported options. Can be specified multiple times.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_SSH_OPTION

In plan metadata:

ssh-option: OPTION

On command-line:

--ssh-option OPTION
export TMT_PLUGIN_PROVISION_ARTEMIS_SSH_OPTION=OPTION

user

A username to use for all guest operations.

Default: root

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_USER

In plan metadata:

user: NAME

On command-line:

--user NAME
export TMT_PLUGIN_PROVISION_ARTEMIS_USER=NAME

user-data

Optional data to attach to guest.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_USER_DATA

In plan metadata:

user-data: KEY=VALUE

On command-line:

--user-data KEY=VALUE
export TMT_PLUGIN_PROVISION_ARTEMIS_USER_DATA=KEY=VALUE

watchdog-dispatch-delay

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

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_WATCHDOG_DISPATCH_DELAY

In plan metadata:

watchdog-dispatch-delay: SECONDS

On command-line:

--watchdog-dispatch-delay SECONDS
export TMT_PLUGIN_PROVISION_ARTEMIS_WATCHDOG_DISPATCH_DELAY=SECONDS

watchdog-period-delay

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

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_ARTEMIS_WATCHDOG_PERIOD_DELAY

In plan metadata:

watchdog-period-delay: SECONDS

On command-line:

--watchdog-period-delay SECONDS
export TMT_PLUGIN_PROVISION_ARTEMIS_WATCHDOG_PERIOD_DELAY=SECONDS

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.

Reserve a machine from the Beaker pool using the mrack plugin. mrack is a multicloud provisioning library supporting multiple cloud services including Beaker.

The following two files are used for configuration:

/etc/tmt/mrack.conf for basic configuration

/etc/tmt/provisioning-config.yaml configuration per supported provider

Beaker installs distribution specified by the image key. If the image can not be translated using the provisioning-config.yaml file mrack passes the image value to Beaker hub and tries to request distribution based on the image value. This way we can bypass default translations and use desired distribution specified like the one in the example below.

Minimal configuration could look like this:

provision:
    how: beaker
    image: fedora

To trigger a hard reboot of a guest, bkr system-power --action reboot command is executed.

Warning

bkr system-power command is executed on the runner, not on the guest.

# Specify the distro directly
provision:
    how: beaker
    image: Fedora-37%

# Set custom whiteboard description (added in 1.30)
provision:
    how: beaker
    whiteboard: Just a smoke test for now

Configuration

See also Common Keys accepted by the plugin.

ansible

Ansible configuration for individual guest inventory generation.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_ANSIBLE

In plan metadata:

ansible:

On command-line:

--ansible ...
export TMT_PLUGIN_PROVISION_BEAKER_ANSIBLE=...

api-session-refresh-tick

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

Default: 3600

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_API_SESSION_REFRESH_TICK

In plan metadata:

api-session-refresh-tick: SECONDS

On command-line:

--api-session-refresh-tick SECONDS
export TMT_PLUGIN_PROVISION_BEAKER_API_SESSION_REFRESH_TICK=SECONDS

arch

Architecture to provision.

Default: x86_64

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_ARCH

In plan metadata:

arch: ARCH

On command-line:

--arch ARCH
export TMT_PLUGIN_PROVISION_BEAKER_ARCH=ARCH

beaker-job-group

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

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_BEAKER_JOB_GROUP

In plan metadata:

beaker-job-group: GROUPNAME

On command-line:

--beaker-job-group GROUPNAME
export TMT_PLUGIN_PROVISION_BEAKER_BEAKER_JOB_GROUP=GROUPNAME

beaker-job-owner

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

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_BEAKER_JOB_OWNER

In plan metadata:

beaker-job-owner: USERNAME

On command-line:

--beaker-job-owner USERNAME
export TMT_PLUGIN_PROVISION_BEAKER_BEAKER_JOB_OWNER=USERNAME

become

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

Default: false

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_BECOME

In plan metadata:

become: true|false

On command-line:

--become
export TMT_PLUGIN_PROVISION_BEAKER_BECOME=1|0

bootc

If set, bootc on Beaker installation will be performed.

Default: false

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_BOOTC

In plan metadata:

bootc: true|false

On command-line:

--bootc
export TMT_PLUGIN_PROVISION_BEAKER_BOOTC=1|0

bootc-check-system-url

URL to check-system task, which is needed for bootc on Beaker installation.

Default: https://gitlab.com/fedora/bootc/tests/bootc-beaker-test/-/archive/1.8/bootc-beaker-test-1.8.tar.gz#check-system

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_BOOTC_CHECK_SYSTEM_URL

In plan metadata:

bootc-check-system-url: URL

On command-line:

--bootc-check-system-url URL
export TMT_PLUGIN_PROVISION_BEAKER_BOOTC_CHECK_SYSTEM_URL=URL

bootc-image-url

Select bootc image to be used to perform the installation.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_BOOTC_IMAGE_URL

In plan metadata:

bootc-image-url: URL

On command-line:

--bootc-image-url URL
export TMT_PLUGIN_PROVISION_BEAKER_BOOTC_IMAGE_URL=URL

bootc-registry-secret

Specify bootc secret, which will be used for fetching from registry.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_BOOTC_REGISTRY_SECRET

In plan metadata:

bootc-registry-secret: SECRET

On command-line:

--bootc-registry-secret SECRET
export TMT_PLUGIN_PROVISION_BEAKER_BOOTC_REGISTRY_SECRET=SECRET

environment

Environment variables to be defined for this guest. These will be available during test execution and can be used to customize behavior on a per-guest basis. Note that variables defined here can be overridden by test-level environment variables.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_ENVIRONMENT

In plan metadata:

environment: KEY=VALUE

On command-line:

--environment KEY=VALUE
export TMT_PLUGIN_PROVISION_BEAKER_ENVIRONMENT=KEY=VALUE

hardware

Hardware requirements the provisioned guest must satisfy.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_HARDWARE

In plan metadata:

hardware: KEY=VALUE

On command-line:

--hardware KEY=VALUE
export TMT_PLUGIN_PROVISION_BEAKER_HARDWARE=KEY=VALUE

image

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

Default: fedora

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_IMAGE

In plan metadata:

image: COMPOSE

On command-line:

--image COMPOSE
export TMT_PLUGIN_PROVISION_BEAKER_IMAGE=COMPOSE

key

Private key to use as SSH identity for key-based authentication.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_KEY

In plan metadata:

key: PATH

On command-line:

--key PATH
export TMT_PLUGIN_PROVISION_BEAKER_KEY=PATH

kickstart

Optional Beaker kickstart to use when provisioning the guest.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_KICKSTART

In plan metadata:

kickstart: KEY=VALUE

On command-line:

--kickstart KEY=VALUE
export TMT_PLUGIN_PROVISION_BEAKER_KICKSTART=KEY=VALUE

password

Password to use for password-based authentication.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_PASSWORD

In plan metadata:

password: PASSWORD

On command-line:

--password PASSWORD
export TMT_PLUGIN_PROVISION_BEAKER_PASSWORD=PASSWORD

port

Port to use for SSH connections instead of the default one.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_PORT

In plan metadata:

port: PORT

On command-line:

--port PORT
export TMT_PLUGIN_PROVISION_BEAKER_PORT=PORT

provision-tick

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

Default: 60

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_PROVISION_TICK

In plan metadata:

provision-tick: SECONDS

On command-line:

--provision-tick SECONDS
export TMT_PLUGIN_PROVISION_BEAKER_PROVISION_TICK=SECONDS

provision-timeout

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

Default: 3600

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_PROVISION_TIMEOUT

In plan metadata:

provision-timeout: SECONDS

On command-line:

--provision-timeout SECONDS
export TMT_PLUGIN_PROVISION_BEAKER_PROVISION_TIMEOUT=SECONDS

public-key

Public keys to add among authorized SSH keys.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_PUBLIC_KEY

In plan metadata:

public-key: PUBKEY

On command-line:

--public-key PUBKEY
export TMT_PLUGIN_PROVISION_BEAKER_PUBLIC_KEY=PUBKEY

role

Marks guests with the same purpose so that common actions can be applied to all such guests at once.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_ROLE

In plan metadata:

role: NAME

On command-line:

--role NAME
export TMT_PLUGIN_PROVISION_BEAKER_ROLE=NAME

ssh-option

Additional SSH option. Value is passed to the -o option of ssh, see ssh_config(5) for supported options. Can be specified multiple times.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_SSH_OPTION

In plan metadata:

ssh-option: OPTION

On command-line:

--ssh-option OPTION
export TMT_PLUGIN_PROVISION_BEAKER_SSH_OPTION=OPTION

user

A username to use for all guest operations.

Default: root

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_USER

In plan metadata:

user: NAME

On command-line:

--user NAME
export TMT_PLUGIN_PROVISION_BEAKER_USER=NAME

whiteboard

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

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BEAKER_WHITEBOARD

In plan metadata:

whiteboard: WHITEBOARD

On command-line:

--whiteboard WHITEBOARD
export TMT_PLUGIN_PROVISION_BEAKER_WHITEBOARD=WHITEBOARD

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.

To trigger hard reboot of a guest, plugin uses testcloud API. It is also used to trigger soft reboot unless a custom reboot command was specified via tmt-reboot -c ....

Configuration

See also Common Keys accepted by the plugin.

add-tmt-dependencies

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

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_ADD_TMT_DEPENDENCIES

In plan metadata:

add-tmt-dependencies: true|false

On command-line:

--add-tmt-dependencies
export TMT_PLUGIN_PROVISION_BOOTC_ADD_TMT_DEPENDENCIES=1|0

ansible

Ansible configuration for individual guest inventory generation.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_ANSIBLE

In plan metadata:

ansible:

On command-line:

--ansible ...
export TMT_PLUGIN_PROVISION_BOOTC_ANSIBLE=...

arch

What architecture to virtualize, host arch by default.

Default: x86_64

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_ARCH

In plan metadata:

arch: x86_64|aarch64|s390x|ppc64le

On command-line:

--arch 'x86_64|aarch64|s390x|ppc64le'
export TMT_PLUGIN_PROVISION_BOOTC_ARCH='x86_64|aarch64|s390x|ppc64le'

become

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

Default: false

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_BECOME

In plan metadata:

become: true|false

On command-line:

--become
export TMT_PLUGIN_PROVISION_BOOTC_BECOME=1|0

build-disk-image-only

Only build a bootc disk image from a container image and quit. Guest VM will not start.

Default: false

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_BUILD_DISK_IMAGE_ONLY

In plan metadata:

build-disk-image-only: true|false

On command-line:

--build-disk-image-only
export TMT_PLUGIN_PROVISION_BOOTC_BUILD_DISK_IMAGE_ONLY=1|0

connection

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

Default: session

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_CONNECTION

In plan metadata:

connection: session|system

On command-line:

--connection 'session|system'
export TMT_PLUGIN_PROVISION_BOOTC_CONNECTION='session|system'

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

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_CONTAINER_FILE

In plan metadata:

container-file: CONTAINER_FILE

On command-line:

--container-file CONTAINER_FILE
export TMT_PLUGIN_PROVISION_BOOTC_CONTAINER_FILE=CONTAINER_FILE

container-file-workdir

Select working directory for the podman build invocation.

Default: .

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_CONTAINER_FILE_WORKDIR

In plan metadata:

container-file-workdir: CONTAINER_FILE_WORKDIR

On command-line:

--container-file-workdir CONTAINER_FILE_WORKDIR
export TMT_PLUGIN_PROVISION_BOOTC_CONTAINER_FILE_WORKDIR=CONTAINER_FILE_WORKDIR

container-image

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

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_CONTAINER_IMAGE

In plan metadata:

container-image: CONTAINER_IMAGE

On command-line:

--container-image CONTAINER_IMAGE
export TMT_PLUGIN_PROVISION_BOOTC_CONTAINER_IMAGE=CONTAINER_IMAGE

disk

Specify disk size in GB, 10 GB by default.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_DISK

In plan metadata:

disk: SIZE

On command-line:

--disk SIZE
export TMT_PLUGIN_PROVISION_BOOTC_DISK=SIZE

environment

Environment variables to be defined for this guest. These will be available during test execution and can be used to customize behavior on a per-guest basis. Note that variables defined here can be overridden by test-level environment variables.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_ENVIRONMENT

In plan metadata:

environment: KEY=VALUE

On command-line:

--environment KEY=VALUE
export TMT_PLUGIN_PROVISION_BOOTC_ENVIRONMENT=KEY=VALUE

hardware

Hardware requirements the provisioned guest must satisfy.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_HARDWARE

In plan metadata:

hardware: KEY=VALUE

On command-line:

--hardware KEY=VALUE
export TMT_PLUGIN_PROVISION_BOOTC_HARDWARE=KEY=VALUE

image

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

Default: fedora

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_IMAGE

In plan metadata:

image: IMAGE

On command-line:

--image IMAGE
export TMT_PLUGIN_PROVISION_BOOTC_IMAGE=IMAGE

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

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_IMAGE_BUILDER

In plan metadata:

image-builder: IMAGE_BUILDER

On command-line:

--image-builder IMAGE_BUILDER
export TMT_PLUGIN_PROVISION_BOOTC_IMAGE_BUILDER=IMAGE_BUILDER

key

Private key to use as SSH identity for key-based authentication.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_KEY

In plan metadata:

key: PATH

On command-line:

--key PATH
export TMT_PLUGIN_PROVISION_BOOTC_KEY=PATH

list-local-images

List locally available images.

Default: false

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_LIST_LOCAL_IMAGES

In plan metadata:

list-local-images: true|false

On command-line:

--list-local-images
export TMT_PLUGIN_PROVISION_BOOTC_LIST_LOCAL_IMAGES=1|0

memory

Set available memory in MB, 2048 MB by default.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_MEMORY

In plan metadata:

memory: SIZE

On command-line:

--memory SIZE
export TMT_PLUGIN_PROVISION_BOOTC_MEMORY=SIZE

password

Password to use for password-based authentication.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_PASSWORD

In plan metadata:

password: PASSWORD

On command-line:

--password PASSWORD
export TMT_PLUGIN_PROVISION_BOOTC_PASSWORD=PASSWORD

port

Port to use for SSH connections instead of the default one.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_PORT

In plan metadata:

port: PORT

On command-line:

--port PORT
export TMT_PLUGIN_PROVISION_BOOTC_PORT=PORT

role

Marks guests with the same purpose so that common actions can be applied to all such guests at once.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_ROLE

In plan metadata:

role: NAME

On command-line:

--role NAME
export TMT_PLUGIN_PROVISION_BOOTC_ROLE=NAME

rootfs

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

Default: xfs

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_ROOTFS

In plan metadata:

rootfs: ext4|xfs|btrfs

On command-line:

--rootfs 'ext4|xfs|btrfs'
export TMT_PLUGIN_PROVISION_BOOTC_ROOTFS='ext4|xfs|btrfs'

ssh-option

Additional SSH option. Value is passed to the -o option of ssh, see ssh_config(5) for supported options. Can be specified multiple times.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_SSH_OPTION

In plan metadata:

ssh-option: OPTION

On command-line:

--ssh-option OPTION
export TMT_PLUGIN_PROVISION_BOOTC_SSH_OPTION=OPTION

stop-retries

Number of attempts to stop a VM.

Default: 10

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_STOP_RETRIES

In plan metadata:

stop-retries: N

On command-line:

--stop-retries N
export TMT_PLUGIN_PROVISION_BOOTC_STOP_RETRIES=N

stop-retry-delay

Time to wait between attempts to stop a VM.

Default: 1

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_STOP_RETRY_DELAY

In plan metadata:

stop-retry-delay: SECONDS

On command-line:

--stop-retry-delay SECONDS
export TMT_PLUGIN_PROVISION_BOOTC_STOP_RETRY_DELAY=SECONDS

user

A username to use for all guest operations.

Default: root

Environment variable: TMT_PLUGIN_PROVISION_BOOTC_USER

In plan metadata:

user: NAME

On command-line:

--user NAME
export TMT_PLUGIN_PROVISION_BOOTC_USER=NAME

connect

Connect to a provisioned guest using SSH.

Do not provision any system, tests will be executed directly on the machine that has been already provisioned. Use provided authentication information to connect to it over SSH.

Private key authentication (using sudo to run scripts):

provision:
    how: connect
    guest: host.example.org
    user: fedora
    become: true
    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

To support hard reboot of a guest, hard-reboot must be set to an executable command or script. Without this key set, hard reboot will remain unsupported and result in an error. In comparison, soft-reboot and systemd-soft-reboot are optional, but if set, the given commands will be preferred over the default soft and systemd soft-reboot commands:

provision:
  how: connect
  hard-reboot: virsh reboot my-example-vm
  systemd-soft-reboot: ssh root@my-example-vm 'systemd soft-reboot'
  soft-reboot: ssh root@my-example-vm 'shutdown -r now'

provision --how connect \
          --hard-reboot="virsh reboot my-example-vm" \
          --systemd-soft-reboot="ssh root@my-example-vm 'systemd soft-reboot'"
          --soft-reboot="ssh root@my-example-vm 'shutdown -r now'"

Warning

hard-reboot, systemd-soft-reboot, and soft-reboot commands are executed on the runner, not on the guest.

Configuration

See also Common Keys accepted by the plugin.

ansible

Ansible configuration for individual guest inventory generation.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_CONNECT_ANSIBLE

In plan metadata:

ansible:

On command-line:

--ansible ...
export TMT_PLUGIN_PROVISION_CONNECT_ANSIBLE=...

become

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

Default: false

Environment variable: TMT_PLUGIN_PROVISION_CONNECT_BECOME

In plan metadata:

become: true|false

On command-line:

--become
export TMT_PLUGIN_PROVISION_CONNECT_BECOME=1|0

environment

Environment variables to be defined for this guest. These will be available during test execution and can be used to customize behavior on a per-guest basis. Note that variables defined here can be overridden by test-level environment variables.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_CONNECT_ENVIRONMENT

In plan metadata:

environment: KEY=VALUE

On command-line:

--environment KEY=VALUE
export TMT_PLUGIN_PROVISION_CONNECT_ENVIRONMENT=KEY=VALUE

guest

A preexisting machine to connect to.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_CONNECT_GUEST

In plan metadata:

guest: HOSTNAME|IP

On command-line:

--guest 'HOSTNAME|IP'
export TMT_PLUGIN_PROVISION_CONNECT_GUEST='HOSTNAME|IP'

hard-reboot

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

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_CONNECT_HARD_REBOOT

In plan metadata:

hard-reboot: COMMAND

On command-line:

--hard-reboot COMMAND
export TMT_PLUGIN_PROVISION_CONNECT_HARD_REBOOT=COMMAND

hardware

Hardware requirements the provisioned guest must satisfy.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_CONNECT_HARDWARE

In plan metadata:

hardware: KEY=VALUE

On command-line:

--hardware KEY=VALUE
export TMT_PLUGIN_PROVISION_CONNECT_HARDWARE=KEY=VALUE

key

Private key to use as SSH identity for key-based authentication.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_CONNECT_KEY

In plan metadata:

key: PATH

On command-line:

--key PATH
export TMT_PLUGIN_PROVISION_CONNECT_KEY=PATH

password

Password to use for password-based authentication.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_CONNECT_PASSWORD

In plan metadata:

password: PASSWORD

On command-line:

--password PASSWORD
export TMT_PLUGIN_PROVISION_CONNECT_PASSWORD=PASSWORD

port

Port to use for SSH connections instead of the default one.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_CONNECT_PORT

In plan metadata:

port: PORT

On command-line:

--port PORT
export TMT_PLUGIN_PROVISION_CONNECT_PORT=PORT

role

Marks guests with the same purpose so that common actions can be applied to all such guests at once.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_CONNECT_ROLE

In plan metadata:

role: NAME

On command-line:

--role NAME
export TMT_PLUGIN_PROVISION_CONNECT_ROLE=NAME

soft-reboot

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

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_CONNECT_SOFT_REBOOT

In plan metadata:

soft-reboot: COMMAND

On command-line:

--soft-reboot COMMAND
export TMT_PLUGIN_PROVISION_CONNECT_SOFT_REBOOT=COMMAND

ssh-option

Additional SSH option. Value is passed to the -o option of ssh, see ssh_config(5) for supported options. Can be specified multiple times.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_CONNECT_SSH_OPTION

In plan metadata:

ssh-option: OPTION

On command-line:

--ssh-option OPTION
export TMT_PLUGIN_PROVISION_CONNECT_SSH_OPTION=OPTION

systemd-soft-reboot

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

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_CONNECT_SYSTEMD_SOFT_REBOOT

In plan metadata:

systemd-soft-reboot: COMMAND

On command-line:

--systemd-soft-reboot COMMAND
export TMT_PLUGIN_PROVISION_CONNECT_SYSTEMD_SOFT_REBOOT=COMMAND

user

A username to use for all guest operations.

Default: root

Environment variable: TMT_PLUGIN_PROVISION_CONNECT_USER

In plan metadata:

user: NAME

On command-line:

--user NAME
export TMT_PLUGIN_PROVISION_CONNECT_USER=NAME

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

# Use an image with a non-root user with sudo privileges,
# and run scripts with sudo.
provision:
    how: container
    image: image with non-root user with sudo privileges
    user: tester
    become: true

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.

Container-backed guests do not support soft reboots or custom reboot commands. Soft reboot or tmt-reboot -c ... will result in an error.

Note

Make sure podman is installed and configured, it is required for container-backed guests provided by provision/container plugin.

To quickly test podman functionality, you can try running podman images or podman run --rm -it fedora:latest.

Users who installed tmt from system repositories should install tmt+provision-container package.
Users who installed tmt from PyPI should also install tmt+provision-container package, as it will install required system dependencies. After doing so, they should install tmt[provision-container] extra.

Configuration

See also Common Keys accepted by the plugin.

ansible

Ansible configuration for individual guest inventory generation.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_CONTAINER_ANSIBLE

In plan metadata:

ansible:

On command-line:

--ansible ...
export TMT_PLUGIN_PROVISION_CONTAINER_ANSIBLE=...

become

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

Default: false

Environment variable: TMT_PLUGIN_PROVISION_CONTAINER_BECOME

In plan metadata:

become: true|false

On command-line:

--become
export TMT_PLUGIN_PROVISION_CONTAINER_BECOME=1|0

container

Name or id of an existing container to be used.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_CONTAINER_CONTAINER

In plan metadata:

container: NAME

On command-line:

--container NAME
export TMT_PLUGIN_PROVISION_CONTAINER_CONTAINER=NAME

environment

Environment variables to be defined for this guest. These will be available during test execution and can be used to customize behavior on a per-guest basis. Note that variables defined here can be overridden by test-level environment variables.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_CONTAINER_ENVIRONMENT

In plan metadata:

environment: KEY=VALUE

On command-line:

--environment KEY=VALUE
export TMT_PLUGIN_PROVISION_CONTAINER_ENVIRONMENT=KEY=VALUE

force-pull

Force pulling a fresh container image.

Default: false

Environment variable: TMT_PLUGIN_PROVISION_CONTAINER_FORCE_PULL

In plan metadata:

force-pull: true|false

On command-line:

--force-pull
export TMT_PLUGIN_PROVISION_CONTAINER_FORCE_PULL=1|0

hardware

Hardware requirements the provisioned guest must satisfy.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_CONTAINER_HARDWARE

In plan metadata:

hardware: KEY=VALUE

On command-line:

--hardware KEY=VALUE
export TMT_PLUGIN_PROVISION_CONTAINER_HARDWARE=KEY=VALUE

image

Select image to use. Short name or complete url.

Default: fedora

Environment variable: TMT_PLUGIN_PROVISION_CONTAINER_IMAGE

In plan metadata:

image: IMAGE

On command-line:

--image IMAGE
export TMT_PLUGIN_PROVISION_CONTAINER_IMAGE=IMAGE

pull-attempts

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

Default: 5

Environment variable: TMT_PLUGIN_PROVISION_CONTAINER_PULL_ATTEMPTS

In plan metadata:

pull-attempts: COUNT

On command-line:

--pull-attempts COUNT
export TMT_PLUGIN_PROVISION_CONTAINER_PULL_ATTEMPTS=COUNT

pull-interval

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

Default: 5

Environment variable: TMT_PLUGIN_PROVISION_CONTAINER_PULL_INTERVAL

In plan metadata:

pull-interval: SECONDS

On command-line:

--pull-interval SECONDS
export TMT_PLUGIN_PROVISION_CONTAINER_PULL_INTERVAL=SECONDS

role

Marks guests with the same purpose so that common actions can be applied to all such guests at once.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_CONTAINER_ROLE

In plan metadata:

role: NAME

On command-line:

--role NAME
export TMT_PLUGIN_PROVISION_CONTAINER_ROLE=NAME

stop-time

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

Default: 1

Environment variable: TMT_PLUGIN_PROVISION_CONTAINER_STOP_TIME

In plan metadata:

stop-time: SECONDS

On command-line:

--stop-time SECONDS
export TMT_PLUGIN_PROVISION_CONTAINER_STOP_TIME=SECONDS

user

Username to use for all guest operations.

Default: root

Environment variable: TMT_PLUGIN_PROVISION_CONTAINER_USER

In plan metadata:

user: USERNAME

On command-line:

--user USERNAME
export TMT_PLUGIN_PROVISION_CONTAINER_USER=USERNAME

local

Use the localhost for the test execution.

Do not provision any system, tests will be executed directly on the localhost.

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 workstation ;-)

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.

Using the plugin:

provision:
    how: local

provision --how local

Note

tmt run is expected to be executed under a non-privileged user account. For some actions on the localhost, e.g. installation of test requirements, local will require elevated privileges, either by running under root account, or by using sudo to run the sensitive commands. You may be asked for a password in such cases.

Note

Neither hard nor soft reboot is supported.

Note

Currently the TMT_SCRIPTS_DIR variable is not supported in the local provision plugin and the default scripts path is used instead. See issue #4081 for details.

Configuration

See also Common Keys accepted by the plugin.

ansible

Ansible configuration for individual guest inventory generation.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_LOCAL_ANSIBLE

In plan metadata:

ansible:

On command-line:

--ansible ...
export TMT_PLUGIN_PROVISION_LOCAL_ANSIBLE=...

become

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

Default: false

Environment variable: TMT_PLUGIN_PROVISION_LOCAL_BECOME

In plan metadata:

become: true|false

On command-line:

--become
export TMT_PLUGIN_PROVISION_LOCAL_BECOME=1|0

environment

Environment variables to be defined for this guest. These will be available during test execution and can be used to customize behavior on a per-guest basis. Note that variables defined here can be overridden by test-level environment variables.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_LOCAL_ENVIRONMENT

In plan metadata:

environment: KEY=VALUE

On command-line:

--environment KEY=VALUE
export TMT_PLUGIN_PROVISION_LOCAL_ENVIRONMENT=KEY=VALUE

hardware

Hardware requirements the provisioned guest must satisfy.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_LOCAL_HARDWARE

In plan metadata:

hardware: KEY=VALUE

On command-line:

--hardware KEY=VALUE
export TMT_PLUGIN_PROVISION_LOCAL_HARDWARE=KEY=VALUE

role

Marks guests with the same purpose so that common actions can be applied to all such guests at once.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_LOCAL_ROLE

In plan metadata:

role: NAME

On command-line:

--role NAME
export TMT_PLUGIN_PROVISION_LOCAL_ROLE=NAME

mock

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 the mock tool for the test execution.

Tests will be executed inside a mock buildroot.

Warning

This plugin requires the --feeling-safe option or the TMT_FEELING_SAFE=1 environment variable defined. While it is roughly as safe as container provisioning, the plugin still bind-mounts the test directory.

Using the plugin:

provision:
    how: mock
    config: fedora-rawhide-x86_64

provision --how mock --config fedora-rawhide-x86_64

Note

Neither hard nor soft reboot is supported.

Configuration

See also Common Keys accepted by the plugin.

ansible

Ansible configuration for individual guest inventory generation.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_MOCK_ANSIBLE

In plan metadata:

ansible:

On command-line:

--ansible ...
export TMT_PLUGIN_PROVISION_MOCK_ANSIBLE=...

become

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

Default: false

Environment variable: TMT_PLUGIN_PROVISION_MOCK_BECOME

In plan metadata:

become: true|false

On command-line:

--become
export TMT_PLUGIN_PROVISION_MOCK_BECOME=1|0

environment

Environment variables to be defined for this guest. These will be available during test execution and can be used to customize behavior on a per-guest basis. Note that variables defined here can be overridden by test-level environment variables.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_MOCK_ENVIRONMENT

In plan metadata:

environment: KEY=VALUE

On command-line:

--environment KEY=VALUE
export TMT_PLUGIN_PROVISION_MOCK_ENVIRONMENT=KEY=VALUE

hardware

Hardware requirements the provisioned guest must satisfy.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_MOCK_HARDWARE

In plan metadata:

hardware: KEY=VALUE

On command-line:

--hardware KEY=VALUE
export TMT_PLUGIN_PROVISION_MOCK_HARDWARE=KEY=VALUE

role

Marks guests with the same purpose so that common actions can be applied to all such guests at once.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_MOCK_ROLE

In plan metadata:

role: NAME

On command-line:

--role NAME
export TMT_PLUGIN_PROVISION_MOCK_ROLE=NAME

root

Mock chroot configuration file. The –root flag to be passed to the mock process.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_MOCK_ROOT

In plan metadata:

root: ROOT

On command-line:

--root ROOT
export TMT_PLUGIN_PROVISION_MOCK_ROOT=ROOT

rootdir

The path for where the chroot should be built.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_MOCK_ROOTDIR

In plan metadata:

rootdir: ROOTDIR

On command-line:

--rootdir ROOTDIR
export TMT_PLUGIN_PROVISION_MOCK_ROOTDIR=ROOTDIR

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. Testcloud takes care of downloading an image and making necessary changes to it for optimal experience (such as disabling UseDNS and GSSAPI for SSH).

Minimal config which uses the latest Fedora image:

provision:
    how: virtual

Here’s a full config example:

# Provision a virtual machine from a specific QCOW2 file,
# using specific memory and disk settings, using the fedora user,
# and using sudo to run scripts.
provision:
    how: virtual
    image: https://mirror.vpsnet.com/fedora/linux/releases/41/Cloud/x86_64/images/Fedora-Cloud-Base-Generic-41-1.4.x86_64.qcow2
    user: fedora
    become: true
    # in MB
    memory: 2048
    # in GB
    disk: 30

Images

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.

Reboot

To trigger hard reboot of a guest, plugin uses testcloud API. It is also used to trigger soft reboot unless a custom reboot command was specified via tmt-reboot -c ....

Console

The full console log is available, after the guest is booted, in the logs directory under the provision step workdir, for example: plan/provision/client/logs/console.txt. Enable verbose mode using -vv to get the full path printed to the terminal for easy investigation.

Note

Make sure testcloud and libvirt packages are installed and configured, they are required for VM-backed guests provided by provision/virtual.testcloud plugin.

Users who installed tmt from system repositories should install tmt+provision-virtual package.
Users who installed tmt from PyPI should also install tmt+provision-virtual package, as it will install required system dependencies. After doing so, they should install tmt[provision-virtual] extra.

Configuration

See also Common Keys accepted by the plugin.

ansible

Ansible configuration for individual guest inventory generation.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_ANSIBLE

In plan metadata:

ansible:

On command-line:

--ansible ...
export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_ANSIBLE=...

arch

What architecture to virtualize, host arch by default.

Default: x86_64

Environment variable: TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_ARCH

In plan metadata:

arch: x86_64|aarch64|s390x|ppc64le

On command-line:

--arch 'x86_64|aarch64|s390x|ppc64le'
export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_ARCH='x86_64|aarch64|s390x|ppc64le'

become

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

Default: false

Environment variable: TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_BECOME

In plan metadata:

become: true|false

On command-line:

--become
export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_BECOME=1|0

connection

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

Default: session

Environment variable: TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_CONNECTION

In plan metadata:

connection: session|system

On command-line:

--connection 'session|system'
export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_CONNECTION='session|system'

disk

Specify disk size in GB, 10 GB by default.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_DISK

In plan metadata:

disk: SIZE

On command-line:

--disk SIZE
export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_DISK=SIZE

environment

Environment variables to be defined for this guest. These will be available during test execution and can be used to customize behavior on a per-guest basis. Note that variables defined here can be overridden by test-level environment variables.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_ENVIRONMENT

In plan metadata:

environment: KEY=VALUE

On command-line:

--environment KEY=VALUE
export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_ENVIRONMENT=KEY=VALUE

hardware

Hardware requirements the provisioned guest must satisfy.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_HARDWARE

In plan metadata:

hardware: KEY=VALUE

On command-line:

--hardware KEY=VALUE
export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_HARDWARE=KEY=VALUE

image

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

Default: fedora

Environment variable: TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_IMAGE

In plan metadata:

image: IMAGE

On command-line:

--image IMAGE
export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_IMAGE=IMAGE

key

Private key to use as SSH identity for key-based authentication.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_KEY

In plan metadata:

key: PATH

On command-line:

--key PATH
export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_KEY=PATH

list-local-images

List locally available images.

Default: false

Environment variable: TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_LIST_LOCAL_IMAGES

In plan metadata:

list-local-images: true|false

On command-line:

--list-local-images
export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_LIST_LOCAL_IMAGES=1|0

memory

Set available memory in MB, 2048 MB by default.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_MEMORY

In plan metadata:

memory: SIZE

On command-line:

--memory SIZE
export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_MEMORY=SIZE

password

Password to use for password-based authentication.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_PASSWORD

In plan metadata:

password: PASSWORD

On command-line:

--password PASSWORD
export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_PASSWORD=PASSWORD

port

Port to use for SSH connections instead of the default one.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_PORT

In plan metadata:

port: PORT

On command-line:

--port PORT
export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_PORT=PORT

role

Marks guests with the same purpose so that common actions can be applied to all such guests at once.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_ROLE

In plan metadata:

role: NAME

On command-line:

--role NAME
export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_ROLE=NAME

ssh-option

Additional SSH option. Value is passed to the -o option of ssh, see ssh_config(5) for supported options. Can be specified multiple times.

Default: not set

Environment variable: TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_SSH_OPTION

In plan metadata:

ssh-option: OPTION

On command-line:

--ssh-option OPTION
export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_SSH_OPTION=OPTION

stop-retries

Number of attempts to stop a VM.

Default: 10

Environment variable: TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_STOP_RETRIES

In plan metadata:

stop-retries: N

On command-line:

--stop-retries N
export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_STOP_RETRIES=N

stop-retry-delay

Time to wait between attempts to stop a VM.

Default: 1

Environment variable: TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_STOP_RETRY_DELAY

In plan metadata:

stop-retry-delay: SECONDS

On command-line:

--stop-retry-delay SECONDS
export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_STOP_RETRY_DELAY=SECONDS

user

A username to use for all guest operations.

Default: root

Environment variable: TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_USER

In plan metadata:

user: NAME

On command-line:

--user NAME
export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_USER=NAME