Esc
↑↓ navigate   Enter open   Esc close
Advanced Writing 10 min read

How to Write an ADR for a Cloud Migration Decision

A step-by-step guide for cloud architects: how to write an Architecture Decision Record (ADR) for cloud migration decisions, with a complete template and real-world examples.

#writing#adr#cloud#architecture#migration#cloud-architect

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.