:tocdepth: 0 .. _/plugins/provision: Provision Plugins ~~~~~~~~~~~~~~~~~ .. include:: provision-header.inc.rst .. _/plugins/provision/common-keys: 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: .. code-block:: yaml name: On command-line: .. code-block:: shell --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: .. code-block:: yaml order: On command-line: .. code-block:: shell --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: .. code-block:: yaml summary: On command-line: .. code-block:: shell --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: .. code-block:: yaml when: RULE On command-line: .. code-block:: shell --when RULE export TMT_PLUGIN_PROVISION_ARTEMIS_WHEN=RULE .. _/plugins/provision/artemis: 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 :ref:`/spec/hardware` are supported. Including the :ref:`/spec/plans/provision/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: .. code-block:: yaml provision: how: artemis image: Fedora api-url: https://your-artemis.com/ .. note:: When used together with the :ref:`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: .. code-block:: yaml 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 :ref:`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: .. code-block:: yaml ansible: On command-line: .. code-block:: shell --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: .. code-block:: yaml api-retries: COUNT On command-line: .. code-block:: shell --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: .. code-block:: yaml api-retry-backoff-factor: COUNT On command-line: .. code-block:: shell --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: .. code-block:: yaml api-timeout: SECONDS On command-line: .. code-block:: shell --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: .. code-block:: yaml api-url: URL On command-line: .. code-block:: shell --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: .. code-block:: yaml api-version: X.Y.Z On command-line: .. code-block:: shell --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: .. code-block:: yaml arch: ARCH On command-line: .. code-block:: shell --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: .. code-block:: yaml become: true|false On command-line: .. code-block:: shell --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: .. code-block:: yaml environment: KEY=VALUE On command-line: .. code-block:: shell --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: .. code-block:: yaml hardware: KEY=VALUE On command-line: .. code-block:: shell --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: .. code-block:: yaml image: COMPOSE On command-line: .. code-block:: shell --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: .. code-block:: yaml key: PATH On command-line: .. code-block:: shell --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: .. code-block:: yaml keyname: NAME On command-line: .. code-block:: shell --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: .. code-block:: yaml kickstart: KEY=VALUE On command-line: .. code-block:: shell --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: .. code-block:: yaml 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: .. code-block:: shell --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: .. code-block:: yaml password: PASSWORD On command-line: .. code-block:: shell --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: .. code-block:: yaml pool: NAME On command-line: .. code-block:: shell --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: .. code-block:: yaml port: PORT On command-line: .. code-block:: shell --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: .. code-block:: yaml post-install-script: SCRIPT|URL On command-line: .. code-block:: shell --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: .. code-block:: yaml priority-group: NAME On command-line: .. code-block:: shell --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: .. code-block:: yaml provision-tick: SECONDS On command-line: .. code-block:: shell --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: .. code-block:: yaml provision-timeout: SECONDS On command-line: .. code-block:: shell --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: .. code-block:: yaml role: NAME On command-line: .. code-block:: shell --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: .. code-block:: yaml skip-prepare-verify-ssh: true|false On command-line: .. code-block:: shell --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: .. code-block:: yaml ssh-option: OPTION On command-line: .. code-block:: shell --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: .. code-block:: yaml user: NAME On command-line: .. code-block:: shell --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: .. code-block:: yaml user-data: KEY=VALUE On command-line: .. code-block:: shell --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: .. code-block:: yaml watchdog-dispatch-delay: SECONDS On command-line: .. code-block:: shell --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: .. code-block:: yaml watchdog-period-delay: SECONDS On command-line: .. code-block:: shell --watchdog-period-delay SECONDS export TMT_PLUGIN_PROVISION_ARTEMIS_WATCHDOG_PERIOD_DELAY=SECONDS ---- .. _/plugins/provision/beaker: 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: .. code-block:: yaml 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. .. code-block:: yaml # Specify the distro directly provision: how: beaker image: Fedora-37% .. code-block:: yaml # Set custom whiteboard description (added in 1.30) provision: how: beaker whiteboard: Just a smoke test for now Configuration ^^^^^^^^^^^^^ See also :ref:`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: .. code-block:: yaml ansible: On command-line: .. code-block:: shell --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: .. code-block:: yaml api-session-refresh-tick: SECONDS On command-line: .. code-block:: shell --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: .. code-block:: yaml arch: ARCH On command-line: .. code-block:: shell --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: .. code-block:: yaml beaker-job-group: GROUPNAME On command-line: .. code-block:: shell --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: .. code-block:: yaml beaker-job-owner: USERNAME On command-line: .. code-block:: shell --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: .. code-block:: yaml become: true|false On command-line: .. code-block:: shell --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: .. code-block:: yaml bootc: true|false On command-line: .. code-block:: shell --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: .. code-block:: yaml bootc-check-system-url: URL On command-line: .. code-block:: shell --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: .. code-block:: yaml bootc-image-url: URL On command-line: .. code-block:: shell --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: .. code-block:: yaml bootc-registry-secret: SECRET On command-line: .. code-block:: shell --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: .. code-block:: yaml environment: KEY=VALUE On command-line: .. code-block:: shell --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: .. code-block:: yaml hardware: KEY=VALUE On command-line: .. code-block:: shell --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: .. code-block:: yaml image: COMPOSE On command-line: .. code-block:: shell --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: .. code-block:: yaml key: PATH On command-line: .. code-block:: shell --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: .. code-block:: yaml kickstart: KEY=VALUE On command-line: .. code-block:: shell --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: .. code-block:: yaml password: PASSWORD On command-line: .. code-block:: shell --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: .. code-block:: yaml port: PORT On command-line: .. code-block:: shell --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: .. code-block:: yaml provision-tick: SECONDS On command-line: .. code-block:: shell --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: .. code-block:: yaml provision-timeout: SECONDS On command-line: .. code-block:: shell --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: .. code-block:: yaml public-key: PUBKEY On command-line: .. code-block:: shell --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: .. code-block:: yaml role: NAME On command-line: .. code-block:: shell --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: .. code-block:: yaml ssh-option: OPTION On command-line: .. code-block:: shell --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: .. code-block:: yaml user: NAME On command-line: .. code-block:: shell --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: .. code-block:: yaml whiteboard: WHITEBOARD On command-line: .. code-block:: shell --whiteboard WHITEBOARD export TMT_PLUGIN_PROVISION_BEAKER_WHITEBOARD=WHITEBOARD ---- .. _/plugins/provision/bootc: 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: .. code-block:: yaml provision: how: bootc container-image: quay.io/centos-bootc/centos-bootc:stream9 rootfs: xfs Here's a config example using a Containerfile: .. code-block:: yaml 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: .. code-block:: yaml 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 :ref:`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: .. code-block:: yaml add-tmt-dependencies: true|false On command-line: .. code-block:: shell --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: .. code-block:: yaml ansible: On command-line: .. code-block:: shell --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: .. code-block:: yaml arch: x86_64|aarch64|s390x|ppc64le On command-line: .. code-block:: shell --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: .. code-block:: yaml become: true|false On command-line: .. code-block:: shell --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: .. code-block:: yaml build-disk-image-only: true|false On command-line: .. code-block:: shell --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: .. code-block:: yaml connection: session|system On command-line: .. code-block:: shell --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: .. code-block:: yaml container-file: CONTAINER_FILE On command-line: .. code-block:: shell --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: .. code-block:: yaml container-file-workdir: CONTAINER_FILE_WORKDIR On command-line: .. code-block:: shell --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: .. code-block:: yaml container-image: CONTAINER_IMAGE On command-line: .. code-block:: shell --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: .. code-block:: yaml disk: SIZE On command-line: .. code-block:: shell --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: .. code-block:: yaml environment: KEY=VALUE On command-line: .. code-block:: shell --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: .. code-block:: yaml hardware: KEY=VALUE On command-line: .. code-block:: shell --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: .. code-block:: yaml image: IMAGE On command-line: .. code-block:: shell --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: .. code-block:: yaml image-builder: IMAGE_BUILDER On command-line: .. code-block:: shell --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: .. code-block:: yaml key: PATH On command-line: .. code-block:: shell --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: .. code-block:: yaml list-local-images: true|false On command-line: .. code-block:: shell --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: .. code-block:: yaml memory: SIZE On command-line: .. code-block:: shell --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: .. code-block:: yaml password: PASSWORD On command-line: .. code-block:: shell --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: .. code-block:: yaml port: PORT On command-line: .. code-block:: shell --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: .. code-block:: yaml role: NAME On command-line: .. code-block:: shell --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: .. code-block:: yaml rootfs: ext4|xfs|btrfs On command-line: .. code-block:: shell --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: .. code-block:: yaml ssh-option: OPTION On command-line: .. code-block:: shell --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: .. code-block:: yaml stop-retries: N On command-line: .. code-block:: shell --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: .. code-block:: yaml stop-retry-delay: SECONDS On command-line: .. code-block:: shell --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: .. code-block:: yaml user: NAME On command-line: .. code-block:: shell --user NAME export TMT_PLUGIN_PROVISION_BOOTC_USER=NAME ---- .. _/plugins/provision/connect: 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): .. code-block:: yaml provision: how: connect guest: host.example.org user: fedora become: true key: /home/psss/.ssh/example_rsa Password authentication: .. code-block:: yaml 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: .. code-block:: yaml 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: .. code-block:: yaml 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' .. code-block:: shell 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 :ref:`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: .. code-block:: yaml ansible: On command-line: .. code-block:: shell --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: .. code-block:: yaml become: true|false On command-line: .. code-block:: shell --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: .. code-block:: yaml environment: KEY=VALUE On command-line: .. code-block:: shell --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: .. code-block:: yaml guest: HOSTNAME|IP On command-line: .. code-block:: shell --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: .. code-block:: yaml hard-reboot: COMMAND On command-line: .. code-block:: shell --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: .. code-block:: yaml hardware: KEY=VALUE On command-line: .. code-block:: shell --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: .. code-block:: yaml key: PATH On command-line: .. code-block:: shell --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: .. code-block:: yaml password: PASSWORD On command-line: .. code-block:: shell --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: .. code-block:: yaml port: PORT On command-line: .. code-block:: shell --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: .. code-block:: yaml role: NAME On command-line: .. code-block:: shell --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: .. code-block:: yaml soft-reboot: COMMAND On command-line: .. code-block:: shell --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: .. code-block:: yaml ssh-option: OPTION On command-line: .. code-block:: shell --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: .. code-block:: yaml systemd-soft-reboot: COMMAND On command-line: .. code-block:: shell --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: .. code-block:: yaml user: NAME On command-line: .. code-block:: shell --user NAME export TMT_PLUGIN_PROVISION_CONNECT_USER=NAME ---- .. _/plugins/provision/container: 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: .. code-block:: yaml provision: how: container image: fedora:latest .. code-block:: yaml # 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 :ref:`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: .. code-block:: yaml ansible: On command-line: .. code-block:: shell --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: .. code-block:: yaml become: true|false On command-line: .. code-block:: shell --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: .. code-block:: yaml container: NAME On command-line: .. code-block:: shell --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: .. code-block:: yaml environment: KEY=VALUE On command-line: .. code-block:: shell --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: .. code-block:: yaml force-pull: true|false On command-line: .. code-block:: shell --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: .. code-block:: yaml hardware: KEY=VALUE On command-line: .. code-block:: shell --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: .. code-block:: yaml image: IMAGE On command-line: .. code-block:: shell --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: .. code-block:: yaml pull-attempts: COUNT On command-line: .. code-block:: shell --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: .. code-block:: yaml pull-interval: SECONDS On command-line: .. code-block:: shell --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: .. code-block:: yaml role: NAME On command-line: .. code-block:: shell --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: .. code-block:: yaml stop-time: SECONDS On command-line: .. code-block:: shell --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: .. code-block:: yaml user: USERNAME On command-line: .. code-block:: shell --user USERNAME export TMT_PLUGIN_PROVISION_CONTAINER_USER=USERNAME ---- .. _/plugins/provision/local: 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: .. code-block:: yaml provision: how: local .. code-block:: shell 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 :ref:`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: .. code-block:: yaml ansible: On command-line: .. code-block:: shell --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: .. code-block:: yaml become: true|false On command-line: .. code-block:: shell --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: .. code-block:: yaml environment: KEY=VALUE On command-line: .. code-block:: shell --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: .. code-block:: yaml hardware: KEY=VALUE On command-line: .. code-block:: shell --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: .. code-block:: yaml role: NAME On command-line: .. code-block:: shell --role NAME export TMT_PLUGIN_PROVISION_LOCAL_ROLE=NAME ---- .. _/plugins/provision/mock: 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: .. code-block:: yaml provision: how: mock config: fedora-rawhide-x86_64 .. code-block:: shell provision --how mock --config fedora-rawhide-x86_64 .. note:: Neither hard nor soft reboot is supported. Configuration ^^^^^^^^^^^^^ See also :ref:`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: .. code-block:: yaml ansible: On command-line: .. code-block:: shell --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: .. code-block:: yaml become: true|false On command-line: .. code-block:: shell --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: .. code-block:: yaml environment: KEY=VALUE On command-line: .. code-block:: shell --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: .. code-block:: yaml hardware: KEY=VALUE On command-line: .. code-block:: shell --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: .. code-block:: yaml role: NAME On command-line: .. code-block:: shell --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: .. code-block:: yaml root: ROOT On command-line: .. code-block:: shell --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: .. code-block:: yaml rootdir: ROOTDIR On command-line: .. code-block:: shell --rootdir ROOTDIR export TMT_PLUGIN_PROVISION_MOCK_ROOTDIR=ROOTDIR ---- .. _/plugins/provision/virtual.testcloud: 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: .. code-block:: yaml provision: how: virtual Here's a full config example: .. code-block:: yaml # 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: .. code-block:: shell /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 :ref:`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: .. code-block:: yaml ansible: On command-line: .. code-block:: shell --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: .. code-block:: yaml arch: x86_64|aarch64|s390x|ppc64le On command-line: .. code-block:: shell --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: .. code-block:: yaml become: true|false On command-line: .. code-block:: shell --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: .. code-block:: yaml connection: session|system On command-line: .. code-block:: shell --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: .. code-block:: yaml disk: SIZE On command-line: .. code-block:: shell --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: .. code-block:: yaml environment: KEY=VALUE On command-line: .. code-block:: shell --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: .. code-block:: yaml hardware: KEY=VALUE On command-line: .. code-block:: shell --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: .. code-block:: yaml image: IMAGE On command-line: .. code-block:: shell --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: .. code-block:: yaml key: PATH On command-line: .. code-block:: shell --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: .. code-block:: yaml list-local-images: true|false On command-line: .. code-block:: shell --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: .. code-block:: yaml memory: SIZE On command-line: .. code-block:: shell --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: .. code-block:: yaml password: PASSWORD On command-line: .. code-block:: shell --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: .. code-block:: yaml port: PORT On command-line: .. code-block:: shell --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: .. code-block:: yaml role: NAME On command-line: .. code-block:: shell --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: .. code-block:: yaml ssh-option: OPTION On command-line: .. code-block:: shell --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: .. code-block:: yaml stop-retries: N On command-line: .. code-block:: shell --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: .. code-block:: yaml stop-retry-delay: SECONDS On command-line: .. code-block:: shell --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: .. code-block:: yaml user: NAME On command-line: .. code-block:: shell --user NAME export TMT_PLUGIN_PROVISION_VIRTUAL.TESTCLOUD_USER=NAME