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
watchdogtest check
Following plugins fully implement hard reboot:
Hardware requirement support
Below you can find a matrix documenting which hardware requirement are supported by plugins bundled with tmt.
Requirement |
|
|
|
|
|
|
|
|---|---|---|---|---|---|---|---|
❌ |
✅ [1] |
❌ |
❌ |
❌ |
❌ |
❌ |
|
✅ |
❌ |
❌ |
❌ |
❌ |
❌ |
❌ |
|
✅ |
❌ |
❌ |
❌ |
❌ |
❌ |
❌ |
|
✅ [2] |
✅ [3] |
❌ |
❌ |
❌ |
❌ |
✅ [4] |
|
❌ |
❌ |
❌ |
❌ |
❌ |
❌ |
❌ |
|
✅ [5] |
✅ [6] |
❌ |
❌ |
❌ |
❌ |
✅ [7] |
|
❌ |
❌ |
❌ |
❌ |
❌ |
❌ |
❌ |
|
✅ |
✅ |
❌ |
❌ |
❌ |
❌ |
❌ |
|
❌ |
✅ [8] |
❌ |
❌ |
❌ |
❌ |
❌ |
|
❌ |
✅ [9] |
❌ |
❌ |
❌ |
❌ |
❌ |
|
✅ |
✅ |
❌ |
❌ |
❌ |
❌ |
✅ [10] |
|
✅ [11] |
❌ |
❌ |
❌ |
❌ |
❌ |
❌ |
|
❌ |
✅ [12] |
❌ |
❌ |
❌ |
❌ |
❌ |
|
✅ |
✅ |
❌ |
❌ |
❌ |
❌ |
✅ [13] |
|
✅ |
✅ [14] |
❌ |
❌ |
❌ |
❌ |
❌ |
|
✅ |
✅ |
❌ |
❌ |
❌ |
❌ |
❌ |
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
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-coreosfedora-coreos-stablefedora-coreos-testingfedora-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
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
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
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
- 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-owner:
USERNAME If set, Beaker jobs will be submitted on behalf of
USERNAME. Submitting user must be a submission delegate for theUSERNAME.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- 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