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.
• Creating a New AWS Account with CDK — provisioning a new workload, infra, or sandbox account and wiring it into SSO.
• Airbyte MWAA Client VPN — Connection — connecting to the airbyte-mwaa-client-vpn-v2 endpoint.

Offer sync

• Offer Sync: Enroll an App: giving an app its first offer sync, or moving it from batch to realtime sync, and verifying its inventory.
• EventSync Incident Response: what each EventSync monitor means, how to confirm it, and the break-glass levers.
• Offer Sync: Add a Per-App Metric: getting a new per-app metric from dbt into the Offer API without a one-sided key in the batch diff, using OFFER_API_IGNORED_FIELDS as the bridge and the one deploy order that works.

Elastic Beanstalk

• Migrating an Elastic Beanstalk Environment to PlatformArn: moving a running environment off SolutionStackName so PHP and platform upgrades become one-line changes.

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.