Document the order of precedence of environment variable sources

[happz]

Environment variables visible to test - but not just tests, prepare scripts or Ansible playbooks must be considered too! - are composed from various sources:

External sources

• run: --environment and --environment-file CLI options
• plan: environment and environment-file fmf keys
• importing plan: environment fmf key of the importing plan
• provision phases ("per-guest environment"): environment fmf key, --environment CLI option
• test: environment fmf key

Internal sources

• plugin action itself - test name, test data, plan data, ...
• test framework
• invocation contexts - reboot, restart, abort, pidfile, restraint, ...

(Did I miss any source?)

The question is: in which order shall they be applied? We are not 100 % sure, and then there are users asking.

The goal is to put together a documentation similar to https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable

[HouMinXi]

Give a more example I plan start two tests, the first test need BUILDID parameter, the second test need OVS_URL/DPDK_URL/NIC_DRIVER as parameters.

on plan level, I define environment as below:

  environment:
    OVS_URL: "https://download.eng.pek2.redhat.com/brewroot/packages/openvswitch3.5/3.5.1/34.el10fdp/x86_64/openvswitch3.5-3.5.1-34.el10fdp.x86_64.rpm"
    DPDK_URL: "https://download.devel.redhat.com/brewroot/packages/dpdk/24.11.1/2.el10/x86_64/dpdk-24.11.1-2.el10.x86_64.rpm"
    BUILDID: $@{build_id}
    NIC_DRIVER: ice,mlx5_core

Q1: Currently, all parameters can be seen on all tests. BUILDID/OVS_URL/DPDK_URL/NIC_DRIVER exist on the first test and the second test. This can easily cause parameter confusion. In fact, task1 only needs the BUILDID parameter.

Q2: NIC_DRIVER is a user-define parameter that used for specify which nic should be used in corresponding server. One server can have muti-nics. So I need to send NIC_DRIVER parameter to plan. So it would exist in plan-level environment, but I didn't know how to change to NIC_DRIVER in provision-level environment.

[therazix]

From the hacking session: Let's find all environment variable sources, determine their correct order and where they should be applied. Also add a test coverage. Proposing to the next sprint.

[happz]

Ok, kicking of with a summary and a couple of notes and TODO items while my memory is reasonably fresh.

See https://github.com/teemtee/tmt/pull/4364 for the very rough draft and notes, and https://tmt--4364.org.readthedocs.build/en/4364/environment.html for the preview.

Ignore the location of the document, I just needed to hook it somewhere.

[happz]

Removed from the sprint, we need a couple of smaller PRs to fix various issues, eventually the documentation will land.