Skip to content

Workflows

A Workflow in DRP is an ordered list of stage names (and optionally direct task, action, or context references) that defines the complete provisioning sequence for a machine. When a workflow is assigned to a machine, DRP advances the machine through each entry in the Stages list in order, running the tasks defined in each stage until the workflow completes or the machine enters a failed state. Workflows are the top-level coordination object: Workflow → Stages → Tasks.

Workflow YAML Structure

YAML
Name: ubuntu-22-04-install
Description: "Full install: discover, install Ubuntu 22.04, configure, finalize"
Stages:
  - discover               # Stage name — run the discover stage first
  - install-ubuntu-22-04   # Install the OS
  - configure-base         # Apply base configuration
  - task:custom-validate   # Direct task reference (prepend "task:")
  - finalize               # Final cleanup stage

The Stages list entries are primarily stage names, but DRP also supports these prefixed forms:

  • task:<name> — run a single task directly without wrapping it in a stage
  • action:<plugin>:<action> — invoke a plugin action
  • context:<name> — switch the runner context for subsequent entries

Creating and Applying Workflows

Bash
# Create a workflow from YAML
drpcli workflows create - < ubuntu-22-04-install.yaml

# Assign the workflow to a machine to start provisioning
drpcli machines workflow <machine-uuid> ubuntu-22-04-install

# Check which stage the machine is currently in
drpcli machines show <machine-uuid> | jq '{Stage:.Stage,Task:.CurrentTask,State:.TaskRunner}'

# Update a workflow's stage list
drpcli workflows update ubuntu-22-04-install \
  '{"Stages":["discover","install-ubuntu-22-04","configure-base","configure-monitoring","finalize"]}'

Prefer Flexiflow Injection Over New Workflows

In general, developers should not create new workflows. The universal pipeline already covers the standard machine lifecycle (discover, hardware, OS install, application). Instead, use the flexiflow injection points built into each Pipeline Element to add custom behavior:

  • universal/<pe-name>-pre-flexiflow — inject stages before the PE's core work
  • universal/<pe-name>-post-flexiflow — inject stages after the PE's core work

For example, to run a custom validation stage after hardware configuration:

Bash
# Inject a custom stage into the post-flexiflow of universal-hardware
drpcli profiles set global param universal/hardware-post-flexiflow \
    to '["my-custom-hardware-validate"]'

This approach keeps customizations isolated in parameters, leaves the upstream PE unchanged, and works correctly across pipeline chaining.

When to Create a Workflow

Create a workflow only when composing existing Pipeline Elements into a site-specific sequence that DRP does not already provide:

Bash
# Thin workflow that composes installed PEs
drpcli workflows create '{
  "Name": "site-specific-deploy",
  "Stages": [
    "universal-discover",
    "universal-hardware",
    "universal-linux-install",
    "my-app-deploy-pe"
  ]
}'

The workflow is a lightweight coordination layer. All the complexity lives in the PEs it references.

See Pipeline Elements for details on building Pipeline Elements.