# Runbook

## What it is

A runbook is a set of tested instructions for carrying out an operating task. It describes when
someone should use it, what they need before starting, how to perform the work and how to recognize
the result. An operator may follow it by hand, or it may explain a procedure that automation runs.
The task might be a planned certificate renewal, a routine restore test or returning a service to
a known configuration after a change.

The AWS Well-Architected Framework recommends runbooks for procedures and describes a different
kind of guide for investigation. Its documents use _runbook_ for the steps of a repeatable task
and _playbook_ for investigating an issue. Teams use these words differently, so the more useful
question is what the document expects the reader to know. If an operator already knows what operation
is needed, the instructions can run from a known starting condition to a defined result. If the
operator still needs to decide which fault has occurred, the document needs observations and decision
points before directing them to a procedure.

A runbook can be short while still being complete. It names the relevant system and the environment,
the access needed, the person or team responsible, the checks that must pass before changing
anything and the evidence that shows completion. It should also say when to pause or escalate. A
command that completes and a service that meets its expected behavior are two kinds of evidence.
The instructions explain how to obtain the relevant one at each step.

## Why it matters

During an interruption, the person available may be familiar with the application but new to the
particular tool used for recovery. A useful runbook reduces the work of reconstructing a procedure
from memory. The reader can check the system they are about to change and can see what an expected
result looks like before pressing ahead. That is especially valuable in a team that rotates on-call
duty or relies on several departments to make a recovery happen.

Writing instructions also exposes where the process depends on hidden knowledge. An operator may
say that a copy is ready as soon as a job finishes. Someone rehearsing the procedure may discover
that the next tool expects a separate permission or that a successful report omits failed records.
The published procedure can make this distinction clear. It can also show which parts the team can
automate and which parts need a human judgment about the current situation.

The document's value depends on how it is maintained. A short note beside the system can become
outdated after a dependency or role changes. The team can keep the runbook with the code or
configuration that defines the procedure, put a responsible owner on it and revise both together
when appropriate. Rehearsal by another person reveals assumptions the author is likely to miss. The
rehearsal is also an opportunity to verify that the result can be recognized when the usual dashboards
or network path are unavailable.

## What it looks like in practice

Consider a runbook for periodically proving that a backup of a reporting database can be restored.
It starts by naming the report database, the isolated environment and the account approved to read the
backup and create the test database. It instructs the reader to confirm the source and the age of
the selected backup. It also asks them to check that no live application is pointed at the target.
The operator records the exact backup and marks the time before starting the restore.

The next step directs the operator to the supported restore tool and tells them where its output is
logged. When the restore ends, the runbook requires more than a completion message. The reader runs
a known report, compares a small set of expected values and checks the date of the newest restored
record. Missing records, an unexpected source or a failed report require a pause and a contact named
in the instructions. A successful exercise records elapsed time and leaves no temporary copy or
access behind after the planned cleanup.

A second reader then rehearses the procedure with a backup intentionally older than the expected
range in the test environment. A good runbook makes the mismatch apparent before the restore starts,
and the person knows what evidence to retain. After the exercise, the owner corrects unclear steps
and adds the observed duration to the latest rehearsal record. People working against a recovery
time objective can use that duration as evidence about this exercise and its conditions.

Engineer's case on [backups that have actually been restored](/portfolio/backups-that-have-actually-been-restored/)
documents restore-test work and its concerns. It gives a concrete reason to look at restoration
rather than a backup's successful completion alone. The reporting database checklist in this article
is an illustrative runbook, with its own sample conditions and outcomes.

## Where it goes wrong

**The steps assume the normal environment is working.** If the main dashboard or identity service is
unavailable, the operator still needs to locate the procedure and verify prerequisites. Rehearse how
people retrieve the instructions and obtain the permitted access under degraded conditions.

**The text says what to click and omits the result.** A changed interface can make a screenshot hard
to follow. State what the operation should affect and show a recognizable outcome. Include limits
that tell the operator to stop, such as a different resource name or data outside the expected range.

**Every situation uses the same procedure.** If different symptoms have several plausible causes,
first establish the condition that makes the runbook applicable. An investigation can assemble the
evidence for that decision. The runbook then carries out an identified task.

**The procedure is never tested by anyone else.** A second operator can surface missing permissions,
unexplained terms and steps that silently rely on values from the author's machine. Give that person
a safe scenario and ask them to record where they had to infer what to do.

## Further reading

- [AWS guidance on runbooks](https://docs.aws.amazon.com/wellarchitected/latest/operational-excellence-pillar/ops_ready_to_support_use_runbooks.html) — ready-to-use procedures, responsible ownership and keeping instructions current.
- [AWS guidance on playbooks](https://docs.aws.amazon.com/wellarchitected/latest/operational-excellence-pillar/ops_ready_to_support_use_playbooks.html) — investigation instructions and the decision to invoke a procedure.
- [Google SRE on emergency response](https://sre.google/sre-book/emergency-response/) — learning from incidents and practicing response before an emergency.

<https://engineer.company/glossary/runbook/>
