Jobs
====
Restraint parses a sub-set of the Beaker job XML [#]_. Here is an example
showing just the elements required for running in the stand-alone configuration.
::
.
.
.
Naming Tasks
------------
For reporting purposes it is a good idea to name your tasks. For git tasks we
have settled on a standard where we use the sub-directory path from our git repo
as the task name. You can see that in the following example.
::
This name will be used when reporting on the status of the task and when
reporting results.
Task Roles
----------
Restraint supports role assignment for tasks or whole recipes for use in
multi-host jobs.
::
The above example results in environment variables "SERVERS" and "CLIENTS"
containing hostnames assigned to corresponding recipes. The variables will be
available only to tasks with the same padding within recipes.
Recipe roles function as default roles for tasks that have no role specified
and can be overridden by task roles.
Apart from role env variables Restraint also exports 2 more hostname-related
variables:
* RECIPE_MEMBERS - contains hostnames of all hosts within current recipeSet.
* JOB_MEMBERS - contains hostnames of all hosts in current job.
Keeping Your Task Changes Intact
--------------------------------
By default Restraint will fetch tasks every time you run a recipe overwriting
any changes you've done locally. This is not desirable in some cases, e.g. when
debugging a test. Restraint provides the ability to keep local changes by
setting task property "keepchanges" to "yes" in the job xml.
::
Installing Tasks
----------------
The above example shows that you can install tasks directly from git or from an
RPM in a yum repo.
.. _fetch-label:
Fetch
~~~~~
The first example shows fetching a task from git.
::
OR
The fetch node accepts git URI's that conform to the following:
* Prefixed with git:// OR use tarballs with http:// and cgit can serve them
automatically.
* The fully qualified hostname. Remember that the system running restraintd must
be able to reach this host.
* The path to the git repo.
* Optionally you can specify a valid reference which can be a branch, tag or
SHA-1. ie: ?master
* Optionally you can specify a sub-dir. Restraint will only extract this sub-dir
and run the task from here. ie: #kernel/performance/fs_mark. Notice that
there is not a preceding slash here.
* If you need to disable SSL certificate checking you can set ssl_verify
parameter to "off".
Restraint uses git's archive protocol to retrieve the contents so make sure
your git server has enabled this. You can enable this on most servers by
putting the following in your git repo config
::
[daemon]
uploadarch=true
RPM
~~~
The second example will attempt to install the task via yum/rpm.
::
Currently Restraint does not attempt to set up any repos that you may have
specified in your job.xml. This means that in order for it to install the
above task you must have already configured the task repo on the machine
running restraintd.
The path attribute tells restraint where the task scripts are installed.
Parameters
----------
You can optionally pass parameters to a task via environment variables. The
following snippet from our example would create an environment variable named
'foo' with the value 'bar'.
::
The parameter KILLTIMEOVERRIDE allows you to specify a different max time than
what is specified in the tasks metadata. KILLTIMEOVERRIDE is provided for
compatibility with legacy RHTS (Red Hat Test System).
As of 0.1.40, the parameter RSTRNT_MAX_TIME has been deprecated in favor of KILLTIMEOVERRIDE
because of confusion with RSTRNT_MAXTIME
The parameter RSTRNT_USE_PTY allows you to either enable or disable using a pty
for task execution. Use ``true`` to enable and ``false`` to disable. Setting
this value in the job will override the settings in metadata or testinfo.desc.
.. [#] `Beaker Job XML `_.