External Tasks for Jobs¶

Specifying name and fetch URL for recipe-tasks¶

It is important that a recipe-task always have a sensible name, so that recipe results can be meaningfully displayed even before the recipe starts. This will also avoid backwards compatibility issues with external tools expecting every recipe-task to have a proper task name. Therefore, when a new recipe is submitted Beaker will use the following rules to determine the name of each recipe-task.

If the submitted XML only specifies a name for the task, the task must exist in Beaker’s task library. The recipe-task name is set to the given name. This represents no change from the current Beaker behaviour and preserves compatibility for harness implementations.

<task name="/distribution/reservesys" />

If the submitted XML specifies both a name and a fetch URL, the task need not exist in Beaker’s task library. The recipe-task name is set to the given name, the fetch URL is set to the given URL, and the recipe-task is not associated with any task library entry (even if the name matches a task library entry).

Beaker will treat the fetch URL as an opaque string and does not attempt to validate or fetch it. The details of how to fetch, unpack, and run the task are left up to the harness implementation.

<task name="/distribution/reservesys">
  <fetch url="git://example.com/tasks/reservesys#master" />
</task>

If a fetch URL is specified, a subdirectory may also be specified. This is for cases where the fetch URL points at an archive or source repository which contains multiple tasks. The subdirectory indicates to the harness where it should look to find the task to run. This is represented as a separate attribute in the XML, because URLs do not have a standard mechanism to express paths within an archive or repository.

<task name="/distribution/reservesys">
  <fetch url="git://git.example.org/beaker-core-tasks#master"
         subdir="reservesys" />
</task>

The name="" attribute may be omitted if a fetch URL is specified. In this case there is no associated task library entry. Initially Beaker will set the recipe-task name to the value of the fetch URL combined with the subdirectory, so that it has a distinct and meaningful value by default, but it is expected that the harness will later update the recipe-task name to some “prettier” value (for example, by extracting the name from testinfo.desc).

<task>
  <fetch url="git://git.example.org/beaker-core-tasks#master"
         subdir="reservesys" />
</task>

Fetch URLs in recipe XML¶

When a recipe-task is associated with a task library entry (no fetch URL), the recipe XML served by Beaker will include an <rpm/> element with the details of the RPM from the task library. The harness should install the named RPM using the system package installer. This represents no change from the current Beaker behaviour and preserves compatibility for harness implementations.

<task name="/distribution/reservesys">
  <rpm name="beaker-core-tasks-distribution-reservesys"
       path="/mnt/tests/distribution/reservesys" />
  ...
</task>

When a recipe-task has a fetch URL, the recipe XML served by Beaker will instead contain a <fetch/> element, matching the submitted job XML:

<task name="/distribution/reservesys">
  <fetch url="git://git.example.org/beaker-core-tasks#master"
         subdir="reservesys" />
  ...
</task>

Version for recipe-tasks¶

For recipe-tasks which have an entry in the task library, Beaker will copy the current version from the task library to the recipe-task when the recipe is Scheduled (this is the point at which the task library snapshot is generated). This is the version of the task which should be run (if all goes well).

For recipe-tasks with a fetch URL, the version will be initially empty. Harness implementations can update Beaker with the version of the task which was run. This is particularly important when fetching from source control. For example, a harness implementation might set the version to <branch>@<sha> for a task fetched from git.

Beaker will treat the version as an opaque string. The format of the version string is left up to the harness implementation.

The versions will be displayed with the recipe results in Beaker’s web UI and included in the job results XML.