Tasks¶
A Task is the smallest discrete unit of work in DRP. When a task is executed on a machine, the runner creates a Job that renders the task's templates into scripts or files and executes them. Tasks are the fundamental execution primitive that all higher-level constructs (stages, workflows) ultimately decompose into.
Each Task contains a list of templates that are rendered at execution time using the machine's parameter context. These templates typically produce shell scripts, configuration files, or other artifacts needed for the task's work. Templates can target specific operating systems via the OS metadata field, allowing a single task definition to work across Linux, Windows, ESXi, and other platforms.
Tasks declare their parameter dependencies through RequiredParams (must be present for execution), OptionalParams (may be used if available), and OutputParams (parameters the task may set during execution). The Prerequisites field lists other tasks that must have already run in the current boot environment before this task can execute.
For tasks that need elevated API access during execution, the ExtraRoles and ExtraClaims fields extend the permissions granted to the job token. This allows tasks to perform privileged operations such as creating machines or modifying other objects. The ExtraDuration field controls how long the generated job token remains valid, with 0 defaulting to 720 hours and -1 meaning approximately three years.
Tasks are contained within Stage objects and create Job objects when executed. They use Param values resolved from the machine's parameter chain including Profile objects.
Metadata¶
| Field | Description |
|---|---|
flow-comment |
Used by UX to provide side-effect information in the triggers flow visualization. |
triggered-by |
Set by DRP when a trigger uses a blueprint to create a work order. |
It can be retrieved in a task using {{get .WorkOrder.Meta "triggered-by"}}. |
Fields¶
| Field | Definition |
|---|---|
| Description | Description is a string for providing a simple description |
| Documentation | Documentation is a string for providing additional in depth information. |
| ExtraClaims | ExtraClaims is a raw list of Claims that should be added to the default set of allowable Claims when a Job based on this task is running. Any extra claims added here will be added after any added by ExtraRoles |
| ExtraClaims/Action | Action is the action taken in the space. e.g. get, list Can be comma separated list or * |
| ExtraClaims/Scope | Scope is the object space. e.g. machines Can be comma separated list or * |
| ExtraClaims/Specific | Specific is the id of the object in the object space. e.g. machine uuid Can be comma separated list or * |
| ExtraDuration | ExtraDuration defines the number of seconds the generated token should be allowed. 0 implies 720 hours. -1 implies "infinite" - well 3 years positvie implies number of seconds |
| ExtraRoles | ExtraRoles is a list of Roles whose Claims should be added to the default set of allowable Claims when a Job based on this task is running. |
| Meta | Meta contains the meta data of the object. The type of this field is a key / value map/dictionary. The key type is string. The value type is also string. The general content of the field is undefined and can be an arbritary store. There are some common known keys: color - The color the UX uses when displaying icon - The icon the UX uses when displaying * title - The UX uses this for additional display information. Often the source of the object. Specific Object types use additional meta data fields. These are described at: https://docs.rackn.io/stable/redirect/?ref=rs_object_metadata |
| Name | Name is the name of this Task. Task names must be globally unique required: true |
| OptionalParams | OptionalParams are extra optional parameters that a template rendered for the Task may use. required: true |
| OutputParams | OutputParams are that parameters that are possibly set by the Task |
| Prerequisites | Prerequisites are tasks that must have been run in the current BootEnv before this task can be run. |
| RequiredParams | RequiredParams is the list of parameters that are required to be present on Machine.Params or in a profile attached to the machine. required: true |
| Templates | Templates lists the templates that need to be rendered for the Task. required: true |
| Templates/Contents | Contents that should be used when this template needs to be expanded. Either this or ID should be set. required: false |
| Templates/EndDelimiter | EndDelimiter is an optional end delimiter. required: false |
| Templates/ID | ID of the template that should be expanded. Either this or Contents should be set required: false |
| Templates/Link | Link optionally references another file to put at the path location. |
| Templates/Meta | Meta for the TemplateInfo. This can be used by the job running system and the bootenvs to handle OS, arch, and firmware differences. required: false |
| Templates/Name | Name of the template required: true |
| Templates/Path | A text/template that specifies how to create the final path the template should be written to. required: true |
| Templates/StartDelimiter | StartDelimiter is an optional start delimiter. required: false |