{
  "id": "runbook",
  "title": "Runbook",
  "lang": "en",
  "source_lang": "en",
  "summary": "A runbook is a documented or executable procedure for performing an operational task, maintaining a computing service, or responding to a known failure.",
  "category": "computer-science",
  "subcategory": "software",
  "type": "concept",
  "aliases": [
    "Run book",
    "Operations runbook",
    "Operational runbook"
  ],
  "generated_at": "2026-11-05",
  "model": "pro/gpt-6.1-sol",
  "url": "https://aiwiki.page/en/runbook/",
  "translations": {
    "zh-Hans": {
      "url": "https://aiwiki.page/zh/runbook/",
      "json": "https://aiwiki.page/zh/runbook.json"
    }
  },
  "sections": [
    {
      "heading": "",
      "text": "A runbook is a documented or executable procedure for operating, maintaining, or restoring a computing system. It specifies the conditions under which a task applies, the actions to perform, and the checks needed to determine whether those actions succeeded. Runbooks are a form of software documentation used for routine administration, scheduled maintenance, and incident response. They may be followed manually, executed automatically, or combine automated steps with human decisions and approvals."
    },
    {
      "heading": "Scope and purpose",
      "text": "A runbook translates operational knowledge into a repeatable procedure. Rather than explaining only how a system is designed, it describes how to carry out a particular task in a particular operational context. Examples include restarting a service, renewing a certificate, restoring a database, replacing a failed server, or investigating a recurring alert.\n\nThe term can refer either to a single procedure or to a collection of procedures for a service. There is no universal format: a runbook may be a page in a wiki, a document stored alongside application code, or a workflow executed by an automation platform.\n\nIts principal purposes include:\n\n- Consistency: making the sequence of actions and their expected results explicit.\n- Knowledge transfer: preserving procedures that would otherwise depend on individual experience.\n- Operational coordination: identifying responsibilities, approvals, and escalation paths.\n- Risk control: documenting prerequisites, potentially disruptive actions, and recovery options.\n- Traceability: providing a basis for recording which procedure was used and what happened.\n\nThese benefits depend on the procedure being accurate and applicable to the current system. Documentation alone does not establish that an operation is safe."
    },
    {
      "heading": "Relationship to other operational documents",
      "text": "Runbooks overlap with several other forms of operational documentation, but their emphasis differs.\n\nA standard operating procedure often describes a recurring organizational process, including responsibilities and policy requirements. A runbook usually provides more system-specific execution detail. The distinction is not standardized, and some organizations use the terms interchangeably.\n\nAn incident playbook commonly addresses a broader scenario: how to classify an incident, coordinate responders, communicate with stakeholders, and choose a response strategy. A runbook may supply the concrete technical procedure invoked at one stage of that playbook. In practice, “playbook” and “runbook” are also sometimes used as synonyms.\n\nA checklist primarily helps verify that required items have not been overlooked. A runbook can include checklists but generally also describes actions, expected observations, and branches for different outcomes.\n\nAn architecture document explains system structure and dependencies. A runbook draws on that information but focuses on execution. Similarly, a disaster recovery plan may establish recovery priorities and coordination arrangements while delegating individual restoration tasks to runbooks."
    },
    {
      "heading": "Typical contents",
      "text": "An effective runbook identifies not only what to do but also when the procedure is inappropriate. Common elements include:\n\nElement | Function\nPurpose and scope | Defines the task, affected service, and intended outcome\nEntry conditions | Identifies the alert, request, or system state that justifies execution\nOwnership | Names the team or role responsible for maintaining the procedure\nPrerequisites | Specifies required permissions, tools, connectivity, and system conditions\nParameters | Identifies environment-specific inputs, such as service names or resource identifiers\nProcedure | Gives ordered actions and conditional branches\nExpected results | Describes the observable result of each significant action\nSafety boundaries | Identifies disruptive steps, approval requirements, and stopping conditions\nRecovery actions | Explains rollback, compensating actions, or escalation\nCompletion criteria | Defines how successful completion is established\nRevision information | Records applicable versions, reviews, and validation history\n\nCommands need enough context to distinguish, for example, a production environment from a test environment. Where a command changes state, the procedure may also explain its consequences and whether repeating it is safe.\n\nCompletion criteria are especially important. A command returning a successful exit status does not necessarily mean that the service has recovered. Verification may require an application-level request, confirmation of data integrity, or observation over a defined period."
    },
    {
      "heading": "Manual, automated, and hybrid runbooks",
      "text": "Manual runbooks\n\nA manual runbook is interpreted and carried out by an operator. It can accommodate judgment, incomplete evidence, and unusual circumstances, but its effectiveness depends on clear instructions and the operator’s access and understanding.\n\nManual procedures often separate diagnostic observations from state-changing actions. This distinction helps prevent an investigation step from unexpectedly modifying the system.\n\nAutomated runbooks\n\nAn automated runbook expresses some or all of the procedure as executable logic. It can invoke scripts, management tools, or an application programming interface to inspect and change resources. Automation may run on a schedule, respond to an event, or be initiated by an authorized user.\n\nAn automated runbook is more than a list of commands when it also manages inputs, dependencies, execution state, branching, failure handling, and result collection. Some products use runbook specifically for such an executable automation artifact.\n\nAutomated execution makes repeated tasks more consistent, but also makes errors repeatable. Relevant design properties include:\n\n- Input validation: rejecting missing, malformed, or inappropriate parameters.\n- Bounded execution: defining timeouts and limits on retries.\n- Repeatability: handling retries without unintentionally duplicating changes.\n- Concurrency control: preventing conflicting executions against the same resource.\n- Failure handling: stopping or choosing an explicit alternative when a step fails.\n- Execution records: retaining the inputs, actions, and results needed for review.\n\nIn distributed systems, partial failure complicates these properties. A request may succeed remotely even if the caller never receives confirmation. Blindly repeating the request can therefore produce an unintended second operation.\n\nHybrid runbooks\n\nHybrid runbooks automate well-defined actions while retaining human decisions at important boundaries. A workflow might gather diagnostic evidence automatically, request approval before changing production resources, and then perform post-change checks.\n\nThis arrangement can reduce repetitive work without treating every operational decision as mechanically determinable."
    },
    {
      "heading": "Applications",
      "text": "Runbooks support both routine operations and exceptional events.\n\nMaintenance procedures cover activities such as software updates, certificate renewal, resource resizing, and scheduled restarts. They may include service-impact estimates and coordination requirements.\n\nIncident procedures address recognizable symptoms or failure modes. An alert about rising request failures, for example, may lead first to checks that distinguish application errors from dependency failures. A runbook need not assume that the alert itself identifies the root cause.\n\nBackup and recovery procedures describe how to create, validate, and restore backups. For database restoration, successful execution generally requires more than copying files: the procedure must account for the database’s recovery mechanism and the intended recovery point.\n\nSecurity procedures can cover account revocation, evidence collection, or credential replacement. Their execution must respect access control and evidence-handling requirements.\n\nInfrastructure procedures manage resources in cloud computing environments or physical facilities. They can complement infrastructure as code: configuration definitions describe intended infrastructure, while a runbook describes the controlled process for applying changes or responding when actual conditions differ from expectations."
    },
    {
      "heading": "Illustrative procedure structure",
      "text": "A runbook for investigating an unhealthy application instance might contain the following stages:\n\n- Confirm applicability. Verify the affected service, environment, and observed symptom.\n- Assess impact. Determine whether the fault affects one instance or multiple instances.\n- Collect evidence. Preserve relevant logs, recent change information, and health-check results.\n- Check dependencies. Determine whether the apparent instance failure originates elsewhere.\n- Choose a branch. Escalate a widespread failure or proceed with an approved instance-level action.\n- Perform the action. Remove the affected instance from traffic before restarting it, where the system supports this operation.\n- Verify recovery. Check application behavior before returning the instance to normal service.\n- Record the outcome. Document actions, observations, and any departure from the procedure.\n\nThis is a structural example rather than a universally applicable recovery sequence. Restarting an instance may destroy diagnostic evidence or worsen an underlying capacity problem, so the appropriateness of that action depends on the system."
    },
    {
      "heading": "Maintenance and validation",
      "text": "Runbooks change as systems, dependencies, permissions, and operating practices change. An accurate procedure can become obsolete even when its own text has not been edited.\n\nMaintenance commonly includes assigning an owner, reviewing procedures after relevant system changes, and incorporating findings from incidents and recovery exercises. Storing runbooks in version control allows revisions to be tracked and reviewed through processes such as code review.\n\nValidation can include command checks, controlled execution in a test environment, simulated incidents, and restoration exercises. Each provides different evidence. A script passing a syntax check does not demonstrate that it restores service, while success in a test environment does not establish equivalence with production conditions.\n\nOperational availability also matters. A runbook stored only inside the service it is intended to recover may become inaccessible during an outage. Dependencies on identity systems, network access, and documentation platforms therefore form part of the procedure’s own operational assumptions."
    },
    {
      "heading": "Limitations and security considerations",
      "text": "Runbooks encode known procedures, not complete knowledge of every possible failure. Rigidly following a procedure despite contradictory evidence can compound an incident. Explicit stopping conditions and escalation paths help distinguish a bounded procedure from an open-ended troubleshooting guide.\n\nAutomation can amplify a mistaken assumption across many resources. Approval gates, limited execution scope, and staged execution reduce exposure, but do not eliminate the need to validate the underlying logic.\n\nRunbooks may also contain sensitive operational information. Credentials are generally referenced through controlled retrieval mechanisms rather than embedded directly in documentation or scripts. Automated execution identities can be restricted according to least privilege, while logs need protection against disclosure of secrets.\n\nRollback has limits as well. Reverting a configuration change is not equivalent to reversing all its effects: deleted data, externally delivered messages, or incompatible database changes may require restoration or compensating actions. A runbook’s recovery section must distinguish these cases rather than assume that every completed step has a simple inverse."
    }
  ],
  "links": [
    "software-documentation",
    "incident-response",
    "database",
    "wiki",
    "disaster-recovery",
    "application-programming-interface",
    "distributed-computing",
    "data-backup",
    "access-control",
    "cloud-computing",
    "infrastructure-as-code",
    "version-control",
    "code-review",
    "least-privilege"
  ],
  "sources": [],
  "license": "https://creativecommons.org/licenses/by/4.0/"
}