: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 draft plugin to be implemented Configuration ^^^^^^^^^^^^^ See also :ref:`Common Keys` accepted by the plugin. 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