:tocdepth: 0 .. _/plugins/prepare: Prepare Plugins ~~~~~~~~~~~~~~~ .. include:: prepare-header.inc.rst .. _/plugins/prepare/common-keys: Common Keys ----------- The following keys are accepted by all plugins of the ``prepare`` step. name The name of the step phase. Environment variable: ``TMT_PLUGIN_PREPARE_ANSIBLE_NAME`` In plan metadata: .. code-block:: yaml name: On command-line: .. code-block:: shell --name ... export TMT_PLUGIN_PREPARE_ANSIBLE_NAME=... order Order in which the phase should be handled. Default: ``50`` Environment variable: ``TMT_PLUGIN_PREPARE_ANSIBLE_ORDER`` In plan metadata: .. code-block:: yaml order: On command-line: .. code-block:: shell --order ... export TMT_PLUGIN_PREPARE_ANSIBLE_ORDER=... summary Concise summary describing purpose of the phase. Default: *not set* Environment variable: ``TMT_PLUGIN_PREPARE_ANSIBLE_SUMMARY`` In plan metadata: .. code-block:: yaml summary: On command-line: .. code-block:: shell --summary ... export TMT_PLUGIN_PREPARE_ANSIBLE_SUMMARY=... when If specified, phase is run only if any rule matches plan context. Default: *not set* Environment variable: ``TMT_PLUGIN_PREPARE_ANSIBLE_WHEN`` In plan metadata: .. code-block:: yaml when: RULE On command-line: .. code-block:: shell --when RULE export TMT_PLUGIN_PREPARE_ANSIBLE_WHEN=RULE where Run this phase on given guest or guests with the given role only. Default: *not set* Environment variable: ``TMT_PLUGIN_PREPARE_ANSIBLE_WHERE`` In plan metadata: .. code-block:: yaml where: GUEST|ROLE On command-line: .. code-block:: shell --where 'GUEST|ROLE' export TMT_PLUGIN_PREPARE_ANSIBLE_WHERE='GUEST|ROLE' .. _/plugins/prepare/ansible: ansible ------- Run Ansible playbooks against the guest, by running ``ansible-playbook`` for all given playbooks. .. note:: The plugin requires a working Ansible to be available on the test runner. .. warning:: When specifying playbooks with paths: * If a metadata tree root exists, all paths must be relative to the metadata tree root. * If the metadata tree root does not exist, all paths must be relative to the current working directory. .. warning:: The plugin may be a subject of various limitations, imposed by Ansible itself: * Ansible 2.17+ no longer supports Python 3.6 and older. Guests where Python 3.7+ is not available cannot be prepared with the ``ansible`` plugin. This has been observed when Fedora Rawhide runner is used with CentOS 7 or CentOS Stream 8 guests. Possible workarounds: downgrade Ansible tmt uses, or install Python 3.7+ before using ``ansible`` plugin from an alternative repository or local build. Run a single playbook on the guest: .. code-block:: yaml prepare: how: ansible playbook: ansible/packages.yml .. code-block:: shell prepare --how ansible --playbook ansible/packages.yml Run multiple playbooks in one phase, with extra arguments for ``ansible-playbook``: .. code-block:: yaml prepare: how: ansible playbook: - one.yml - two.yml extra-args: '-vvv' .. code-block:: shell prepare --how ansible --playbook one.yml --playbook two.yml --extra-args '-vvv' Remote playbooks - provided as URLs starting with ``http://`` or ``https://``, local playbooks - optionally starting with a ``file://`` schema, and playbooks bundled with collections can be referenced as well as local ones, and all kinds can be intermixed: .. code-block:: yaml prepare: how: ansible playbook: - https://foo.bar/one.yml - two.yml - file://three.yml - ansible_galaxy_namespace.cool_collection.four .. code-block:: shell prepare --how ansible --playbook https://foo.bar/two.yml \ --playbook two.yml \ --playbook file://three.yml \ --playbook ansible_galaxy_namespace.cool_collection.four Configuration ^^^^^^^^^^^^^ See also :ref:`Common Keys` accepted by the plugin. extra-args Additional CLI options for ``ansible-playbook``. Default: *not set* Environment variable: ``TMT_PLUGIN_PREPARE_ANSIBLE_EXTRA_ARGS`` In plan metadata: .. code-block:: yaml extra-args: ANSIBLE-PLAYBOOK-OPTIONS extra-args: -vvv On command-line: .. code-block:: shell --extra-args ANSIBLE-PLAYBOOK-OPTIONS export TMT_PLUGIN_PREPARE_ANSIBLE_EXTRA_ARGS=ANSIBLE-PLAYBOOK-OPTIONS --extra-args -vvv export TMT_PLUGIN_PREPARE_ANSIBLE_EXTRA_ARGS=-vvv playbook Path or URL of an Ansible playbook, or a playbook bundled within a collection, to run on a guest. Playbook ``PATH`` must be relative to the metadata tree root, if the metadata tree exists, or to the current working directory. Default: *not set* Environment variable: ``TMT_PLUGIN_PREPARE_ANSIBLE_PLAYBOOK`` In plan metadata: .. code-block:: yaml playbook: PATH|URL|NAMESPACE.COLLECTION.PLAYBOOK On command-line: .. code-block:: shell --playbook 'PATH|URL|NAMESPACE.COLLECTION.PLAYBOOK' export TMT_PLUGIN_PREPARE_ANSIBLE_PLAYBOOK='PATH|URL|NAMESPACE.COLLECTION.PLAYBOOK' ---- .. _/plugins/prepare/artifact: artifact -------- .. 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. Prepare artifacts on the guest. .. note:: This is a tech preview feature. This plugin makes a given artifact available on the guest. This can consist of downloading the artifacts and creating a preferred repository on the guest. The goal is to make sure these exact artifacts are being used when requested in one of the :ref:`test require `, :ref:`test recommend `, or :ref:`prepare install `. Exact NVR *should not* be used in those requests, instead this plugin will take care of disambiguating the requested package based on the provided artifacts. Currently, the following artifact providers are supported: **Koji** Builds from the `Fedora Koji `__ build system. * ``koji.build:`` - Koji build by build ID * ``koji.task:`` - Koji task (including scratch builds) * ``koji.nvr:`` - Koji build by NVR (name-version-release) Example usage: .. code-block:: yaml prepare: how: artifact provide: - koji.build:123456 - koji.task:654321 - koji.nvr:openssl-3.2.6-2.fc42 **Brew** (Red Hat internal) Builds from the Red Hat Brew build system. * ``brew.build:`` - Brew build by build ID * ``brew.task:`` - Brew task (including scratch builds) * ``brew.nvr:`` - Brew build by NVR Example usage: .. code-block:: yaml prepare: how: artifact provide: - brew.build:123456 - brew.task:654321 - brew.nvr:openssl-3.2.6-2.el10 **Copr** Builds from the `Fedora Copr `__ build system. * ``copr.build::`` - Copr build by ID and chroot Example usage: .. code-block:: yaml prepare: how: artifact provide: - copr.build:1784470:fedora-43-x86_64 **File** RPMs from local files or remote URLs. * ``file:`` - Local RPM file(s) specified via path or a glob pattern * ``file:`` - All RPMs from a local directory * ``file:`` - Remote RPM file URL (http/https) Example usage: .. code-block:: yaml prepare: how: artifact provide: - file:/tmp/my-package.rpm - file:/tmp/rpms/*.rpm - file:/tmp/rpms - file:https://example.com/my-package.rpm **Repository** Remote dnf repositories. * ``repository-file:`` - URL to a ``.repo`` file .. note:: The ``repository-file`` provider only adds the dnf repository to the guest system, and does not download the RPMs from the repository. Example usage: .. code-block:: yaml prepare: how: artifact provide: - repository-file:https://example.com/my-repo.repo Configuration ^^^^^^^^^^^^^ See also :ref:`Common Keys` accepted by the plugin. default-repository-priority Default priority for created artifact repositories. Lower values mean higher priority in package managers. Default: ``50`` Environment variable: ``TMT_PLUGIN_PREPARE_ARTIFACT_DEFAULT_REPOSITORY_PRIORITY`` In plan metadata: .. code-block:: yaml default-repository-priority: PRIORITY On command-line: .. code-block:: shell --default-repository-priority PRIORITY export TMT_PLUGIN_PREPARE_ARTIFACT_DEFAULT_REPOSITORY_PRIORITY=PRIORITY provide Artifact ID to provide. Format :. Default: *not set* Environment variable: ``TMT_PLUGIN_PREPARE_ARTIFACT_PROVIDE`` In plan metadata: .. code-block:: yaml provide: ID On command-line: .. code-block:: shell --provide ID export TMT_PLUGIN_PREPARE_ARTIFACT_PROVIDE=ID ---- .. _/plugins/prepare/feature: feature ------- .. 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. Easily enable and disable common features The ``feature`` plugin provides a comfortable way to enable and disable some commonly used functionality such as enabling and disabling the ``epel`` repository or the ``fips`` mode. .. note:: The plugin requires a working Ansible to be available on the test runner. .. warning:: The plugin may be a subject of various limitations, imposed by the fact it uses Ansible to implement some of the features: * Ansible 2.17+ no longer supports Python 3.6 and older. Guests where Python 3.7+ is not available cannot be prepared with the ``feature`` plugin. This has been observed when Fedora Rawhide runner is used with CentOS 7 or CentOS Stream 8 guests. Possible workarounds: downgrade Ansible tmt uses, or install Python 3.7+ before using ``feature`` plugin from an alternative repository or local build. .. code-block:: yaml prepare: how: feature epel: disabled crb: enabled fips: enabled ... .. code-block:: shell prepare --how feature --epel disabled --crb enabled --fips enabled ... .. note:: Features available via this plugin are implemented and shipped as plugins too. The list of available features and configuration keys will depend on which plugins you have installed. See also :ref:`Common Keys` accepted by the plugin. .. include:: prepare-feature.rst .. _/plugins/prepare/install: install ------- .. 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. Install packages on the guest. Example config: .. code-block:: yaml prepare: how: install copr: psss/tmt package: tmt-all missing: fail Use ``copr`` for enabling a desired Copr repository and ``missing`` to choose whether missing packages should be silently ignored (``skip``) or a preparation error should be reported (``fail``), which is the default. One or more RPM packages can be specified under the ``package`` attribute. The packages will be installed on the guest. They can either be specified using their names, paths to local rpm files or urls to remote rpms. .. code-block:: yaml # Install local rpms using file path prepare: how: install package: - tmp/RPMS/noarch/tmt-0.15-1.fc31.noarch.rpm - tmp/RPMS/noarch/python3-tmt-0.15-1.fc31.noarch.rpm .. code-block:: yaml # Install remote packages using url prepare: how: install package: - https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm - https://dl.fedoraproject.org/pub/epel/epel-next-release-latest-8.noarch.rpm .. code-block:: yaml # Install the whole directory, exclude selected packages prepare: how: install directory: - tmp/RPMS/noarch exclude: - tmt+all - tmt+provision-virtual .. code-block:: yaml prepare: how: install # Repository with a group owner (@ prefixed) requires quotes, e.g. # copr: "@osci/rpminspect" copr: psss/tmt package: tmt-all missing: skip Use ``directory`` to install all packages from given folder and ``exclude`` to skip selected packages (globbing characters are supported as well). .. code-block:: yaml prepare: how: install directory: tmp/RPMS/noarch exclude: tmt+provision-virtual .. note:: When testing ostree booted deployments tmt will use ``rpm-ostree`` as the package manager to perform the installation of requested packages. The current limitations of the ``rpm-ostree`` implementation are: * Cannot install new version of already installed local rpm. * No support for installing debuginfo packages at this time. Configuration ^^^^^^^^^^^^^ See also :ref:`Common Keys` accepted by the plugin. copr Copr repository to be enabled. Default: *not set* Environment variable: ``TMT_PLUGIN_PREPARE_INSTALL_COPR`` In plan metadata: .. code-block:: yaml copr: REPO On command-line: .. code-block:: shell --copr REPO export TMT_PLUGIN_PREPARE_INSTALL_COPR=REPO directory Path to a local directory with rpm packages. Default: *not set* Environment variable: ``TMT_PLUGIN_PREPARE_INSTALL_DIRECTORY`` In plan metadata: .. code-block:: yaml directory: PATH On command-line: .. code-block:: shell --directory PATH export TMT_PLUGIN_PREPARE_INSTALL_DIRECTORY=PATH exclude Packages to be skipped during installation. Default: *not set* Environment variable: ``TMT_PLUGIN_PREPARE_INSTALL_EXCLUDE`` In plan metadata: .. code-block:: yaml exclude: PACKAGE On command-line: .. code-block:: shell --exclude PACKAGE export TMT_PLUGIN_PREPARE_INSTALL_EXCLUDE=PACKAGE missing Action on missing packages, fail (default) or skip. Default: ``fail`` Environment variable: ``TMT_PLUGIN_PREPARE_INSTALL_MISSING`` In plan metadata: .. code-block:: yaml missing: ACTION On command-line: .. code-block:: shell --missing ACTION export TMT_PLUGIN_PREPARE_INSTALL_MISSING=ACTION package Package name or path to rpm to be installed. Default: *not set* Environment variable: ``TMT_PLUGIN_PREPARE_INSTALL_PACKAGE`` In plan metadata: .. code-block:: yaml package: PACKAGE On command-line: .. code-block:: shell --package PACKAGE export TMT_PLUGIN_PREPARE_INSTALL_PACKAGE=PACKAGE ---- .. _/plugins/prepare/shell: shell ----- .. 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. Prepare guest using shell (Bash) scripts. Default shell options are applied to the script, see the :ref:`/spec/tests/test` key specification for more details. .. code-block:: yaml prepare: how: shell script: - sudo dnf install -y 'dnf-command(copr)' - sudo dnf copr enable -y psss/tmt - sudo dnf install -y tmt Scripts can also be fetched from a remote git repository. Specify the ``url`` for the repository and optionally ``ref`` to checkout a specific branch, tag or commit. ``TMT_PREPARE_SHELL_URL_REPOSITORY`` will hold the value of the repository path. .. code-block:: yaml prepare: how: shell url: https://github.com/teemtee/tmt.git ref: main script: cd $TMT_PREPARE_SHELL_URL_REPOSITORY && make docs Configuration ^^^^^^^^^^^^^ See also :ref:`Common Keys` accepted by the plugin. ref Branch, tag or commit to checkout in the git repository cloned when ``url`` is specified. Default: *not set* Environment variable: ``TMT_PLUGIN_PREPARE_SHELL_REF`` In plan metadata: .. code-block:: yaml ref: REVISION On command-line: .. code-block:: shell --ref REVISION export TMT_PLUGIN_PREPARE_SHELL_REF=REVISION script Shell script to be executed. Can be used multiple times. Default: *not set* Environment variable: ``TMT_PLUGIN_PREPARE_SHELL_SCRIPT`` In plan metadata: .. code-block:: yaml script: SCRIPT On command-line: .. code-block:: shell --script SCRIPT export TMT_PLUGIN_PREPARE_SHELL_SCRIPT=SCRIPT url URL of a repository to clone. It will be pushed to guests before running any scripts, the path on the guest will be stored in a step variable. Default: *not set* Environment variable: ``TMT_PLUGIN_PREPARE_SHELL_URL`` In plan metadata: .. code-block:: yaml url: REPOSITORY On command-line: .. code-block:: shell --url REPOSITORY export TMT_PLUGIN_PREPARE_SHELL_URL=REPOSITORY