WorkOrder¶
DRP implements an extension to the workflow system that allows for execution of sets of tasks as a unit after the initial provisioning of the machine. These WorkOrder objects can scheduled or triggered to run.
To simplify building work orders, a blueprint can be created to allow for easy replication of work orders across machines.
Fields¶
| Field | Definition |
|---|---|
| Archived | Archived indicates whether the complete log for the async action can be retrieved via the API. If Archived is true, then the log cannot be retrieved. required: true |
| Blueprint | Blueprint defines the tasks and base parameters for this action required: true |
| Context | Contexts contains the name of the current execution context. An empty string indicates that an agent running on a Machine should be executing tasks, and any other value means that an agent running with its context set for this value should be executing tasks. |
| CreateTime | CreateTime is the time the work order was created. This is distinct from StartTime, as there may be a significant delay before the workorder starts running. |
| CurrentTask | The index into the Tasks list for the task that is currently running (if a task is running) or the next task that will run (if no task is currently running). If -1, then the first task will run next, and if it is equal to the length of the Tasks list then all the tasks have finished running. required: true |
| EndTime | EndTime The time the async action failed or finished or cancelled. |
| Filter | Filter is a list filter for this WorkOrder |
| JobExitState | The final disposition of the current job. Can be one of "reboot","poweroff","stop", or "complete" Other substates may be added as time goes on |
| JobResultErrors | ResultErrors is a list of error from the task. This is filled in by the task if it is written to do so. This tracks results without requiring job logs. |
| JobState | The state the current job is in. Must be one of "created", "failed", "finished", "incomplete" |
| Machine | Machine is the key of the machine running the WorkOrder swagger:strfmt uuid |
| 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 |
| Params | Params that have been directly set on the Machine. |
| Profiles | Profiles An array of profiles to apply to this machine in order when looking for a parameter during rendering. |
| Runnable | Runnable indicates that this is Runnable. |
| Stage | The stage that this is currently in. |
| StartTime | StartTime The time the async action started running. |
| State | State The state the async action is in. Must be one of "created", "running", "failed", "finished", "cancelled" required: true |
| Status | Status is a short text snippet for humans explaining the current state. |
| TaskErrorStacks | This list of previous task lists and current tasks to handle errors. Upon completing the list, the previous task list will be executed. This will be capped to a depth of 1. Error failures can not be handled. |
| TaskErrorStacks/CurrentJob | CurrentJob is the job that presents this task stack swagger:strfmt uuid |
| TaskErrorStacks/CurrentTask | CurrentTask is the index in the task list in a previous errored task. |
| TaskErrorStacks/TaskList | TaskList is the task list from a previous errored task. |
| Tasks | The current tasks that are being processed. |
| Uuid | Uuid is the key of this particular WorkOrder. required: true swagger:strfmt uuid |
Work Orders¶
The work order connects a set of tasks, parameters, and profiles to a machine.
When created, the work order is associated with a machine. If the machine is in work order mode, the runner on that machine will pick up the work order and execute the task list on that work order. As the runner executes the tasks, the system accumulates job objects to track the results.
If a task fails, the work order fails. Work orders are not intended to be restarted. They can be cloned and rerun. These are intended to be trackable, results-oriented actions.
Currently, each runner will run one work order at a time, but this is not required and may change in the future.
The task list on a work order can initially contain stages by prepending stage:<name of stage> and should not contain bootenv changes or context changes.
State¶
The WorkOrder has a state and can only be operated based upon a state.
| Field | Description |
|---|---|
created |
This is the starting state for a created work order. This means the work order is on the machine, but not started yet. |
running |
The WorkOrder has been picked up by a runner and is running. |
failed |
This WorkOrder has a failed task and has stopped. |
finished |
This WorkOrder has completed all tasks successfully. |
cancelled |
This WorkOrder was cancelled before completion of the tasks. |
Work orders must me moved to one of the final three states to delete or remove the work order.
Additionally, the WorkOrder Status field contains information about what is going on with the WorkOrder. This is generally a failure message.
Jobs¶
A job is used to track the execution history of tasks against a specific machine. The job object contains a reference to the owning machine and the owning work order. This allows for searching and filtering by machine and work order.
Blueprint¶
The blueprint defines a set of tasks, parameters, and profiles that act as the basis for a work order.
When a work order is created that reference a blueprint, the Params and Profiles fields are added to the machine's template render process. These are used before the machine's parameters, but after the work order's own params and profiles.
The blueprint has a task list that will get expanded when the work order is picked up to start execution. The task list on a blueprint may additionally include stages by prepending stage:<stage name>. The task list should not include bootenv changes.
TriggerProvider¶
A trigger provider defines a trigger type. The object defines the required and optional parameters for using the trigger. The trigger provider defines is it is a URL-based trigger. If the NoURL field is set to true, the trigger provider is an internal DRP trigger. The Method field, if specified, defines the HTTP request type of the trigger. If unspecified, anything is allowed and the trigger will decide if the method is allowed.
The triggers plugin provides many webhook triggers. For a trigger provider that doesn't have NoURL set to true, the system will create the following URL, https://IP:APIPORT/webhooks/\<TriggerProviderName>. By default, all methods are allow. The URL-based trigger is assumed to be handled by a plugin action on the system object. The plugin providing the trigger provider support should provide an action on the system object named the same as the trigger provider.
The trigger provider has profiles and parameters associated with it. These are used to define the trigger operations and customization. They are not applied to the work order.
There are two embedded trigger providers:
CronTrigger¶
This defines a trigger type that will generate a trigger bounded by a cron tab string.
The cron-trigger/time-string parameter defines a crontab, 5-element string that defines when the trigger will fire.
EventTrigger¶
This defines a trigger type that will generate a trigger based upon a matching event.
The event-trigger/event-match parameter defines an event matcher that follows the scope, action, specific format of the event. This is the dot separated with comma separated elements. e.g. machines.update,create,save.* would match any machine event that is of action create, update, or save.
The event-trigger/event-object-match parameters optionally defines an await drpcli-style string that will allow for matching on the object field of the event. Await allows for And / Or / Not logical operators along with the Eq function to create a complex test structure. This example would match if the state of the event was finished, failed, or cancelled.
Trigger¶
A trigger defines the specific details of how the trigger operates and the resulting set of work orders that result from the trigger. Additionally, the trigger can assign work orders immediately to a specific set of machines, or the machine assignment can be deferred until the machines are ready to accept new work.
There are three parts to a trigger:
Trigger Definition¶
The first part is the trigger definition. The following fields define how the trigger operates:
| Field | Definition |
|---|---|
Name |
Defines the trigger\'s key in the DRP data system. |
TriggerProvider |
Defines the type of Trigger |
Enabled |
Defines if the trigger is enabled |
Params |
Defines a set of parameters that alter what triggers. E.g. the crontab string for the CronTrigger |
Profiles |
Defines a list of profiles that also can be used to define parameters for the trigger |
These parameters control how the trigger works. For example, the event-trigger provider uses the event-trigger/event-match parameter to define which events will invoke the trigger. These parameters are placed in the Params field or in a profile attached to the trigger.
Triggers are often delivered in content packs as read-only objects. This makes turning the on and off impossible with the Enabled field. The Enabled field represents the default state of the trigger. This can be overridden by the global parameters trigger/<name-of-trigger>-enabled or trigger/<name-of-trigger>-disabled. The disabled parameter is higher precedence than the enabled parameter. Either parameter overrides the Enabled field. These parameters can only be specified in the global profile and not in sub-profiles or parameter defaults.
Trigger Scope¶
The second part is the Trigger scope. The following fields define what the trigger show act upon:
- Filter - this is a DRP filter string to limit the scope of machines that should be applied. If the filter is empty, the machines list is [Runnable=true]{.title-ref} and [WorkOrderMode=true]{.title-ref} still applied.
- AllInFilter - This boolean indicates if all the machines should receive a WorkOrder. Default is false.
- FilterCount - This defaults to 1. If AllInFilter is not set to true, then this limits the WorkOrders to be created.
- QueueMode - This boolean indiciates if the WorkOrders should be created without a Machine specifically assigned. This defers assignment until the Machines are ready to handle the work.
The Filter limits the machines to be triggered. Only machines that are Runnable and in WorkOrderMode are eligible for WorkOrders.
The Filter field can also use the rendering system to generate its value. The rendering of the field is restricted to functions that will work against the global profile. See Template for template functions. In general these should be restricted to parameter lookup functions. Here are some example strings.
Using the API or drpcli to test filter matching is useful to determine the scope of the trigger. See Filter Syntax.
Trigger Work Orders #{rs_trigger_work_orders}¶
The third part is the Trigger Work Order definition. The following fields define what the WorkOrder will look like:
- Blueprint - This defines the Blueprint object for the WorkOrder.
- WorkOrderParams - These are parameters that should initialize the WorkOrder\'s Params field.
- WorkOrderProfiles - These are profiles that should initialize the WorkOrder\'s Profiles field.
- StoreDataInParameter - If this string parameter is defined, the data of the trigger will be stored on the WorkOrder in that parameter.
- MergeDataIntoParams - If this boolean parameter is true, the data of the trigger will be merged into the WorkOrder\'s Params field.
The combination of the fields will be used to create WorkOrder for each machine that machines the filter set of parameters.
Execution Models¶
With the addition of WorkOrders, there are two additional execution models to consider when building and planning infrastructure management.
The initial model revolved around provisioning and building up a machine. This is the traditional execution of DRP with extensions into Cloud infrastructure and logical components like clusters. Switch and storage provisioning through contexts fall into this model as well.
When used with Cluster and Resource Broker, Machine as Service can allow for operating and maintaining specific services.
When used with Context and Trigger Definition, the system can be used to operate a CI/CD pipeline like system.
All execution models can exist at the same time with a single DRP environment.
Machine as Service¶
Once a Machine, Cluster, or ResourceBroker has been provisioned, that system can be placed in WorkOrderMode. This will cause the system not run workflows anymore and switch the WorkOrder execution mode, only WorkOrders will be processed. The goal is to operate those systems as service with Blueprints acting as defined actions to take through WorkOrders.
For example, a machine that represents a switch might use WorkOrderMode to handle port configuration changes as needed based upon other system\'s needs. A cluster that represents a Kubernetes Cluster might use WorkOrderMode to manage applications and other cluster management functions after initial provisioning. Blueprints could be created with tasks and initial parameters needed to take those actions. WorkOrders would be created against these system that other WorkOrders or Workflows could use to handle configuration/state changes.
In this case, the Machine / Cluster / ResourceBroker objects continue to represent an element in the data center that is being managed.
Orchestrated Tasks¶
When a Trigger is has QueueMode set to true, the Trigger operates as a deferred WorkOrder queue where the Filter field is the queue definition. This allows these triggers to operate like a pool of runners waiting to do jobs as they arrive. This is subtlely different than the Machine as Server model. The runners, grouped by the filter, are not specifically requested, but operate more anonymously.
CI/CD Pipelines¶
With the introduction of Triggers and WorkOrders, the DRP environment can now act as a general action execution environment. This model matches a more worker / action model instead of a managed system environment.
In this execution model, a set of worker are started with tags. These worker could be Machines, Clusters, or ResourceBrokers that are backed by physical, virtual, or containers. These specified workers run WorkOrders generated by Triggers to manage the whole set of systems. This is NOT necessarily used to manage infrastructure elements directly.
Some examples:
- A Blueprint could be written to handle repackaging content based upon a trigger from gitlab to rebuild and redeploy system components.
- A Blueprint could be written to do heartbeat validation of a machine upon a cron-based trigger to monitor components.