:tocdepth: 0 .. _/plugins/provision: Provision Plugins ~~~~~~~~~~~~~~~~~ .. _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 suboptional. Provision guest using Artemis backend. Minimal configuration could look like this: .. code-block:: yaml 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: .. 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 ^^^^^^^^^^^^^ 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.69`` 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`` guestname: Default: *not set* 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* Common Keys """"""""""" 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* ---- .. _plugins/provision/connect: 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 suboptional. Connect to a provisioned guest using SSH. Private key authentication: .. code-block:: yaml provision: how: connect guest: host.example.org user: root 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 Configuration ^^^^^^^^^^^^^ 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`` Common Keys """"""""""" 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* ---- .. _plugins/provision/local: 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 suboptional. 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 ;-) Example config: .. code-block:: yaml 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 ^^^^^^^^^^^^^ 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* Common Keys """"""""""" 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* ---- .. _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 suboptional. Provision guest on Beaker system using mrack. Minimal configuration could look like this: .. code-block:: yaml provision: how: beaker image: fedora Configuration ^^^^^^^^^^^^^ 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`` 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`` job-id: 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* 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* Common Keys """"""""""" 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* ---- .. _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 suboptional. Create a new container using ``podman``. Example config: .. code-block:: yaml 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 ^^^^^^^^^^^^^ 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`` network: Default: *not set* 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`` Common Keys """"""""""" 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* ---- .. _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 suboptional. Local virtual machine using ``testcloud`` library. Minimal config which uses the latest Fedora image: .. code-block:: yaml provision: how: virtual Here's a full config example: .. code-block:: yaml provision: how: virtual image: fedora user: root memory: 2048 As the image use ``fedora`` for the latest released Fedora compose, ``fedora-rawhide`` for the latest Rawhide compose, short aliases such as ``fedora-32``, ``f-32`` or ``f32`` for specific release or a full url to the qcow2 image for example from https://kojipkgs.fedoraproject.org/compose/. Short names are also provided for ``centos``, ``centos-stream``, ``alma``, ``rocky``, ``oracle``, ``debian`` and ``ubuntu`` (e.g. ``centos-8`` or ``c8``). .. note:: The non-rpm distros are not fully supported yet in tmt as the package installation is performed solely using ``dnf``/``yum`` and ``rpm``. But you should be able the login to the provisioned guest and start experimenting. Full support is coming in the future :) Supported Fedora CoreOS images are: * ``fedora-coreos`` * ``fedora-coreos-stable`` * ``fedora-coreos-testing`` * ``fedora-coreos-next`` Use the full path for images stored on local disk, for example: .. 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. Configuration ^^^^^^^^^^^^^ 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`` image-url: Default: *not set* instance-name: Default: *not set* 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`` Common Keys """"""""""" 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*