The migration is not finished when traffic moves
The final cutover feels like the end. For the operations team it is the start. They now own a platform built by people who are about to leave, in a cloud environment that may be new to them, with new failure modes, new tools and a different bill. Without a runbook, knowledge sits in the heads of the migration engineers, and the first real incident becomes a lesson in where it was not written down.
The runbook is the last deliverable of our cloud migration service, and it draws from every previous stage: the landing zone, network, identity and security baseline.
What good looks like
- Anyone on the team can find the page they need within a minute.
- Each page opens with when to use it, then steps, then how to verify.
- Commands are copy-pasteable and tested against the current environment.
- Alerts link directly to their runbook page.
- Ownership, on-call and escalation are unambiguous.
- Changes to the system update the runbook in the same review.
Structure that works under pressure
We organise by question, not by technology. A typical top level:
- Overview and ownership. Diagram, accounts and subscriptions, who owns each component, how to reach them.
- Access. How people get access, how to use break-glass, how to review permissions.
- Monitoring and alerts. What is monitored, thresholds, and a page per alert.
- Routine operations. Patching, certificate renewal, scaling, log retention, cost review.
- Backup and recovery. What is backed up, how to restore, when it was last tested.
- Deployments and rollbacks. How changes reach production and how to reverse them.
- Incidents. Triage steps, common failures, communication templates.
- Change log. Notable changes and decisions.
For each procedure, a consistent template reduces friction:
## Restore a database from snapshot
**When to use:** accidental data loss, failed deployment migration.
**Who can run it:** on-call engineer with the DatabaseAdmin role.
**Time to complete:** rehearsed at about 25 minutes for the current size.
### Steps
1. Identify the restore point: `aws rds describe-db-snapshots --db-instance-identifier prod-orders`
2. Restore to a new instance: `aws rds restore-db-instance-from-db-snapshot ...`
3. Verify row counts against the expected table list in the checks section.
4. Repoint the application via the parameter store value `/prod/orders/db_host`.
### Verify
Application health endpoint returns 200 and order creation works.
### Roll back this procedure
Repoint to the previous host; do not delete it until sign-off.
### Last tested
2026-09-30 by a different engineer than the author.
The ellipsis stands in for options that depend on your environment. A real page lists them in full. The point is the shape: trigger, permissions, time, steps, verification, escape hatch, test date.
Linking alerts to pages
An alert that says “CPU high” at three in the morning helps nobody. Every alert should carry a link to its runbook page, a statement of customer impact, and a first action. In Prometheus-style rules this is an annotation, and CloudWatch or Azure Monitor alerts can carry the same in their descriptions or action group messages:
- alert: DatabaseStorageLow
expr: aws_rds_free_storage_space_average < 10 * 1024 * 1024 * 1024
for: 15m
labels:
severity: page
annotations:
summary: "Orders database has under 10 GiB free"
runbook_url: "https://runbooks.example.com/database/storage-low"
Our Prometheus alerting examples show more patterns, and the choice of thresholds should reflect your SLOs so pages correspond to real user pain.
Testing the runbook
A document nobody has executed is a hypothesis. We test in two ways. First, a walkthrough: someone from your team follows each key page in a non-production environment, and we record every hesitation. Second, a game day: a realistic failure such as a failed database, an expired certificate or a lost VPN tunnel, handled by your team with us observing. The result is a list of fixes to the runbook and often to the platform, such as a missing permission or an alert that fired too late.
Decisions and trade-offs
Wiki or repository. A wiki is easy to edit and easy to forget. A repository with Markdown ties changes to code review and keeps history. We prefer the repository, rendered to a site, and link from the wiki if your organisation uses one.
Automate or document. If a procedure runs often, turn it into a script or a Systems Manager automation and document how to run it. Documentation for a procedure nobody should do by hand is a smell. Keep manual pages for the rare, judgement-heavy tasks.
Long or short. Short pages that link to details work better than one long manual. Resist writing everything in advance, and start with the tasks most likely to occur.
When you want us to run it. If you do not want to staff on-call, our Managed DevOps team can operate the platform from the same runbook, which we explain in what is managed DevOps.
Keeping it alive
A runbook decays unless someone has a reason to touch it. We add a short review to the team’s regular cadence, assign each section an owner, and make “runbook updated” a line in the pull request template for infrastructure changes. After every incident, the review asks which page helped, which was missing and which was wrong, and the fixes are made the same week.
Common failure modes
- Runbooks written by the migration team for the migration team, assuming context the operators lack.
- Screenshots of consoles that change with the next UI update.
- No named owner, and no review date.
- Credentials pasted into pages. Reference the secrets manager entry, never the value.
- Recovery steps never tested, discovered to be wrong during the incident they were meant for.
Delivery and handover
You receive the runbook in your repository, alert-to-page links, a short training session per team, a completed game day and a 30 day period where we are available for questions. Backup procedures follow the approach in our backup and disaster recovery service.
How to tell it is working
New engineers become useful on-call sooner. Incident reviews cite runbook pages that helped and fixes for the ones that did not. Time to find the right procedure falls, and the runbook shows recent edits rather than a year-old date. For help writing yours, book a consultation.