Stages¶

A Stage is the mid-level unit of the DRP provisioning pipeline, sitting between a Workflow (an ordered list of stage names) and a Task (an atomic script). A Stage groups a set of tasks into a logical step, optionally constrains them to a particular BootEnv, declares the parameters the stage needs, and controls whether the machine should reboot on entering the stage. Understanding stage construction is essential for writing reliable content packs.

Stage YAML Structure¶

The following annotated example shows the key fields in a stage definition:

Name: configure-os              # Required. Globally unique stage name.
Description: "Post-install OS configuration"
BootEnv: local                  # The bootenv the machine must be in to run this stage.
                                # Leave empty to run in whatever bootenv is current.
Reboot: false                   # If true, DRP triggers a reboot when entering this stage.
RunnerWait: true                # Deprecated; always treated as true. Leave at true.
Tasks:
  - set-hostname                # Tasks run in order. All must complete before advancing.
  - configure-ntp
  - configure-dns
  - harden-ssh
RequiredParams:
  - dns/servers                 # DRP will fail the job if these are not present.
  - ntp/servers
OptionalParams:
  - ssh/authorized-keys         # Used if present; no error if missing.
OutputParams:
  - os/configured               # Parameters this stage may set for downstream consumers.
Profiles:
  - base-security               # Profiles applied to the machine when entering this stage.
Params:
  dns/search-domain: "example.com"   # Inline param defaults for this stage.

The BootEnv Field¶

BootEnv controls the boot environment the machine must be in before the stage's tasks run. Common values are:

• "" (empty) — stage runs in whatever bootenv is currently active; no boot change occurs
• local — machine boots from its local disk; used for post-install configuration stages
• sledgehammer — machine netboots into the DRP discovery/runner environment
• A custom bootenv name — DRP will change the machine's bootenv and trigger a reboot if Reboot: true

If BootEnv is set and the machine is already in that bootenv, DRP does not reboot unless Reboot: true is explicitly set.

Task Ordering and Prerequisites¶

Tasks in a stage run sequentially in the order listed under Tasks. If any task fails, the stage stops and the machine enters a Failed state (unless the task is marked optional via a task-level flag). Do not rely on task ordering across stages — each stage should be self-contained.

Tasks can include special prefixed directives beyond simple task names:

• action:<plugin>:<action> — invoke a plugin action instead of running a script
• chroot:<path> — change the chroot context for subsequent tasks
• bootenv:<name> — switch the machine's bootenv mid-stage (rare; prefer stage BootEnv field)
• context:<name> — switch the runner context for subsequent tasks

Tasks:
  - prepare-disk
  - action:ipmi:set-boot-order   # Call the IPMI plugin's set-boot-order action
  - install-os
  - context:local-runner         # Switch to a local runner context for post-install tasks
  - configure-network

Declaring Required vs. Optional Parameters¶

Parameters declared in RequiredParams cause a pre-flight check failure if they are not present on the machine (directly or via an attached profile) before any task in the stage runs. Use RequiredParams for anything the stage cannot function without.

Parameters in OptionalParams serve as documentation — they tell operators which additional parameters can be set to influence this stage's behavior without being mandatory. The build system and UX surfaces these to help operators configure machines correctly.

OutputParams declares what parameters this stage may write. This is informational but enables downstream tooling to know what data will be available after the stage completes.

Common Pitfalls¶

• Missing BootEnv mismatch: If BootEnv is set to local but the machine has not yet had an OS installed, the stage will fail. Sequence stages carefully in the parent workflow.
• Task name typos: DRP validates stage YAML on creation and will reject unknown task names. Run drpcli stages create - < stage.yaml and check for validation errors before adding the stage to a workflow.
• Circular dependencies: Tasks have a Prerequisites field; stages do not. Do not try to implement cross-stage dependencies — use workflow ordering instead.
• Side-effect coupling: Avoid writing stages where task N assumes task N-1 left a file on disk. Use DRP parameters (via drpcli machines set) as the communication channel between tasks so that retries work correctly.

To create or update a stage:

# Create from YAML
drpcli stages create - < configure-os.yaml

# Update an existing stage's task list
drpcli stages update configure-os '{"Tasks":["set-hostname","configure-ntp","configure-dns","harden-ssh","validate-config"]}'

# Validate the stage object
drpcli stages show configure-os | jq '.Errors'