{"canonical_url":"https://engineer.company/glossary/runbook/","content_markdown":"# Runbook\n\n## What it is\n\nA runbook is a set of tested instructions for carrying out an operating task. It describes when\nsomeone should use it, what they need before starting, how to perform the work and how to recognize\nthe result. An operator may follow it by hand, or it may explain a procedure that automation runs.\nThe task might be a planned certificate renewal, a routine restore test or returning a service to\na known configuration after a change.\n\nThe AWS Well-Architected Framework recommends runbooks for procedures and describes a different\nkind of guide for investigation. Its documents use _runbook_ for the steps of a repeatable task\nand _playbook_ for investigating an issue. Teams use these words differently, so the more useful\nquestion is what the document expects the reader to know. If an operator already knows what operation\nis needed, the instructions can run from a known starting condition to a defined result. If the\noperator still needs to decide which fault has occurred, the document needs observations and decision\npoints before directing them to a procedure.\n\nA runbook can be short while still being complete. It names the relevant system and the environment,\nthe access needed, the person or team responsible, the checks that must pass before changing\nanything and the evidence that shows completion. It should also say when to pause or escalate. A\ncommand that completes and a service that meets its expected behavior are two kinds of evidence.\nThe instructions explain how to obtain the relevant one at each step.\n\n## Why it matters\n\nDuring an interruption, the person available may be familiar with the application but new to the\nparticular tool used for recovery. A useful runbook reduces the work of reconstructing a procedure\nfrom memory. The reader can check the system they are about to change and can see what an expected\nresult looks like before pressing ahead. That is especially valuable in a team that rotates on-call\nduty or relies on several departments to make a recovery happen.\n\nWriting instructions also exposes where the process depends on hidden knowledge. An operator may\nsay that a copy is ready as soon as a job finishes. Someone rehearsing the procedure may discover\nthat the next tool expects a separate permission or that a successful report omits failed records.\nThe published procedure can make this distinction clear. It can also show which parts the team can\nautomate and which parts need a human judgment about the current situation.\n\nThe document's value depends on how it is maintained. A short note beside the system can become\noutdated after a dependency or role changes. The team can keep the runbook with the code or\nconfiguration that defines the procedure, put a responsible owner on it and revise both together\nwhen appropriate. Rehearsal by another person reveals assumptions the author is likely to miss. The\nrehearsal is also an opportunity to verify that the result can be recognized when the usual dashboards\nor network path are unavailable.\n\n## What it looks like in practice\n\nConsider a runbook for periodically proving that a backup of a reporting database can be restored.\nIt starts by naming the report database, the isolated environment and the account approved to read the\nbackup and create the test database. It instructs the reader to confirm the source and the age of\nthe selected backup. It also asks them to check that no live application is pointed at the target.\nThe operator records the exact backup and marks the time before starting the restore.\n\nThe next step directs the operator to the supported restore tool and tells them where its output is\nlogged. When the restore ends, the runbook requires more than a completion message. The reader runs\na known report, compares a small set of expected values and checks the date of the newest restored\nrecord. Missing records, an unexpected source or a failed report require a pause and a contact named\nin the instructions. A successful exercise records elapsed time and leaves no temporary copy or\naccess behind after the planned cleanup.\n\nA second reader then rehearses the procedure with a backup intentionally older than the expected\nrange in the test environment. A good runbook makes the mismatch apparent before the restore starts,\nand the person knows what evidence to retain. After the exercise, the owner corrects unclear steps\nand adds the observed duration to the latest rehearsal record. People working against a recovery\ntime objective can use that duration as evidence about this exercise and its conditions.\n\nEngineer's case on [backups that have actually been restored](/portfolio/backups-that-have-actually-been-restored/)\ndocuments restore-test work and its concerns. It gives a concrete reason to look at restoration\nrather than a backup's successful completion alone. The reporting database checklist in this article\nis an illustrative runbook, with its own sample conditions and outcomes.\n\n## Where it goes wrong\n\n**The steps assume the normal environment is working.** If the main dashboard or identity service is\nunavailable, the operator still needs to locate the procedure and verify prerequisites. Rehearse how\npeople retrieve the instructions and obtain the permitted access under degraded conditions.\n\n**The text says what to click and omits the result.** A changed interface can make a screenshot hard\nto follow. State what the operation should affect and show a recognizable outcome. Include limits\nthat tell the operator to stop, such as a different resource name or data outside the expected range.\n\n**Every situation uses the same procedure.** If different symptoms have several plausible causes,\nfirst establish the condition that makes the runbook applicable. An investigation can assemble the\nevidence for that decision. The runbook then carries out an identified task.\n\n**The procedure is never tested by anyone else.** A second operator can surface missing permissions,\nunexplained terms and steps that silently rely on values from the author's machine. Give that person\na safe scenario and ask them to record where they had to infer what to do.\n\n## Further reading\n\n- [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.\n- [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.\n- [Google SRE on emergency response](https://sre.google/sre-book/emergency-response/) — learning from incidents and practicing response before an emergency.\n\n\u003chttps://engineer.company/glossary/runbook/\u003e\n","date_modified":"2026-11-19T19:18:49Z","description":"What a runbook records, how operators verify each step and how teams keep the instructions usable when conditions change.","formats":{"gemtext":"https://engineer.company/glossary/runbook/index.gmi","gopher":"https://engineer.company/glossary/runbook/gophermap","html":"https://engineer.company/glossary/runbook/","json":"https://engineer.company/glossary/runbook/index.json","markdown":"https://engineer.company/glossary/runbook/index.md","pdf":"https://engineer.company/glossary/runbook/index.pdf"},"kind":"page","language":"en","title":"What is a runbook?","url":"https://engineer.company/glossary/runbook/","version":1}