Як написати ADR для рішення про міграцію в хмару

Запис рішення архітектури (ADR) документує важливі архітектурні рішення — що було вирішено, чому, які альтернативи були розглянуті, і які компроміси були прийняті. Рішення про міграцію в хмару мають високі ставки: вони впливають на вартість, надійність, безпеку і можливості команди на роки вперед. Вони заслуговують на чітку, аудиторську справу. Цей посібник містить покрокові інструкції щодо написання ADR, спеціально розробленого для сценаріїв міграції до хмарних обчислень.

---

Що таке АДР?

** Запис рішення архітектури (ADR) ** — це короткий документ, який містить:

1. Рішення — який архітектурний вибір був зроблений
2. ** Контекст ** - яка проблема або сили призвели до цього рішення
3. ** Варіанти ** — які альтернативи були оцінені
4. ** Причина** — чому цей варіант було обрано на користь інших
5. Наслідки - що дозволяє рішення і скільки це коштує

ADR зберігаються разом з кодом (часто в docs/decisions/ або adr/ папці), версії контролюються і ніколи не вилучаються - тільки замінюються новими ADR.

«Новий член команди запитав, чому ми не використовуємо Kubernetes для пакетних завдань. Я вказував їм на ADR-012 — це пояснює рішення, альтернативи, які ми оцінювали, і чому ми обрали ECS Fargate»

---

Формат ADR для міграції хмар

Типовий заголовок

# 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]

---

Розділ 1: Контекст і висловлювання проблеми

Опишете ситуацію, яка вимагає рішення. Будь конкретним щодо обмежень і сил, що грають.

** Що включати: **

• Поточний стан (те, що існує зараз)
• Проблема, що веде до рішення
• Ключові обмеження (часовий проміжок, бюджет, можливості команди, відповідність)
• Что будет, если мы не решим?

** Приклад: **

## 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

---

Розділ 2: Двигунні рішення

Список критеріїв, які найбільш важливі для прийняття цього рішення — у порядку або групі за важливістю.

## 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

---

Розділ 3: Розглянуті варіанти

Перерахуйте всі варіанти, які ви серйозно оцінили. Будь справедливим до кожного варіанту — не ігноруй альтернативи.

## 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

---

Розділ 4: Результат рішення

Ясно вкажіть, що було вирішено і чому.

## 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.

---

Розділ 5: Плюси і мінуси кожного варіанту

Це аналітичне ядро хорошого ADR — воно показує, що обґрунтування було ретельним.

## 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

---

Розділ 6: Наслідки

Документуйте, що це рішення дозволяє, запобігає і коштує.

## 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

---

Мова для вивчення мови

Запис розділу Контекст

• • « Система зараз… » * — описує поточний стан
• • “Це рішення необхідно, тому що…” * — вказує функцію примусового виконання
• • « Обмеження включають… » * — показувати список жорстких обмежень окремо

Розробка логіки

• • “[Параметри X] було обрано, оскільки вони найкраще задовольняють [критерій]…” *
• “Незважаючи на [недолік], [варіант X] був кращим, тому що…”
• “Команда розглядала [варіант Y], але відхилила його, тому що…”

Наслідки написання

• “Це рішення дозволяє…”
• “Це рішення означає, що ми приймаємо…”
• “Буде потрібно прийняти рішення щодо…”

---

Practice

Досліджуйте словниковий запас хмарної архітектури за допомогою ** Набор упражнений Cloud FinOps ** і всіх ресурсів для написання та словникового запасу за допомогою ** Архітектурний стиль — класицизм **.

Переклади з англійської: І. І. Степанов

Написання ефективних записів архітектурних рішень — ADR — не тільки про документування технічних виборів; це про сприяння ясному спілкуванню між командами. Коли розробники з різних сфер співпрацюють над складними проектами, такими як хмарні міграції, тонкі відмінності у фразуваннях і словниковому запасі можуть створювати значні нерозуміння. Розглянемо сценарій: Алекс, розробник, що базується в Іспанії, вносить ADR, пропонуючи повністю мігрувати службу автентифікації користувача до AWS Lambda. Початковий проект використовує такі фрази, як «левередж» і «оптимізація продуктивності» — терміни, поширені в деяких англомовних середовищах, але які можуть не бути відразу зрозумілими для когось, чиє основне вивчення технічного жаргону здійснюється через перекладену документацію або менш формальний стиль спілкування. Це може призвести до плутанини під час перегляду коду, значно затримуючи процес прийняття рішення.

Ключовим елементом успішних ADR, особливо при роботі з міжнародними командами, є прагнення до точності. Замість того, щоб покладатися на потенційно неоднозначні терміни, ми повинні намагатися чітко сформулювати наші міркування. Наприклад, замість того, щоб сказати «ми повинні використовувати масштабованість Lambda», більш ефективною формулюванням буде: «Ми будемо використовувати AWS Lambda для обробки автентифікації користувача, тому що вона автоматично масштабується на основі попиту, зменшуючи ризик вузлів продуктивності під час періодів пікового використання». Аналогічно, у дискусіях Slack навколо ADR, ви можете побачити, як хтось каже: «Давайте переробимо це для кращої пропускної здатності». Колега з Німеччини може відповісти: «Чи можете ви розібратися, що означає «пропускна здатність» у цьому контексті? Чи це кількість запитів за секунду, чи щось інше?» Проактивне пошуку пояснень демонструє повагу і забезпечує, що всі працюють з спільним розумінням.

Крім того, пам’ятайте, що АДР не повинні бути надто формальними юридичними документами. Цель - совместное исследование, а не жесткое исполнение. Під час написання опису для запитів на витягування, пов’ язаних з ADR, замість написання «Ця PR реалізує запропоновану стратегію міграції Lambda», розгляньте: «Ця PR включає рішення архітектури, узгоджене для міграції автентифікації користувача до AWS Lambda, зосереджуючись на безстатевості і автоматичному масштабуванні для забезпечення стійкості». Ця фраза є більш описовою, описуючи * результат * рішення, а не просто зазначаючи дію. Це також ненадовго підсилює фундаментальні міркування за зміною - критичний елемент для будь-кого, хто переглядає код.

Нарешті, заохочуйте відкритий діалог щодо термінології. Якщо ви помітите, що ваші колеги використовують фрази, які не є загально зрозумілими, ніжно запропонуйте альтернативні формулювання або надайте короткі пояснення. Простий коментар на кшталт «Тільки щоб пояснити, коли ми говоримо «оптимізувати продуктивність», ми маємо на увазі зменшення затримки і поліпшення часу відповіді» може пройти довгий шлях у сприянні більш інклюзивному і продуктивному середовищі комунікації. Пам’ ятайте, що мета — не лише документувати рішення, але і створювати спільне розуміння між членами вашої команди, незалежно від їх рідної мови.