Skip to content

Universal Runbook

Overview

This diagram provides a high-level description of burnin.

runbook image

What Is a Runbook?

A runbook in DRP is a structured sequence of workflow stages and tasks that drives a machine through a defined operational procedure after the base operating system has been installed. Runbooks encode the steps required to configure software, apply application-level settings, register the machine with external services, and validate the resulting state. They represent the transition from "machine with an OS" to "machine ready for production use."

Unlike a workflow that installs an OS from scratch, a runbook typically assumes the machine is already running and reachable via the DRP agent. This makes runbooks well-suited for post-install configuration, application deployment, and day-2 operations such as patching, compliance remediation, or service reconfiguration.

Runbook Architecture

Runbooks are implemented as DRP workflows — ordered lists of stages, each stage containing an ordered list of tasks. The runbook pattern extends the Universal Workflow structure by using the universal/application parameter to select which runbook to execute. When the universal-application workflow runs, it reads this parameter and chains into the appropriate application-specific stages.

Each stage in a runbook maps to a logical phase of the deployment:

  • Pre-application FlexiFlow — injects operator-defined tasks before the main runbook logic runs, allowing site-specific steps without modifying the core runbook.
  • Application stages — the core steps: package installation, configuration file rendering via templates, service enablement, and external API registration.
  • Post-application FlexiFlow — injects operator-defined tasks after the main application work, enabling validation, monitoring agent install, or notification calls.
  • Callback — notifies external systems (via the callback content pack) that the runbook has started or completed, enabling integration with CMDB, ticketing, or orchestration systems.
  • Workflow chain — hands control to the next workflow in the chain (for example, moving to a "local" boot workflow once configuration is complete).

Task Chaining and Idempotency

Runbook tasks are chained by the DRP task executor: each task runs to completion before the next is started, with the exit code determining whether the chain continues, retries, or fails. Tasks in a runbook should be written to be idempotent — running the same task twice should produce the same result. This is especially important for runbooks that may be re-applied to configure a machine that was already partially configured, or to re-run after a failure.

To achieve idempotency, tasks typically check for the presence of a sentinel parameter (a boolean flag set after successful first-time execution) and skip their work if the flag is already set. The DRP parameter store, accessible to every task via the template system, is the canonical location for this state.

Relationship to Workflows

A runbook is not a distinct DRP object type — it is a design pattern implemented using standard DRP Workflows, Stages, and Tasks. The pattern is:

  1. The machine's universal/application parameter is set to a value (for example, k8s-worker or web-tier).
  2. The universal-application workflow is assigned to the machine.
  3. The workflow reads the application parameter and chains into the application-specific runbook stages.
  4. The runbook stages execute in order, driving the machine to its intended end state.

This layered approach — universal workflow as the outer container, application runbook as the inner logic — allows operators to reuse the universal workflow's callback, FlexiFlow, classification, and chaining infrastructure without reimplementing it for every application.

Read More