Runbooks
Operational runbooks for infrastructure and observability config — the things that aren't obvious from code alone and would otherwise get re-derived from scratch next time.
A runbook belongs here when it captures how to carry out or recover from an operation against live infrastructure. If you're documenting why we chose an approach, write an ADR instead. If you're documenting how to use a tool or library day to day, that's a guide.
Infra / SSL
- Amplify Domain Recreation — recovering a stuck or expired Amplify custom domain. From IR-275.
Access / Identity
- AWS Identity Center — Groups, Users & Permission Sets — adding IdC groups, users and permission sets via our CDK repos.
- Airbyte MWAA Client VPN — Connection — connecting to
the
airbyte-mwaa-client-vpn-v2endpoint.
Cost / Observability
- Datadog Cloud Cost Management — how cloud cost data flows into Datadog, allocation tagging, and troubleshooting.
Adding a runbook
Add a Markdown file to this directory, then add it to both the list above and the
Runbooks category in sidebars.ts. Include, near the top:
- When to use this — the symptom or trigger, so someone mid-incident can tell in one read whether they're in the right document.
- Prerequisites — accounts, profiles, and access needed, named explicitly.
- Where the IaC lives, if the thing being operated on is managed by code.
Runbooks go stale faster than ADRs, because they describe live infrastructure rather than a decision made at a point in time. Where a fact was verified against a specific incident, ticket, or date, say so inline — that lets the next reader judge how much to trust it. Open questions are worth keeping in the document rather than dropping; a known gap is more useful than a confident-sounding guess.