YAML Reference

A runbook definition consists of two top-level keys: params (optional) and steps (required).

Full Schema

params:
  <param_name>:
    type: string | int | bool | enum   # Required
    required: true | false              # Default: false
    default: <value>                    # Default value if not provided
    description: "Help text"            # Optional
    # Type-specific constraints:
    enum: ["val1", "val2"]              # enum type only
    pattern: "^[a-z]+$"                # string type only (regex)
    min: 0                              # int type only
    max: 100                            # int type only

steps:
  - id: <unique_step_id>               # Required, must be unique
    name: "Human-readable name"         # Required
    action: <action_name>               # Required, must be a registered action
    params:                             # Action-specific parameters
      key: value
      key2: "{{ param_name }}"          # Parameter substitution
      key3: "{{ prev_step.field }}"     # Cross-step reference
    when: "{{ step_id.field > 0 }}"     # Optional conditional
    on_failure: abort | warn | skip     # Default: abort

Parameter Types

Type	JSON Type	Constraints	Example
string	string	pattern (regex)	"nginx.service"
int	number	min, max	50
bool	boolean	--	true
enum	string	enum (list of allowed values)	"SIGTERM"

Substitution Syntax

Parameter References

Use {{ param_name }} to inject a runbook parameter into a step's params:

params:
  unit_name:
    type: string
    required: true

steps:
  - id: restart
    name: "Restart service"
    action: restart_systemd_unit
    params:
      unit: "{{ unit_name }}"

Cross-Step References

Use {{ step_id.field }} to reference a previous step's output:

steps:
  - id: read_logs
    name: "Read recent logs"
    action: read_file_tail
    params:
      path: "/var/log/syslog"
      lines: 50
  - id: report
    name: "Check line count"
    action: read_file_head
    params:
      path: "/var/log/syslog"
      lines: "{{ read_logs.lines_read }}"

Each action returns a structured output map. The available fields depend on the action -- see the Action Reference for return fields.

String Interpolation

When a {{ ref }} is the entire value, the resolved value keeps its original type (int, bool, etc.). When embedded in a larger string, it is converted to a string:

# Entire value -- lines will be an int
lines: "{{ log_lines }}"

# Embedded in string -- becomes a string
path: "/var/log/{{ service_name }}/access.log"

When Conditions

The when field controls whether a step executes. If the condition evaluates to false, the step is skipped.

Comparison Operators

Supported operators: ==, !=, >, <, >=, <=

# Numeric comparison
when: "{{ check.lines_read > 0 }}"

# String equality
when: "{{ check_status.status == active }}"

# Not equal
when: "{{ check.error != }}"

Boolean References

A bare reference evaluates as truthy:

when: "{{ check.content }}"  # True if content is non-empty

Evaluation Rules

• The left-hand side must be a {{ step_id.field }} reference.
• The right-hand side is a literal value (no template syntax).
• If the referenced step has not yet executed (or was skipped), the condition evaluates to false.
• If there is no operator, the value is evaluated as a boolean (strings: non-empty = true; booleans: as-is).

On Failure Semantics

Value	Behavior
abort	Stop the runbook immediately. Final status: failed. This is the default if omitted.
warn	Log the error, mark the step as failed, and continue to the next step.
skip	Mark the step as skipped and continue.

If any step has status failed at the end of execution, the overall execution status is failed even if other steps succeeded.

Complete Example

params:
  service:
    type: string
    required: true
    description: "Systemd service to investigate and restart"
  log_lines:
    type: int
    default: 100
    min: 10
    max: 1000

steps:
  - id: check_logs
    name: "Read recent logs"
    action: read_file_tail
    params:
      path: "/var/log/syslog"
      lines: "{{ log_lines }}"

  - id: run_healthcheck
    name: "Run healthcheck"
    action: run_healthcheck
    on_failure: warn

  - id: restart_service
    name: "Restart the service"
    action: restart_systemd_unit
    when: "{{ check_logs.lines_read > 0 }}"
    params:
      unit: "{{ service }}"

  - id: verify_logs
    name: "Check logs after restart"
    action: read_file_tail
    params:
      path: "/var/log/syslog"
      lines: 20

This runbook:

1. Reads the last N lines of syslog.
2. Runs a healthcheck (continues even if it fails).
3. Restarts the specified service only if step 1 found log lines.
4. Reads logs again to verify the restart.