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
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 — ready-to-use procedures, responsible
ownership and keeping instructions current.

  * AWS guidance on playbooks — investigation instructions and the
decision to invoke a procedure.

  * Google SRE on emergency response — learning from incidents and
practicing response before an emergency.

hThis page on the web	URL:https://engineer.company/glossary/runbook/	engineer.company	70
