How to Write an ADR for a Cloud Migration Decision

An Architecture Decision Record (ADR) documents important architectural decisions — what was decided, why, what alternatives were considered, and what trade-offs were accepted. Cloud migration decisions are high-stakes: they affect cost, reliability, security, and team capability for years. They deserve a clear, auditable record. This guide walks through writing an ADR specifically for cloud migration scenarios.

What Is an ADR?

An Architecture Decision Record (ADR) is a short document that captures:

1. The decision — what architectural choice was made
2. The context — what problem or forces led to this decision
3. The options — what alternatives were evaluated
4. The rationale — why this option was chosen over the others
5. The consequences — what the decision enables and what it costs

ADRs are stored alongside code (often in docs/decisions/ or an adr/ folder), version-controlled, and never deleted — only superseded by newer ADRs.

“The new team member asked why we don’t use Kubernetes for the batch jobs. I pointed them to ADR-012 — it explains the decision, the alternatives we evaluated, and why we chose ECS Fargate.”

ADR Format for Cloud Migration

Standard Header

# ADR-[NUMBER]: [TITLE]

**Status**: [Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
**Date**: [YYYY-MM-DD]
**Deciders**: [Names or teams involved]
**Technical Story**: [Optional link to ticket/RFC]

Section 1: Context and Problem Statement

Describe the situation that requires a decision. Be specific about the constraints and forces at play.

What to include:

• Current state (what exists now)
• The problem driving the decision
• Key constraints (timeline, budget, team capability, compliance)
• What happens if we don’t decide

Example:

## Context and Problem Statement

The legacy ordering service currently runs on self-managed bare-metal servers
in our on-premises data centre. The hardware is approaching end-of-life (Q4 2026),
and the data centre lease expires in Q2 2027.

We need to decide the target deployment platform for the ordering service
migration to meet the Q4 2026 decommissioning deadline.

**Constraints:**
- The ordering service processes ~200 orders/minute peak with strong
  latency requirements (p99 < 300ms)
- The team has limited Kubernetes experience (1 of 5 engineers has K8s certification)
- Budget: cloud migration budget is €15,000 for the migration project
- Compliance: SOC 2 Type II and PCI DSS Level 2 requirements apply

Section 2: Decision Drivers

List the criteria that matter most for this decision — ranked or grouped by importance.

## Decision Drivers

1. **Reliability** — 99.9% availability SLA required
2. **Team capability** — solution must be operable by current team without
   significant upskilling investment
3. **Cost** — must stay within the agreed cloud budget
4. **Time to production** — migrated service must be live by Q3 2026
5. **Compliance** — PCI DSS and SOC 2 controls must be preserved or improved

Section 3: Considered Options

List every option you seriously evaluated. Be fair to each option — don’t strawman alternatives.

## Considered Options

1. **AWS ECS with Fargate** — serverless container orchestration on AWS
2. **AWS EKS (Kubernetes)** — managed Kubernetes on AWS
3. **AWS EC2 with Auto Scaling** — conventional VM-based deployment on AWS
4. **Google Cloud Run** — serverless container platform on GCP
5. **Lift and shift to AWS EC2** — direct migration without re-architecture,
   then optimise later

Section 4: Decision Outcome

State clearly what was decided and why.

## Decision Outcome

**Chosen option: AWS ECS with Fargate**

Rationale: ECS Fargate meets all five decision drivers with the best risk profile
given team capabilities and the Q3 2026 deadline. It avoids the complexity and
operational overhead of Kubernetes while providing full container orchestration,
auto-scaling, and IAM integration for PCI DSS compliance.

Section 5: Pros and Cons of Each Option

This is the analytical core of a good ADR — it shows the reasoning was thorough.

## Option Analysis

### Option 1: AWS ECS Fargate
**Pros:**
- No node management overhead — serverless container execution
- Native integration with AWS IAM, Secrets Manager, CloudWatch
- Faster team adoption than Kubernetes (lower learning curve)
- Strong compliance tooling through existing AWS services
- Cost predictable — pay per task execution

**Cons:**
- Vendor lock-in: ECS API is AWS-specific
- Less portable than Kubernetes workloads
- Some advanced scheduling features require Kubernetes

### Option 2: AWS EKS (Kubernetes)
**Pros:**
- Industry-standard orchestration — portable workloads
- Rich ecosystem of tooling and patterns
- Potential for multi-cloud strategy later

**Cons:**
- Only 1 of 5 engineers has Kubernetes experience
- EKS control plane has additional cost
- Higher operational complexity — upgrades, node group management
- Risk: migration deadline likely to slip given skill gap

### Option 3: EC2 with Auto Scaling
**Pros:**
- Well understood by team
- Maximum control over runtime environment

**Cons:**
- OS patching, security updates, and AMI management required
- Less efficient than serverless containers
- Slower scaling response

### Option 4: Google Cloud Run
**Pros:**
- Excellent serverless developer experience
- Competitive pricing

**Cons:**
- Organisation is standardised on AWS
- GCP migration would require parallel IAM, networking, and compliance work
- Not feasible within timeline

### Option 5: Lift and Shift (EC2)
**Pros:**
- Fastest to execute
- Least application change required

**Cons:**
- Takes on the same operational debt in cloud as on-premises
- Does not meet cost efficiency goals
- No improvement to reliability or scalability

Section 6: Consequences

Document what this decision enables, prevents, and costs.

## Consequences

**Positive:**
- Team can deliver migration by Q3 2026 without significant upskilling
- PCI DSS controls map cleanly to ECS + AWS managed services
- Operating cost estimated at 40% below current co-location cost
- Auto-scaling eliminates manual capacity planning

**Negative:**
- Creates AWS dependency for the ordering service
- Teams wanting to move to Kubernetes in future will need to re-architect
- ECS tooling and IaC patterns need to be established (accepted cost)

**Neutral:**
- A future ADR will address database migration from on-premises PostgreSQL to Amazon RDS

Language Tips for ADRs

Writing the Context section

• “The system currently…” — describe current state
• “This decision is required because…” — state the forcing function
• “Constraints include…” — list hard constraints separately

Writing the Rationale

• “[Option X] was chosen because it best satisfies [criterion]…”
• “Despite [disadvantage], [option X] was preferred because…”
• “The team considered [option Y] but rejected it because…”

Writing Consequences

• “This decision enables…”
• “This decision means we accept…”
• “A future decision will be needed for…”

Practice

Explore cloud architecture vocabulary with the Cloud FinOps exercise set and all writing and vocabulary resources in the Cloud Architect learning path.

Refining Your Language: ADRs for International Teams

Writing effective Architecture Decision Records – ADRs – isn’t just about documenting technical choices; it’s about fostering clear communication across teams. When developers from diverse backgrounds collaborate on complex projects like cloud migrations, subtle differences in phrasing and vocabulary can create significant misunderstandings. Let’s consider a scenario: Alex, a developer based in Spain, contributes an ADR proposing to migrate the user authentication service entirely to AWS Lambda. The initial draft uses phrases like “leverage” and “optimize performance” – terms common in some English-speaking environments but which might not be immediately understood by someone whose primary exposure to technical jargon is through translated documentation or a less formal communication style. This could lead to confusion during code review, delaying the decision process considerably.

A key element of successful ADRs, particularly when working with international teams, is striving for precision. Instead of relying on potentially ambiguous terms, we should aim for explicitly stating our reasoning. For example, instead of saying “we need to leverage Lambda’s scalability,” a more effective phrasing would be: “We will use AWS Lambda to handle user authentication because it automatically scales based on demand, reducing the risk of performance bottlenecks during peak usage periods.” This approach removes any potential ambiguity and clearly articulates why a particular technology choice is being made. Similarly, in Slack discussions around an ADR, you might see someone say, “Let’s refactor this for better throughput.” A colleague from Germany could respond with “Could you elaborate on what ‘throughput’ means in this context? Is it the number of requests per second or something else?” Proactively seeking clarification demonstrates respect and ensures everyone is operating with a shared understanding.

Furthermore, remember that ADRs aren’t meant to be overly formal legal documents. The goal is collaborative exploration, not rigid enforcement. When drafting the description for a pull request related to an ADR, instead of writing “This PR implements the proposed Lambda migration strategy,” consider: “This PR incorporates the agreed-upon architecture decision to migrate user authentication to AWS Lambda, focusing on statelessness and automated scaling to ensure resilience.” This phrasing is more descriptive, outlining the outcome of the decision rather than simply stating an action. It also subtly reinforces the foundational reasoning behind the change – a critical element for anyone reviewing the code.

Finally, encourage open dialogue about terminology. If you notice colleagues using phrases that aren’t universally understood, gently suggest alternative wording or provide brief explanations. A simple comment like “Just to clarify, when we say ‘optimize performance,’ we mean reducing latency and improving response times” can go a long way in fostering a more inclusive and productive communication environment. Remember, the goal is not just to document decisions but to build a shared understanding amongst your team members, regardless of their native language.