11 KiB
11 KiB
ADR-017 — Công cụ Infrastructure as Code — Terraform
Tên file: adr/ADR-017_iac-terraform.md
| Status | Proposed |
| Date | 2026-09-15 |
| Người quyết | Tech Lead + Ops/SRE (hạ tầng — decision-radar.md §5) — chưa ký thật |
| Người đề xuất | SA (qua skill sa-2-architecture, hoạt động adr) |
| Điểm radar | 7/10 (chấm theo decision-radar.md §2, kế thừa nguyên ước lượng đã ghi ở INF_e-commerce_v1.0.md §11: Chi phí đảo ngược=2 (>4 tuần — đổi công cụ sau khi đã có code Terraform thật cho toàn bộ hạ tầng tốn nhiều tuần viết lại + rủi ro thao tác chuyển đổi state) · Bán kính ảnh hưởng=2 (toàn bộ tài nguyên AWS của dự án) · Chạm QAS Must=1 (gián tiếp — nền tảng hiện thực hoá mọi QAS hạ tầng, không phải chính nó là một QAS) · Ràng buộc dài hạn=2 (chuẩn IaC nội bộ ≥1 năm) · Tranh cãi=0 → 7 ⇒ ADR bắt buộc, dưới ngưỡng 8, không bắt buộc POC) |
| Supersedes | — |
| Superseded by | — |
| Liên quan | CON-05 · INF_e-commerce_v1.0.md §11 · OQ-060 · DEC-30 |
⚠️ ADR bất biến sau khi
Accepted. Muốn đổi quyết định thì viết ADR mới cóSupersedes: ADR-017và đổi trạng thái bản cũ thànhSuperseded by. Không sửa nội dung ADR đãAccepted, không xoá ADR đãRejected.
0. Ghi chú Preflight & ngoại lệ gate
Viết cùng lượt với ADR-014/ADR-015/ADR-016 dưới ngoại lệ gate ghi ở DEC-31 (tiếp nối
DEC-01…30) — xem ADR-014 §0 cho bối cảnh đầy đủ. Riêng ADR-017: hiện thực hoá đề xuất đã ghi
ở INF_e-commerce_v1.0.md §11 (duyệt từng phần, DEC-30).
1. Bối cảnh
Trước khi sa-3-enablement (GĐ3) viết code hạ tầng thật, cần chốt công cụ Infrastructure as Code
(IaC) chính cho toàn dự án — tránh tình trạng mỗi thành phần hạ tầng dùng một công cụ khác nhau,
không ai review/audit được nhất quán. INF_e-commerce_v1.0.md §11 đã đề xuất Terraform và đánh
dấu đây là quyết định thiết lập tiền lệ (radar ước lượng ~7, đạt ngưỡng ADR bắt buộc), yêu cầu
SA viết ADR chính thức ở hoạt động adr.
Ràng buộc đang chi phối:
| Nguồn | Nội dung |
|---|---|
CON-05 |
Năng lực đội (kỹ năng lập trình cho hạ tầng — TypeScript/Python cho CDK, hay chỉ cần HCL của Terraform) chưa xác nhận rõ |
D9 (design-rules.md) |
Mọi con số hạ tầng phải quy ra tiền, có nguồn, và cấu hình phải tái lập được — công cụ IaC là nền tảng để đạt điều này |
Cái đã biết chắc / cái còn là giả định:
| Điều | 🟢 Đã kiểm chứng / 🔴 Giả định | Bằng chứng |
|---|---|---|
| Terraform có cộng đồng module lớn cho ECS/RDS/ElastiCache (AWS) | 🟢 Đã kiểm chứng — thực tế công khai của hệ sinh thái Terraform | INF §11 |
| Đội có đủ kỹ năng TypeScript/Python để dùng AWS CDK hiệu quả | 🔴 Giả định chưa xác nhận | CON-05, OQ-060 |
| Đội có đủ kỹ năng HCL (ngôn ngữ cấu hình của Terraform) hoặc học được nhanh hơn một ngôn ngữ lập trình đầy đủ | 🔴 Giả định — Terraform HCL thường được coi là dễ tiếp cận hơn với đội chưa quen lập trình hạ tầng, nhưng chưa xác nhận với đội thật | OQ-060 |
2. Phương án đã cân nhắc
PA-1 — Terraform (chọn)
| Mô tả | HashiCorp Terraform, dùng HCL để định nghĩa hạ tầng, quản lý state qua backend (đề xuất S3 + DynamoDB lock) |
| Ưu | Đa cloud-agnostic hơn CDK (dù hiện chỉ dùng AWS — giữ tuỳ chọn mở cho tương lai); cộng đồng module lớn cho ECS/RDS/ElastiCache; không khoá vào một ngôn ngữ lập trình cụ thể (HCL là ngôn ngữ khai báo riêng, không cần biết TypeScript/Python) |
| Nhược | HCL là một ngôn ngữ riêng cần học, dù thường được coi là dễ tiếp cận hơn ngôn ngữ lập trình đầy đủ; cần thiết lập backend state (S3 + DynamoDB lock) — thêm một phần hạ tầng nhỏ |
| Chi phí đảo ngược | Cao (>4 tuần) nếu đổi công cụ sau khi đã có code Terraform thật cho toàn bộ hạ tầng — viết lại + rủi ro thao tác trong lúc chuyển đổi state |
PA-2 — AWS CDK
| Mô tả | Định nghĩa hạ tầng bằng ngôn ngữ lập trình đầy đủ (TypeScript/Python), compile ra CloudFormation |
| Ưu | Tích hợp sâu với AWS, cho phép dùng logic lập trình (vòng lặp, hàm) trực tiếp khi định nghĩa hạ tầng |
| Nhược | Cần kỹ năng TypeScript/Python cho hạ tầng — CON-05 chưa xác nhận đội có; khoá vào AWS (dù hiện tại dự án chỉ dùng AWS, việc khoá vào một hãng làm giảm tuỳ chọn multi-cloud tương lai nếu cần) |
| Chi phí đảo ngược | Cao — tương tự PA-1, đổi sau khi đã có code thật tốn nhiều tuần |
PA-3 — AWS CloudFormation (native)
| Mô tả | Dùng trực tiếp CloudFormation (JSON/YAML), không qua công cụ trung gian |
| Ưu | Không cần công cụ bên thứ ba, tích hợp gốc với AWS Console/CLI |
| Nhược | Cú pháp JSON/YAML kém module hoá hơn Terraform/CDK; cộng đồng module tái sử dụng nhỏ hơn; quản lý state kém linh hoạt hơn (CloudFormation tự quản lý state, không có backend tách rời như Terraform S3+DynamoDB, khó tách theo môi trường/nhóm tài nguyên để giảm blast radius) |
| Chi phí đảo ngược | Trung bình-cao — viết lại theo cấu trúc module hoá tốt hơn sau này |
Bảng so sánh
| Tiêu chí | PA-1 (Terraform) | PA-2 (CDK) | PA-3 (CloudFormation) |
|---|---|---|---|
Phù hợp năng lực đội hiện tại (CON-05, chưa xác nhận kỹ năng lập trình) |
🟡 Cần học HCL (thường dễ hơn) | 🔴 Cần TypeScript/Python | 🟡 Cần học JSON/YAML CloudFormation |
| Đa cloud-agnostic (giữ tuỳ chọn tương lai) | ✅ | ❌ Khoá vào AWS | ❌ Khoá vào AWS |
| Cộng đồng module tái sử dụng (ECS/RDS/ElastiCache) | ✅ Lớn | 🟡 Trung bình | 🔴 Nhỏ hơn |
| Tách state theo môi trường/nhóm tài nguyên (giảm blast radius) | ✅ Linh hoạt (backend riêng) | 🟡 Qua CDK stack | 🔴 Kém linh hoạt hơn |
3. Quyết định
Chọn PA-1 — Terraform làm công cụ Infrastructure as Code chính cho toàn dự án.
Vì sao: Cân bằng tốt nhất giữa năng lực đội chưa xác nhận rõ (CON-05, không đòi hỏi kỹ năng
lập trình đầy đủ như CDK), hệ sinh thái module tái sử dụng lớn cho đúng các dịch vụ AWS đã chọn
(ECS/RDS/ElastiCache), và khả năng tách state để giảm blast radius (yêu cầu (h) của INF §11).
Phạm vi áp dụng: Toàn bộ hạ tầng AWS của dự án — network, data, compute — trong mọi môi trường (dev/stg/prod).
Điều kiện chuyển Proposed → Accepted
| Điều kiện | Ai xác nhận | Trạng thái hiện tại |
|---|---|---|
| Tech Lead xác nhận công cụ IaC (Terraform) cho P2 | Tech Lead | Mở (OQ-060 chưa đóng) |
| Ops/SRE xác nhận năng lực vận hành Terraform (đào tạo nếu cần) | Ops/SRE | Mở |
| Thiết lập backend state (S3 + DynamoDB lock) thành công ở dev/stg | Ops/SRE | Chưa chạy — GĐ3 |
4. Phương án bị loại và lý do
| Phương án | Loại vì | Gắn với | Điều kiện nào thì xét lại |
|---|---|---|---|
| PA-2 — AWS CDK | Cần kỹ năng TypeScript/Python cho hạ tầng mà CON-05 chưa xác nhận đội có; khoá vào AWS làm giảm tuỳ chọn multi-cloud tương lai dù hiện chưa cần |
CON-05 |
Xét lại nếu đội xác nhận có kỹ năng lập trình mạnh (TypeScript/Python) và muốn tích hợp logic lập trình phức tạp trực tiếp vào định nghĩa hạ tầng |
| PA-3 — CloudFormation | Cộng đồng module nhỏ hơn, kém tái sử dụng, quản lý state kém linh hoạt hơn so với Terraform (backend S3+DynamoDB tách rời) | INF §11 (yêu cầu tách state theo môi trường/nhóm) |
Xét lại nếu tổ chức có chính sách bắt buộc chỉ dùng công cụ AWS gốc (không có ở dự án này hiện tại) |
5. Hệ quả
Hệ quả tích cực
- Module hoá tốt, tách state theo môi trường/nhóm tài nguyên — giảm blast radius khi
terraform apply - Drift detection dễ tích hợp CI (
terraform planđịnh kỳ,FIT-34) - Không khoá vào một ngôn ngữ lập trình cụ thể — giảm rào cản với đội chưa xác nhận kỹ năng TypeScript/Python
Hệ quả tiêu cực phải sống chung
- Cần đào tạo Terraform/HCL cho đội nếu chưa quen (
TCO §5) - Cần thiết lập và vận hành backend state riêng (S3 + DynamoDB lock) — thêm một phần hạ tầng nhỏ cần quản lý (quyền truy cập, backup state)
Cái quyết định này khoá lại
| Muốn đổi về sau thì | Tốn |
|---|---|
| Đổi công cụ IaC sau khi đã có code Terraform thật cho toàn bộ hạ tầng | Viết lại toàn bộ + rủi ro thao tác trong lúc migrate state — nhiều tuần |
Việc phát sinh
| Việc | Chủ | Hạn | Ghi ở đâu |
|---|---|---|---|
| Viết Terraform module thật cho network/data/compute | Ops/SRE + Dev (GĐ3) | Trước go-live | 03-enablement/AGD_e-commerce.md (chưa tồn tại) |
| Thiết lập backend state (S3 + DynamoDB lock) | Ops/SRE | Trước khi viết module thật | GĐ3 |
Viết FIT-34/FIT-35/FIT-36 thật |
Ops/SRE (GĐ3) | GĐ3 | 03-enablement/FIT_e-commerce.md |
6. Cách kiểm chứng quyết định này được tuân thủ
| Cách kiểm | Công cụ | Chạy ở đâu | FIT |
|---|---|---|---|
| Drift detection — hạ tầng thật khớp Terraform state | terraform plan định kỳ / driftctl |
CI, hàng ngày | FIT-34 (đã đề xuất ở INF §11) |
| Tag policy — mọi tài nguyên có đủ 4 tag bắt buộc | AWS Config rule / OPA | CI + AWS Config liên tục | FIT-35 (đã đề xuất ở INF §11) |
| Đúng cấu trúc hạ tầng (2 ECS service GD/HT + 1 Payment, đúng SG cô lập) | Terraform plan review + AWS Config | CI/CD | FIT-36 (đã đề xuất ở INF §11) |
7. Điều kiện xét lại
| Dấu hiệu | Ngưỡng | Ai theo dõi |
|---|---|---|
| Đội xác nhận có kỹ năng TypeScript/Python mạnh và muốn logic lập trình phức tạp trong định nghĩa hạ tầng | Ý kiến chính thức từ Tech Lead sau khi đội đã dùng Terraform một thời gian | Tech Lead |
| Nhu cầu multi-cloud thật sự phát sinh | Có quyết định kinh doanh mở rộng ngoài AWS | PO + Tech Lead |
8. Tham chiếu
- POC: Không bắt buộc (radar 7/10, dưới ngưỡng 8)
- Bài đo:
FIT-34/FIT-35/FIT-36(ứng viên GĐ3, đã đề xuất ởINF §11) - Tài liệu ngoài: —
- Thảo luận:
INF_e-commerce_v1.0.md §11(phát hiện + đề xuất),OQ-060,DEC-30