System Variables

System Variable (sys_var) plugins give you the ability to add new variables that test configs can use in your environment. The variable values are generated by a Python function that you define, which makes the possibilities fairly limitless.

These are used primarily to gather information unique to your systems and environment. Tests can then use that information to tailor themselves to a particular system or deal with other complexities that are unique to your OS or software deployments.

Files

System Variable plugins, like all other Pavilion plugins, require a python module and a yapsy-plugin file. See the plugin basics for more info on these files and where they should go.

System Variable Module

A sys_var module should contain a class definition that inherits from the system variable base class.

from pavilion import system_variables

class Uptime(system_variables.SystemPlugin):
    """This is a fairly useless variable, but is a good enough example."""

    def __init__(self):

        super().__init__(
            # The name of the plugin.
            plugin_name="uptime",
            # The description will be listed when using 'pav show sys_vars'
            description="How long the (kickoff) host has been up in seconds.",
        )

    # This is the method you override to provide the variables value.
    # The base .get() method handles all the deferred variable logic, so
    # you don't have to.
    def _get(self):

        with open('/proc/uptime') as uptime:
            data = uptime.read()

        return data.split()[0]

With this plugin in the system, we can refer to it in test configs:

uptime_test:
  run:
    cmds: echo {{sys.uptime}}

The _get() Method

This should gather the information needed to compute your variables value and then return that value. While the computation of the value can be simple or complex, the returned value must be one of the following:

• A string
• A dict with a strict set of string keys and string values
• A list of such strings or dicts.

Important: If your variable can return dicts, it must always return them. It can’t return dicts sometimes and strings other times. Additionally, dicts returned must always have the same keys, regardless of system or other considerations.

Additional restrictions apply to deferred variables.

The __init__() Method

The basics of the __init__() method and it’s generic arguments are covered elsewhere.

The ‘is_deferrable’ argument

If this is set to True, then the variable value lookup will be deferred until right before the test is run within an allocation. This allows you to gather information on a node rather than the kickoff host.

Deferred variable values are more restricted. They can be one of: - A string - A dict with string keys and string values

The sub_keys argument

If a variable is deferred and is expected to return a dict, you must provide a list of the sub-keys that the return dictionary will contain. This is so Pavilion can validate any sub-key references made in configs at test kickoff time.