Tám chặng trước giả định cluster đã tồn tại. Chặng này trả lời câu hỏi còn lại: VPC, EKS, ECR, IAM role đó được tạo ra bằng cách nào — và vì sao việc tạo chúng phải là code trong Git, không phải vài chục cú bấm trong AWS Console.
Chín mục: vai trò và ranh giới (1) → nền tảng Terraform (2) → state và backend (3) → module (4) → Terragrunt (5) → dựng EKS bằng code (6) → CI/CD cho hạ tầng (7) → bảo mật và vận hành (8) → checklist (9).
Đây là bảng quan trọng nhất của chặng này. Nhầm ranh giới giữa ba tầng là nguồn gốc của phần lớn rắc rối khi vận hành.
| Tầng | Công cụ | Nhịp thay đổi | Hậu quả khi sai | Ví dụ cụ thể |
|---|---|---|---|---|
| Hạ tầng AWS | Terraform + Terragrunt |
Hàng tuần đến hàng tháng | Rất cao Có thể mất dữ liệu, mất cả cluster |
VPC, subnet, EKS control plane, ECR, IAM role, RDS, ElastiCache, Route53, ACM, S3 |
| Thành phần cluster | Helm chart qua ArgoCD |
Hàng tuần | Trung bình Mất một chức năng của cluster |
ALB Controller, Karpenter, External Secrets, CoreDNS tuning, Prometheus, cert-manager |
| Ứng dụng | Helm values qua ArgoCD |
Nhiều lần mỗi ngày | Thấp Rollback bằng git revert |
Deployment, Service, Ingress, ConfigMap, HPA, image tag |
kubernetes và
helm của Terraform chạy được, nhưng chúng tạo ra ba vấn đề thật:
terraform apply cho mỗi lần deploy nghĩa là khoá state liên tục và pipeline xếp hàng.kubectl thì nó không biết tới lần apply sau. ArgoCD phát hiện trong vài giây.helm chỉ để cài ArgoCD (bootstrap), rồi mọi
thứ sau đó do ArgoCD lo. Đó là một lần duy nhất, và nó phá vỡ vòng lặp "cần ArgoCD để cài ArgoCD".
| Terraform | Terragrunt | |
|---|---|---|
| Là gì | Công cụ IaC: đọc file .tf, gọi API nhà cung cấp, ghi lại kết quả vào state. |
Lớp bọc mỏng quanh Terraform. Không thay thế Terraform — nó gọi Terraform. |
| Giải quyết vấn đề | Khai báo hạ tầng bằng code, biết trước thay đổi (plan), tái lập được. |
Lặp code giữa các môi trường. Với Terraform thuần, mỗi môi trường phải có một bộ file khai báo backend, provider, và biến gần như giống nhau. |
| Khi nào cần | Luôn luôn. | Khi có từ 3 môi trường hoặc 3 region trở lên. Dưới mức đó, Terraform workspace hoặc thư mục riêng là đủ và đơn giản hơn. |
| Chi phí | — | Thêm một công cụ phải học và cài. Thông báo lỗi khó đọc hơn vì đi qua hai lớp. |
terraform thành tofu.
Deployment của ứng dụng bằng Terraform?Phần cú pháp bạn sẽ dùng hầu hết thời gian, kèm những điểm dễ sai.
terraform init # tải provider và module, cấu hình backend. Chạy lại khi đổi provider/module.
terraform fmt -recursive # format code — đưa vào pre-commit hook
terraform validate # kiểm cú pháp và kiểu dữ liệu, KHÔNG gọi API
terraform plan # so code với thực tế, in ra thay đổi sẽ làm. KHÔNG đổi gì.
terraform apply # thực hiện thay đổi
terraform destroy # xoá mọi thứ trong state này
plan là thứ làm Terraform đáng dùng. Nó trả lời "nếu tôi apply thì chuyện gì xảy
ra" trước khi chuyện đó xảy ra. Mọi quy trình CI/CD cho hạ tầng đều xây quanh việc đọc và phê
duyệt output của plan.
# 1. provider — cấu hình nhà cung cấp
provider "aws" {
region = var.region
default_tags {
tags = {
Environment = var.environment
ManagedBy = "terraform"
Repository = "github.com/myorg/infra"
}
}
}
# 2. resource — thứ Terraform TẠO RA và quản lý
resource "aws_ecr_repository" "app" {
name = "order-service"
image_tag_mutability = "IMMUTABLE"
image_scanning_configuration {
scan_on_push = true
}
}
# 3. data — thứ Terraform ĐỌC, không tạo và không quản
data "aws_eks_cluster" "this" {
name = var.cluster_name
}
data "aws_caller_identity" "current" {}
# 4. output — giá trị xuất ra cho module khác hoặc cho người dùng
output "ecr_repository_url" {
description = "URL để CI push image lên"
value = aws_ecr_repository.app.repository_url
}
resource và data: resource nghĩa là "tôi sở hữu
thứ này" — Terraform sẽ tạo, sửa, và xoá nó. data nghĩa là "tôi chỉ đọc" — xoá khối
data khỏi code không ảnh hưởng gì tới tài nguyên thật. Dùng data để tham
chiếu thứ do đội khác quản (ví dụ VPC dùng chung).
variable "environment" {
description = "Tên môi trường"
type = string
validation {
condition = contains(["dev", "staging", "prod"], var.environment)
error_message = "environment phải là dev, staging hoặc prod."
}
}
variable "node_groups" {
description = "Cấu hình node group"
type = map(object({
instance_types = list(string)
min_size = number
max_size = number
capacity_type = optional(string, "ON_DEMAND")
}))
default = {}
}
variable "db_password" {
type = string
sensitive = true # không in ra trong plan và log
}
# Biến cục bộ — giá trị tính toán, dùng lại trong module
locals {
name_prefix = "${var.environment}-${var.project}"
account_id = data.aws_caller_identity.current.account_id
common_tags = {
Environment = var.environment
Project = var.project
}
}
validation là công cụ bị dùng ít hơn mức nó đáng. Nó chặn giá trị sai ngay lúc
plan, với thông báo bạn tự viết — thay vì để AWS API trả về lỗi khó hiểu sau khi đã tạo
một nửa hạ tầng. Những thứ đáng kiểm: tên môi trường, CIDR hợp lệ, phiên bản Kubernetes được hỗ trợ,
kích thước instance nằm trong danh sách cho phép.
for_each thay vì countresource "aws_ecr_repository" "app" {
count = length(var.services)
name = var.services[count.index]
}
# services = ["order", "payment", "report"]
# → app[0]=order, app[1]=payment, app[2]=report
# Xoá "order" khỏi danh sách:
# → app[0] thành payment
# → app[1] thành report
# → app[2] bị xoá
# Terraform sẽ XOÁ VÀ TẠO LẠI cả ba!
resource "aws_ecr_repository" "app" {
for_each = toset(var.services)
name = each.value
}
# → app["order"], app["payment"],
# app["report"]
# Xoá "order" khỏi danh sách:
# → chỉ app["order"] bị xoá
# → hai cái còn lại KHÔNG bị ảnh hưởng
# Quy tắc: luôn dùng for_each trừ khi
# bạn thực sự cần N bản giống nhau.
lifecycle — bảo vệ tài nguyên quan trọngresource "aws_db_instance" "main" {
identifier = "${local.name_prefix}-postgres"
# ...
lifecycle {
# Chặn destroy. terraform destroy sẽ THẤT BẠI thay vì xoá database.
prevent_destroy = true
# Bỏ qua thay đổi ở những field bị thứ khác sửa
ignore_changes = [
password, # do Secrets Manager rotation đổi
final_snapshot_identifier,
]
}
}
resource "aws_launch_template" "node" {
# ...
lifecycle {
# Tạo cái mới TRƯỚC khi xoá cái cũ — tránh khoảng trống không có tài nguyên
create_before_destroy = true
}
}
prevent_destroy là bắt buộc cho mọi tài nguyên có trạng thái: RDS, ElastiCache,
S3 bucket có dữ liệu, EFS. Nó biến một sai sót thành một lỗi pipeline thay vì mất dữ liệu.
destroy, nhưng không chặn việc tài nguyên bị thay thế do
sửa một field bất biến (ví dụ đổi availability_zone của RDS). Để chặn cả trường hợp đó,
đọc kỹ plan và tìm dòng must be replaced — đó là dấu hiệu nguy hiểm nhất
trong output của plan.
plan — các ký hiệuTerraform will perform the following actions:
# aws_ecr_repository.app["order"] will be created
+ resource "aws_ecr_repository" "app" { ← THÊM MỚI, an toàn
+ name = "order-service"
}
# aws_eks_cluster.this will be updated in-place
~ resource "aws_eks_cluster" "this" { ← SỬA TẠI CHỖ, thường an toàn
~ version = "1.30" -> "1.31"
}
# aws_db_instance.main must be replaced
-/+ resource "aws_db_instance" "main" { ← XOÁ RỒI TẠO LẠI. NGUY HIỂM!
~ availability_zone = "ap-southeast-1a" -> "ap-southeast-1b" # forces replacement
}
# aws_security_group.old will be destroyed
- resource "aws_security_group" "old" { ← XOÁ
}
Plan: 1 to add, 1 to change, 1 to destroy.
-/+ và must be replaced trước tiên. Với tài
nguyên không trạng thái (security group, launch template) thì thay thế là bình thường. Với RDS, EBS,
hay bất cứ thứ gì chứa dữ liệu, dừng lại và tìm hiểu vì sao — dòng
# forces replacement nói rõ field nào gây ra.
count cho 3 ECR repo rồi xoá phần tử đầu khỏi danh sách. Terraform làm gì?State là file Terraform dùng để ghi nhớ "tôi đã tạo những gì và nó có ID nào". Hiểu state là hiểu vì sao Terraform hành xử như nó đang hành xử — và vì sao làm hỏng state là sự cố tốn kém nhất.
aws_eks_cluster.this) và ID thật trên AWS (prod-eks). Không có state,
Terraform không biết tài nguyên nào thuộc về nó — nên lần apply sau nó sẽ tạo lại tất cả.
terraform.tfstate trên máy bạn. Ba vấn đề:
.gitignore: *.tfstate, *.tfstate.*,
.terraform/, *.tfvars (nếu chứa secret).
terraform {
required_version = ">= 1.9.0"
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.70" # ghim minor, cho phép patch
}
}
backend "s3" {
bucket = "myorg-terraform-state"
key = "prod/ap-southeast-1/eks/terraform.tfstate"
region = "ap-southeast-1"
encrypt = true
# Khoá để hai người không apply cùng lúc
dynamodb_table = "terraform-locks"
# Từ AWS provider 5.x: dùng S3 native locking, bỏ được DynamoDB
# use_lockfile = true
}
}
# Đây là vấn đề "con gà và quả trứng": cần S3 để lưu state, nhưng tạo S3 cũng cần state.
# Giải pháp: tạo bằng CLI một lần, hoặc tạo bằng Terraform với backend local rồi migrate.
aws s3api create-bucket \
--bucket myorg-terraform-state \
--region ap-southeast-1 \
--create-bucket-configuration LocationConstraint=ap-southeast-1
# Versioning: BẮT BUỘC. Đây là cách phục hồi khi state bị hỏng.
aws s3api put-bucket-versioning \
--bucket myorg-terraform-state \
--versioning-configuration Status=Enabled
# Mã hoá
aws s3api put-bucket-encryption \
--bucket myorg-terraform-state \
--server-side-encryption-configuration \
'{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"aws:kms"}}]}'
# Chặn mọi truy cập công khai
aws s3api put-public-access-block \
--bucket myorg-terraform-state \
--public-access-block-configuration \
"BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true"
# Bảng khoá
aws dynamodb create-table \
--table-name terraform-locks \
--attribute-definitions AttributeName=LockID,AttributeType=S \
--key-schema AttributeName=LockID,KeyType=HASH \
--billing-mode PAY_PER_REQUEST \
--region ap-southeast-1
aws s3api list-object-versions \
--bucket myorg-terraform-state \
--prefix prod/ap-southeast-1/eks/terraform.tfstate \
--query 'Versions[0:5].[VersionId,LastModified,Size]' --output table
aws s3api get-object \
--bucket myorg-terraform-state \
--key prod/ap-southeast-1/eks/terraform.tfstate \
--version-id <VersionId> \
restored.tfstate
Một state khổng lồ cho toàn bộ hạ tầng là phản mẫu. Lý do:
| Vấn đề của state lớn | Hệ quả cụ thể |
|---|---|
| Bán kính ảnh hưởng lớn | Một lỗi khi sửa ECR có thể sinh ra plan đề nghị thay đổi VPC. Mọi apply đều rủi ro cao. |
| Khoá chặn cả đội | Người sửa ECR khoá state, người cần sửa RDS phải chờ. |
plan rất chậm |
Terraform phải gọi API refresh cho mọi tài nguyên. Vài trăm tài nguyên là vài phút mỗi lần plan. |
| Phân quyền thô | Ai apply được state đó là sửa được mọi thứ trong đó. Không tách được quyền theo tầng. |
# Cách chia theo NHỊP THAY ĐỔI và BÁN KÍNH ẢNH HƯỞNG:
prod/ap-southeast-1/
├── network/ state riêng — gần như không bao giờ đổi, ảnh hưởng mọi thứ
├── eks-cluster/ state riêng — đổi khi nâng phiên bản
├── eks-addons/ state riêng — IAM role cho IRSA, EKS add-on
├── data/ state riêng — RDS, ElastiCache. prevent_destroy ở đây.
├── ecr/ state riêng — đổi khi thêm service
└── dns/ state riêng — Route53, ACM
# Nguyên tắc: thứ đổi cùng nhịp thì ở cùng state.
# network và data gần như không đổi → state riêng, ít ai chạm.
# ecr đổi mỗi khi thêm service → state riêng để không khoá cái khác.
# Cách 1: data source — ĐƯỢC KHUYẾN NGHỊ. Không phụ thuộc vào state người khác.
data "aws_vpc" "main" {
tags = { Name = "prod-vpc" }
}
data "aws_subnets" "private" {
filter {
name = "vpc-id"
values = [data.aws_vpc.main.id]
}
tags = { Tier = "private" }
}
# Cách 2: remote state — đọc output của state khác.
# Nhanh hơn nhưng tạo ghép nối chặt: đổi output của network là vỡ mọi state đọc nó.
data "terraform_remote_state" "network" {
backend = "s3"
config = {
bucket = "myorg-terraform-state"
key = "prod/ap-southeast-1/network/terraform.tfstate"
region = "ap-southeast-1"
}
}
# Dùng: data.terraform_remote_state.network.outputs.vpc_id
data source hơn terraform_remote_state. Data source đọc trực
tiếp từ AWS API nên không cần quyền đọc state của đội khác, và không vỡ khi họ đổi cấu trúc output.
Điều kiện: tài nguyên phải có tag hoặc tên đủ ổn định để tìm được — nên hãy đặt quy ước tag ngay từ
đầu.
# Xem và tìm
terraform state list
terraform state show aws_eks_cluster.this
terraform state pull > backup.tfstate # LUÔN backup trước khi can thiệp
# Đưa tài nguyên đã tồn tại vào quản lý của Terraform
terraform import aws_ecr_repository.app order-service
# Từ Terraform 1.5+: khai báo import trong code, an toàn hơn vì có plan
import {
to = aws_ecr_repository.app
id = "order-service"
}
# Bỏ tài nguyên khỏi state mà KHÔNG xoá nó trên AWS
terraform state rm aws_db_instance.old
# Đổi tên/di chuyển trong state (khi refactor code)
terraform state mv aws_instance.web aws_instance.app
# Từ Terraform 1.1+: khai báo moved trong code — tốt hơn vì có trong Git
moved {
from = aws_instance.web
to = aws_instance.app
}
# Mở khoá khi apply bị ngắt và khoá còn treo
terraform force-unlock <LOCK_ID>
terraform state rm — tài nguyên vẫn tồn tại trên AWS nhưng Terraform "quên" nó.
Lần apply sau sẽ tạo một cái mới trùng lặp.terraform force-unlock — nếu lệnh apply kia vẫn đang chạy thật, bạn vừa mở đường cho
hai apply đồng thời và state sẽ hỏng. Xác nhận tiến trình kia đã chết trước.terraform apply -replace — buộc xoá rồi tạo lại. Với RDS là mất dữ liệu.terraform state pull > backup.tfstate trước mọi can thiệp vào state.
terraform state rm aws_db_instance.main. Database thật thế nào?Module là thư mục chứa code Terraform dùng lại được. Đây là cách giữ 3 môi trường nhất quán mà không sao chép code.
modules/eks-irsa-role/
├── main.tf # tài nguyên
├── variables.tf # tham số vào
├── outputs.tf # giá trị ra
├── versions.tf # yêu cầu phiên bản provider
└── README.md # tài liệu (sinh bằng terraform-docs)
variable "cluster_name" {
description = "Tên EKS cluster"
type = string
}
variable "oidc_provider_arn" {
description = "ARN của OIDC provider của cluster"
type = string
}
variable "namespace" {
description = "Namespace Kubernetes của ServiceAccount"
type = string
}
variable "service_account_name" {
description = "Tên ServiceAccount được gắn role này"
type = string
}
variable "policy_json" {
description = "IAM policy dạng JSON. Nên giới hạn tới ARN cụ thể."
type = string
}
variable "tags" {
type = map(string)
default = {}
}
locals {
oidc_host = replace(var.oidc_provider_arn, "/^.*oidc-provider\\//", "")
role_name = "${var.cluster_name}-${var.namespace}-${var.service_account_name}"
}
# Trust policy: CHỈ ServiceAccount này, ở namespace này, trên cluster này
data "aws_iam_policy_document" "assume" {
statement {
effect = "Allow"
actions = ["sts:AssumeRoleWithWebIdentity"]
principals {
type = "Federated"
identifiers = [var.oidc_provider_arn]
}
condition {
test = "StringEquals"
variable = "${local.oidc_host}:sub"
values = ["system:serviceaccount:${var.namespace}:${var.service_account_name}"]
}
condition {
test = "StringEquals"
variable = "${local.oidc_host}:aud"
values = ["sts.amazonaws.com"]
}
}
}
resource "aws_iam_role" "this" {
name = local.role_name
assume_role_policy = data.aws_iam_policy_document.assume.json
tags = var.tags
}
resource "aws_iam_policy" "this" {
name = local.role_name
policy = var.policy_json
tags = var.tags
}
resource "aws_iam_role_policy_attachment" "this" {
role = aws_iam_role.this.name
policy_arn = aws_iam_policy.this.arn
}
output "role_arn" {
description = "Gắn giá trị này vào annotation eks.amazonaws.com/role-arn của ServiceAccount"
value = aws_iam_role.this.arn
}
output "role_name" {
value = aws_iam_role.this.name
}
sub trong trust policy là phần quan trọng nhất của module này. Nó khoá
role vào đúng một ServiceAccount ở đúng một namespace. Nếu bạn đặt wildcard
(system:serviceaccount:*:*) thì mọi pod trong cluster đều assume được role — và IRSA mất
hoàn toàn ý nghĩa. Xem chặng 08, mục 3.
module "order_service_irsa" {
source = "../../modules/eks-irsa-role"
cluster_name = data.aws_eks_cluster.this.name
oidc_provider_arn = data.aws_iam_openid_connect_provider.this.arn
namespace = "prod"
service_account_name = "order-service"
tags = local.common_tags
policy_json = jsonencode({
Version = "2012-10-17"
Statement = [
{
Effect = "Allow"
Action = ["s3:GetObject", "s3:PutObject"]
Resource = ["${aws_s3_bucket.uploads.arn}/*"]
},
{
Effect = "Allow"
Action = ["secretsmanager:GetSecretValue"]
Resource = ["arn:aws:secretsmanager:${var.region}:${local.account_id}:secret:prod/order-service/*"]
}
]
})
}
output "order_service_role_arn" {
value = module.order_service_irsa.role_arn
}
# 1. Đường dẫn cục bộ — cho module trong cùng repo
source = "../../modules/eks-irsa-role"
# 2. Git với TAG — cách đúng cho module dùng chung giữa nhiều repo
source = "git::https://github.com/myorg/terraform-modules.git//eks-irsa-role?ref=v2.4.0"
# 3. Terraform Registry — cho module công khai
source = "terraform-aws-modules/eks/aws"
version = "~> 20.31"
# 4. S3 — cho module nội bộ không muốn đưa lên Git
source = "s3::https://s3-ap-southeast-1.amazonaws.com/myorg-modules/eks-irsa-v2.4.0.zip"
# SAI — nhánh main đổi là plan của bạn đổi theo, không lường trước được
source = "git::https://github.com/myorg/terraform-modules.git//eks?ref=main"
# ĐÚNG — tag bất biến
source = "git::https://github.com/myorg/terraform-modules.git//eks?ref=v2.4.0"
Đây là cùng một nguyên tắc với việc không deploy image bằng tag latest ở
chặng 03: bạn cần biết chính xác mình đang chạy phiên bản nào.
| Module | Dùng để |
|---|---|
terraform-aws-modules/vpc/aws |
VPC với subnet, NAT, route table. Xử lý sẵn phần tag cho EKS — tiết kiệm nhiều công. |
terraform-aws-modules/eks/aws |
EKS control plane, OIDC provider, node group, add-on, access entry. Module phức tạp nhất và đáng dùng nhất. |
terraform-aws-modules/rds/aws |
RDS với subnet group, parameter group, backup. |
terraform-aws-modules/iam/aws |
Có submodule iam-role-for-service-accounts-eks làm sẵn phần IRSA, kèm policy có
sẵn cho ALB Controller, External DNS, EBS CSI. |
terraform plan và đọc kỹ, hoặc xem
.terraform/modules/ sau khi init. Cùng nguyên tắc với Helm chart bên thứ ba
ở chặng 05.
Terragrunt không thay thế Terraform. Nó là một lớp bọc mỏng gọi Terraform, sinh ra để xử lý ba việc lặp đi lặp lại mà Terraform thuần bắt bạn làm bằng tay.
# prod/eks/backend.tf
terraform {
backend "s3" {
bucket = "myorg-tf-state"
key = "prod/eks/terraform.tfstate"
region = "ap-southeast-1"
dynamodb_table = "terraform-locks"
encrypt = true
}
}
# staging/eks/backend.tf
terraform {
backend "s3" {
bucket = "myorg-tf-state"
key = "staging/eks/terraform.tfstate"
... ← lặp lại gần như y nguyên
}
}
# Và key KHÔNG dùng được biến.
# terraform không cho phép var trong backend.
# → phải viết tay cho TỪNG thư mục.
# root.hcl (ở gốc repo)
remote_state {
backend = "s3"
generate = {
path = "backend.tf"
if_exists = "overwrite"
}
config = {
bucket = "myorg-tf-state"
# Tự sinh key theo ĐƯỜNG DẪN thư mục
key = "${path_relative_to_include()}/terraform.tfstate"
region = "ap-southeast-1"
encrypt = true
dynamodb_table = "terraform-locks"
}
}
# Mỗi thư mục con chỉ cần:
include "root" {
path = find_in_parent_folders("root.hcl")
}
# Terragrunt tự sinh backend.tf đúng key
# cho từng thư mục. Không lặp dòng nào.
Khi đã chia nhỏ state (mục 3), bạn phải apply theo đúng thứ tự: network → eks → addons → apps. Với Terraform thuần bạn làm bằng tay hoặc viết script. Terragrunt khai báo được:
include "root" {
path = find_in_parent_folders("root.hcl")
}
terraform {
source = "git::https://github.com/myorg/terraform-modules.git//eks-addons?ref=v2.4.0"
}
# Khai báo phụ thuộc — Terragrunt tự apply eks-cluster TRƯỚC
dependency "eks" {
config_path = "../eks-cluster"
# Giá trị dùng khi chạy plan mà eks-cluster chưa tồn tại,
# tránh lỗi "dependency has no outputs" khi plan toàn bộ từ đầu
mock_outputs = {
cluster_name = "mock-cluster"
oidc_provider_arn = "arn:aws:iam::000000000000:oidc-provider/mock"
}
mock_outputs_allowed_terraform_commands = ["plan", "validate"]
}
dependency "network" {
config_path = "../network"
mock_outputs = {
vpc_id = "vpc-mock"
private_subnet_ids = ["subnet-mock1", "subnet-mock2"]
}
mock_outputs_allowed_terraform_commands = ["plan", "validate"]
}
inputs = {
cluster_name = dependency.eks.outputs.cluster_name
oidc_provider_arn = dependency.eks.outputs.oidc_provider_arn
vpc_id = dependency.network.outputs.vpc_id
private_subnet_ids = dependency.network.outputs.private_subnet_ids
}
# Terragrunt đọc graph phụ thuộc và apply theo đúng thứ tự
terragrunt run-all plan
terragrunt run-all apply
# Thứ tự tự suy ra: network → eks-cluster → eks-addons → ecr
# Những module ĐỘC LẬP được chạy SONG SONG.
# Cấu trúc thư mục = cấu trúc state
infra/
├── root.hcl # backend + provider dùng chung cho TẤT CẢ
├── _envcommon/ # cấu hình chung cho MỖI LOẠI module
│ ├── eks-cluster.hcl
│ └── network.hcl
├── prod/
│ ├── env.hcl # biến riêng của prod
│ └── ap-southeast-1/
│ ├── region.hcl # biến riêng của region
│ ├── network/terragrunt.hcl
│ ├── eks-cluster/terragrunt.hcl
│ ├── eks-addons/terragrunt.hcl
│ └── ecr/terragrunt.hcl
├── staging/
│ ├── env.hcl
│ └── ap-southeast-1/
│ └── ... # cùng cấu trúc, chỉ khác env.hcl
└── dev/
├── env.hcl
└── ap-southeast-1/
└── ...
locals {
# Đọc biến từ các tầng thư mục cha
env_vars = read_terragrunt_config(find_in_parent_folders("env.hcl"))
region_vars = read_terragrunt_config(find_in_parent_folders("region.hcl"))
environment = local.env_vars.locals.environment
aws_region = local.region_vars.locals.aws_region
account_id = local.env_vars.locals.account_id
}
# Sinh file provider cho mọi module — không phải viết lại ở từng thư mục
generate "provider" {
path = "provider.tf"
if_exists = "overwrite_terragrunt"
contents = <<EOF
provider "aws" {
region = "${local.aws_region}"
allowed_account_ids = ["${local.account_id}"]
default_tags {
tags = {
Environment = "${local.environment}"
ManagedBy = "terragrunt"
Repository = "github.com/myorg/infra"
}
}
}
EOF
}
# Backend dùng chung, key tự sinh theo đường dẫn
remote_state {
backend = "s3"
generate = {
path = "backend.tf"
if_exists = "overwrite_terragrunt"
}
config = {
bucket = "myorg-tf-state-${local.environment}"
key = "${path_relative_to_include()}/terraform.tfstate"
region = local.aws_region
encrypt = true
dynamodb_table = "terraform-locks"
}
}
# Input chung cho mọi module
inputs = {
environment = local.environment
aws_region = local.aws_region
}
locals {
environment = "prod"
account_id = "123456789012"
vpc_cidr = "10.0.0.0/16"
kubernetes_version = "1.31"
# Prod: không dùng spot cho node hệ thống
node_capacity_type = "ON_DEMAND"
enable_deletion_protection = true
}
locals {
environment = "dev"
account_id = "210987654321"
vpc_cidr = "10.20.0.0/16"
kubernetes_version = "1.31"
node_capacity_type = "SPOT" # dev chịu được gián đoạn
enable_deletion_protection = false
}
env.hcl và sao chép các terragrunt.hcl rỗng (mỗi file 5–10 dòng). Với
Terraform thuần, bạn phải sao chép toàn bộ khai báo backend, provider, và biến cho từng thư mục — rồi
duy trì chúng đồng bộ bằng tay.
# Trong một thư mục — giống Terraform, chỉ đổi tên lệnh
terragrunt init
terragrunt plan
terragrunt apply
terragrunt output
# Chạy cho nhiều module cùng lúc, theo đúng thứ tự phụ thuộc
terragrunt run-all plan
terragrunt run-all apply
terragrunt run-all apply --terragrunt-non-interactive # cho CI
# Giới hạn phạm vi
terragrunt run-all plan --terragrunt-include-dir "prod/ap-southeast-1/eks-*"
terragrunt run-all plan --terragrunt-exclude-dir "**/data"
# Xem graph phụ thuộc — hữu ích để kiểm thứ tự trước khi apply
terragrunt graph-dependencies | dot -Tpng > graph.png
# Dọn cache (.terragrunt-cache phình khá nhanh)
find . -type d -name ".terragrunt-cache" -prune -exec rm -rf {} \;
run-all apply trên production cần rất cẩn thận. Nó apply nhiều state cùng lúc, nên
một plan sai lan ra nhiều tầng. Hai nguyên tắc:
run-all plan và đọc hết trước khi apply. Output dài, nhưng
-/+ must be replaced là thứ phải tìm.run-all. Chậm hơn nhưng bán kính ảnh
hưởng nhỏ và dễ biết chỗ nào fail. Dùng run-all cho plan (đọc) và cho
môi trường dev.| Tình huống | Lựa chọn đơn giản hơn |
|---|---|
| Một môi trường, một region | Terraform thuần với thư mục phẳng. Thêm Terragrunt chỉ tăng độ phức tạp. |
| Hai môi trường, cấu hình gần giống nhau | terraform workspace hoặc hai thư mục với file .tfvars riêng. |
| Đã dùng Terraform Cloud / Spacelift / Env0 | Các nền tảng này đã giải quyết backend, dependency và phê duyệt. Terragrunt thành trùng lặp. |
| Đội nhỏ, ít kinh nghiệm Terraform | Học Terraform cho vững trước. Terragrunt làm thông báo lỗi khó đọc hơn vì đi qua hai lớp. |
Ví dụ đầy đủ, dùng được: VPC đúng chuẩn cho EKS, cluster, OIDC provider, và các IAM role cho add-on. Đây là phần tạo ra mọi thứ mà chặng 08 mô tả.
module "vpc" {
source = "terraform-aws-modules/vpc/aws"
version = "~> 5.16"
name = "${var.environment}-vpc"
cidr = var.vpc_cidr # 10.0.0.0/16
azs = ["${var.aws_region}a", "${var.aws_region}b", "${var.aws_region}c"]
# Subnet pod phải LỚN: VPC CNI cấp một IP thật cho mỗi pod.
# /19 = 8187 IP mỗi AZ. Xem chặng 08 mục 2.
private_subnets = ["10.0.32.0/19", "10.0.64.0/19", "10.0.96.0/19"]
public_subnets = ["10.0.0.0/24", "10.0.1.0/24", "10.0.2.0/24"]
database_subnets = ["10.0.128.0/24", "10.0.129.0/24", "10.0.130.0/24"]
enable_nat_gateway = true
single_nat_gateway = var.environment != "prod" # prod: một NAT mỗi AZ
one_nat_gateway_per_az = var.environment == "prod"
enable_dns_hostnames = true
enable_dns_support = true
# ---- TAG BẮT BUỘC: thiếu là ALB Controller và Karpenter không hoạt động ----
public_subnet_tags = {
"kubernetes.io/role/elb" = "1"
"kubernetes.io/cluster/${var.cluster_name}" = "shared"
}
private_subnet_tags = {
"kubernetes.io/role/internal-elb" = "1"
"kubernetes.io/cluster/${var.cluster_name}" = "shared"
"karpenter.sh/discovery" = var.cluster_name
}
tags = var.tags
}
# ---- VPC endpoint: cắt phí NAT và tăng bảo mật ----
# S3 là GATEWAY endpoint, MIỄN PHÍ. Bắt buộc có vì layer image nằm trên S3.
resource "aws_vpc_endpoint" "s3" {
vpc_id = module.vpc.vpc_id
service_name = "com.amazonaws.${var.aws_region}.s3"
vpc_endpoint_type = "Gateway"
route_table_ids = module.vpc.private_route_table_ids
tags = merge(var.tags, { Name = "${var.environment}-s3" })
}
# Interface endpoint cho các dịch vụ pod gọi thường xuyên
resource "aws_vpc_endpoint" "interface" {
for_each = toset([
"ecr.api", "ecr.dkr", "sts", "logs",
"secretsmanager", "ssm", "ssmmessages", "ec2messages",
"elasticloadbalancing", "eks",
])
vpc_id = module.vpc.vpc_id
service_name = "com.amazonaws.${var.aws_region}.${each.key}"
vpc_endpoint_type = "Interface"
subnet_ids = module.vpc.private_subnets
security_group_ids = [aws_security_group.vpce.id]
private_dns_enabled = true
tags = merge(var.tags, { Name = "${var.environment}-${each.key}" })
}
resource "aws_security_group" "vpce" {
name_prefix = "${var.environment}-vpce-"
vpc_id = module.vpc.vpc_id
ingress {
from_port = 443
to_port = 443
protocol = "tcp"
cidr_blocks = [module.vpc.vpc_cidr_block]
}
lifecycle { create_before_destroy = true }
tags = var.tags
}
module "eks" {
source = "terraform-aws-modules/eks/aws"
version = "~> 20.31"
cluster_name = var.cluster_name
cluster_version = var.kubernetes_version # "1.31"
vpc_id = var.vpc_id
subnet_ids = var.private_subnet_ids
# Endpoint access — xem chặng 08 mục 2
cluster_endpoint_public_access = true
cluster_endpoint_private_access = true
cluster_endpoint_public_access_cidrs = var.allowed_cidrs # CIDR của VPN và office
# BẮT BUỘC: tạo OIDC provider để IRSA hoạt động
enable_irsa = true
# Bật log để điều tra được. Mặc định TẮT HẾT.
cluster_enabled_log_types = ["api", "audit", "authenticator", "controllerManager", "scheduler"]
# Mã hoá Secret trong etcd bằng KMS
cluster_encryption_config = {
provider_key_arn = aws_kms_key.eks.arn
resources = ["secrets"]
}
# Dùng access entry (API mới) thay cho aws-auth ConfigMap
authentication_mode = "API_AND_CONFIG_MAP"
access_entries = {
platform_team = {
principal_arn = "arn:aws:iam::${var.account_id}:role/PlatformTeam"
policy_associations = {
admin = {
policy_arn = "arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy"
access_scope = { type = "cluster" }
}
}
}
developers = {
principal_arn = "arn:aws:iam::${var.account_id}:role/Developers"
policy_associations = {
view = {
policy_arn = "arn:aws:eks::aws:cluster-access-policy/AmazonEKSViewPolicy"
access_scope = { type = "namespace", namespaces = ["dev", "staging"] }
}
}
}
}
# Add-on cốt lõi do AWS quản
cluster_addons = {
vpc-cni = {
most_recent = true
before_compute = true # phải có TRƯỚC khi node join
configuration_values = jsonencode({
env = {
# Tăng số pod mỗi node nhiều lần — xem chặng 08 mục 2
ENABLE_PREFIX_DELEGATION = "true"
WARM_PREFIX_TARGET = "1"
# Bật NetworkPolicy. Mặc định false và KHÔNG có cảnh báo nào.
ENABLE_NETWORK_POLICY = "true"
}
})
}
coredns = {
most_recent = true
configuration_values = jsonencode({
replicaCount = 3
})
}
kube-proxy = { most_recent = true }
eks-pod-identity-agent = { most_recent = true }
}
# Node group nhỏ chỉ để chạy Karpenter và add-on hệ thống.
# Mọi node khác do Karpenter cấp.
eks_managed_node_groups = {
system = {
instance_types = ["m6g.large"] # Graviton
ami_type = "AL2023_ARM_64_STANDARD"
capacity_type = "ON_DEMAND" # Karpenter không nên chạy trên spot
min_size = 2
max_size = 4
desired_size = 2
labels = { role = "system" }
taints = {
system = {
key = "CriticalAddonsOnly"
value = "true"
effect = "NO_SCHEDULE"
}
}
}
}
# Tag để Karpenter tìm được security group
node_security_group_tags = {
"karpenter.sh/discovery" = var.cluster_name
}
tags = var.tags
}
resource "aws_kms_key" "eks" {
description = "Mã hoá Secret trong etcd của ${var.cluster_name}"
deletion_window_in_days = 30
enable_key_rotation = true
tags = var.tags
}
output "cluster_name" { value = module.eks.cluster_name }
output "cluster_endpoint" { value = module.eks.cluster_endpoint }
output "oidc_provider_arn" { value = module.eks.oidc_provider_arn }
locals {
oidc_host = replace(var.oidc_provider_arn, "/^.*oidc-provider\\//", "")
}
# ---- Karpenter ----
module "karpenter" {
source = "terraform-aws-modules/eks/aws//modules/karpenter"
version = "~> 20.31"
cluster_name = var.cluster_name
enable_v1_permissions = true
namespace = "kube-system"
node_iam_role_use_name_prefix = false
node_iam_role_name = "${var.cluster_name}-karpenter-node"
node_iam_role_additional_policies = {
AmazonSSMManagedInstanceCore = "arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore"
}
tags = var.tags
}
# ---- AWS Load Balancer Controller ----
module "alb_controller_irsa" {
source = "terraform-aws-modules/iam/aws//modules/iam-role-for-service-accounts-eks"
version = "~> 5.48"
role_name = "${var.cluster_name}-alb-controller"
attach_load_balancer_controller_policy = true
oidc_providers = {
main = {
provider_arn = var.oidc_provider_arn
namespace_service_accounts = ["kube-system:aws-load-balancer-controller"]
}
}
tags = var.tags
}
# ---- External Secrets Operator ----
module "external_secrets_irsa" {
source = "terraform-aws-modules/iam/aws//modules/iam-role-for-service-accounts-eks"
version = "~> 5.48"
role_name = "${var.cluster_name}-external-secrets"
attach_external_secrets_policy = true
# Giới hạn tới tiền tố secret, không cấp "*"
external_secrets_secrets_manager_arns = [
"arn:aws:secretsmanager:${var.aws_region}:${var.account_id}:secret:${var.environment}/*"
]
oidc_providers = {
main = {
provider_arn = var.oidc_provider_arn
namespace_service_accounts = ["external-secrets:external-secrets"]
}
}
tags = var.tags
}
# ---- EBS CSI Driver ----
module "ebs_csi_irsa" {
source = "terraform-aws-modules/iam/aws//modules/iam-role-for-service-accounts-eks"
version = "~> 5.48"
role_name = "${var.cluster_name}-ebs-csi"
attach_ebs_csi_policy = true
oidc_providers = {
main = {
provider_arn = var.oidc_provider_arn
namespace_service_accounts = ["kube-system:ebs-csi-controller-sa"]
}
}
tags = var.tags
}
# ---- Xuất ra để ArgoCD dùng ----
# Những ARN này đi vào annotation của ServiceAccount trong Helm values.
output "irsa_role_arns" {
description = "Map role ARN để điền vào values.yaml của ArgoCD"
value = {
karpenter = module.karpenter.iam_role_arn
alb_controller = module.alb_controller_irsa.iam_role_arn
external_secrets = module.external_secrets_irsa.iam_role_arn
ebs_csi = module.ebs_csi_irsa.iam_role_arn
}
}
eks.amazonaws.com/role-arn của ServiceAccount. Ba cách chuyển
giá trị này:
${cluster}-${namespace}-${sa}) rồi Helm
template tự ghép ARN từ account ID. Không cần truyền giá trị nào.# Đây là NGOẠI LỆ hợp lý duy nhất cho việc dùng provider helm trong Terraform:
# phá vỡ vòng lặp "cần ArgoCD để cài ArgoCD".
# Sau bước này, MỌI thứ khác do ArgoCD quản.
provider "helm" {
kubernetes {
host = var.cluster_endpoint
cluster_ca_certificate = base64decode(var.cluster_ca_cert)
exec {
api_version = "client.authentication.k8s.io/v1beta1"
command = "aws"
args = ["eks", "get-token", "--cluster-name", var.cluster_name]
}
}
}
resource "helm_release" "argocd" {
name = "argocd"
repository = "https://argoproj.github.io/argo-helm"
chart = "argo-cd"
version = "7.7.11"
namespace = "argocd"
create_namespace = true
values = [file("${path.module}/argocd-values.yaml")]
# Terraform KHÔNG quản cấu hình ArgoCD sau khi cài.
# ArgoCD tự quản chính nó (self-management) qua repo GitOps.
lifecycle {
ignore_changes = [values]
}
}
# Áp root Application — từ đây ArgoCD lo phần còn lại
resource "kubernetes_manifest" "root_app" {
depends_on = [helm_release.argocd]
manifest = yamldecode(file("${path.module}/root-app.yaml"))
}
ignore_changes = [values] là chi tiết quan trọng. Sau khi ArgoCD được cài và tự
quản chính nó qua repo GitOps (app-of-apps), mọi thay đổi cấu hình ArgoCD đi qua Git. Nếu Terraform
vẫn theo dõi values thì nó và ArgoCD sẽ tranh nhau — đúng vấn đề đã nói ở mục 1.
enable_irsa = true khi tạo EKS. Hậu quả?Terraform trong CI/CD khác hẳn ứng dụng: nhịp chậm hơn, rủi ro cao hơn, và
luôn cần người đọc plan rồi phê duyệt trước khi apply vào production.
| Pipeline hạ tầng (Terraform) | Pipeline ứng dụng (chặng 06) | |
|---|---|---|
| Kích hoạt | Pull request vào repo infra |
Push vào repo code ứng dụng |
| Tần suất | Vài lần mỗi tuần | Nhiều lần mỗi ngày |
| Sản phẩm | Tài nguyên AWS thay đổi | Image trong ECR + commit bump tag |
| Phê duyệt | Bắt buộc với prod. Người đọc plan rồi mới apply |
Tự động cho dev/staging; prod qua pull request vào repo GitOps |
| Rollback | Khó git revert rồi apply — nhưng dữ liệu đã mất thì
không lấy lại được |
Dễ git revert, ArgoCD sync lại |
| Ai apply | CI với IAM role riêng, quyền hẹp theo môi trường | Không ai — ArgoCD kéo từ Git |
Developer mở PR sửa infra/prod/ap-southeast-1/eks-cluster/terragrunt.hcl
│
├─ 1. fmt + validate + tflint + tfsec (nhanh, fail sớm)
├─ 2. terragrunt plan (chỉ ĐỌC, không đổi gì)
├─ 3. Đăng output plan thành comment trong PR ← người review đọc ở đây
├─ 4. Infracost: ước tính thay đổi chi phí (tuỳ chọn, rất hữu ích)
│
├─ 5. Người có quyền review và phê duyệt PR
│
└─ 6. Merge → pipeline apply chạy
├─ dev : apply tự động
├─ staging : apply tự động
└─ prod : CHỜ phê duyệt lần hai trong Jenkins, rồi apply
pipeline {
agent {
kubernetes {
yaml """
apiVersion: v1
kind: Pod
spec:
serviceAccountName: jenkins-terraform # IRSA, không dùng access key
containers:
- name: tf
image: 123456789012.dkr.ecr.ap-southeast-1.amazonaws.com/ci-terraform:1.9.8
command: ['sleep']
args: ['infinity']
resources:
requests: { cpu: 500m, memory: 1Gi }
limits: { cpu: '2', memory: 2Gi }
"""
}
}
options {
// Hai apply đồng thời vào cùng state sẽ tranh khoá
disableConcurrentBuilds()
timeout(time: 60, unit: 'MINUTES')
ansiColor('xterm')
}
parameters {
choice(name: 'ENVIRONMENT', choices: ['dev', 'staging', 'prod'], description: '')
choice(name: 'MODULE', choices: ['network', 'eks-cluster', 'eks-addons', 'ecr', 'data'],
description: 'Module cần apply')
booleanParam(name: 'AUTO_APPROVE', defaultValue: false,
description: 'Chỉ dùng cho dev')
}
environment {
TF_IN_AUTOMATION = 'true'
TF_INPUT = '0'
TG_NON_INTERACTIVE = 'true'
WORK_DIR = "infra/${params.ENVIRONMENT}/ap-southeast-1/${params.MODULE}"
}
stages {
stage('Checkout') {
steps { checkout scm }
}
stage('Kiểm tra tĩnh') {
parallel {
stage('fmt') {
steps {
container('tf') {
sh 'terraform fmt -check -recursive -diff'
sh 'terragrunt hclfmt --terragrunt-check'
}
}
}
stage('tflint') {
steps {
container('tf') {
sh "cd ${WORK_DIR} && tflint --recursive --format compact"
}
}
}
stage('tfsec') {
steps {
container('tf') {
// Quét cấu hình sai về bảo mật: S3 public, SG mở 0.0.0.0/0, không mã hoá
sh 'trivy config --severity HIGH,CRITICAL --exit-code 1 infra/'
}
}
}
}
}
stage('Init & Validate') {
steps {
container('tf') {
sh """
cd ${WORK_DIR}
terragrunt init -upgrade
terragrunt validate
"""
}
}
}
stage('Plan') {
steps {
container('tf') {
script {
// detailed-exitcode: 0 = không đổi, 1 = lỗi, 2 = CÓ thay đổi
def rc = sh(returnStatus: true, script: """
cd ${WORK_DIR}
terragrunt plan -out=tfplan -detailed-exitcode -no-color | tee plan.txt
""")
if (rc == 1) {
error 'terragrunt plan thất bại'
}
env.HAS_CHANGES = (rc == 2) ? 'true' : 'false'
// Lưu plan làm artifact — apply sẽ dùng ĐÚNG file này
archiveArtifacts artifacts: "${WORK_DIR}/tfplan,${WORK_DIR}/plan.txt"
// Cảnh báo nếu plan có tài nguyên bị THAY THẾ
def planText = readFile("${WORK_DIR}/plan.txt")
if (planText.contains('must be replaced')) {
env.HAS_REPLACEMENT = 'true'
echo '*** CẢNH BÁO: plan có tài nguyên bị XOÁ VÀ TẠO LẠI. Đọc kỹ trước khi duyệt. ***'
}
}
}
}
}
stage('Ước tính chi phí') {
when { expression { env.HAS_CHANGES == 'true' } }
steps {
container('tf') {
sh """
cd ${WORK_DIR}
terragrunt show -json tfplan > plan.json
infracost breakdown --path plan.json --format table | tee cost.txt
"""
archiveArtifacts artifacts: "${WORK_DIR}/cost.txt"
}
}
}
stage('Phê duyệt') {
when {
allOf {
expression { env.HAS_CHANGES == 'true' }
expression { params.ENVIRONMENT == 'prod' || !params.AUTO_APPROVE }
}
}
steps {
script {
def msg = env.HAS_REPLACEMENT == 'true'
? "NGUY HIỂM: plan có tài nguyên bị thay thế. Đã đọc plan.txt chưa?"
: "Áp dụng thay đổi vào ${params.ENVIRONMENT}/${params.MODULE}?"
timeout(time: 30, unit: 'MINUTES') {
input message: msg, ok: 'Apply',
submitter: 'platform-team', // chỉ nhóm này duyệt được
submitterParameter: 'APPROVER'
}
}
}
}
stage('Apply') {
when { expression { env.HAS_CHANGES == 'true' } }
steps {
container('tf') {
// Apply ĐÚNG file plan đã được duyệt, không plan lại.
// Nếu hạ tầng đổi giữa lúc plan và apply, Terraform sẽ TỪ CHỐI — đúng như mong đợi.
sh "cd ${WORK_DIR} && terragrunt apply -no-color tfplan"
}
}
}
}
post {
success {
script {
if (env.HAS_CHANGES == 'true') {
slackSend channel: '#infra-changes', color: 'good',
message: "Đã apply ${params.ENVIRONMENT}/${params.MODULE} — duyệt bởi ${env.APPROVER ?: 'auto'}"
}
}
}
failure {
slackSend channel: '#infra-alerts', color: 'danger',
message: "THẤT BẠI: ${params.ENVIRONMENT}/${params.MODULE} — ${env.BUILD_URL}"
}
always {
container('tf') {
// Dọn để không để lại state hay plan trên agent
sh 'find . -name ".terragrunt-cache" -prune -exec rm -rf {} \\; || true'
}
}
}
}
-detailed-exitcode cho bạn biết plan có thay đổi hay không. Nhờ đó pipeline
bỏ qua bước phê duyệt khi không có gì đổi — tránh làm người duyệt mệt vì những yêu cầu rỗng.tfplan đã duyệt, không plan lại. Nếu hạ tầng đổi giữa lúc
plan và apply, Terraform từ chối — đó là cơ chế bảo vệ, không phải lỗi.submitter: 'platform-team' giới hạn ai bấm được nút phê duyệt. Thiếu dòng
này thì bất kỳ ai có quyền xem job đều duyệt được.Hạ tầng không có self-heal như ArgoCD. Ai sửa bằng Console thì Terraform không biết tới
lần apply sau. Giải pháp: một job định kỳ chạy plan và báo động nếu có thay đổi.
pipeline {
agent { kubernetes { /* như trên */ } }
triggers { cron('H 7 * * 1-5') } // 7h sáng các ngày làm việc
stages {
stage('Kiểm drift mọi môi trường') {
steps {
container('tf') {
script {
def drifted = []
for (env_name in ['dev', 'staging', 'prod']) {
for (mod in ['network', 'eks-cluster', 'eks-addons', 'ecr', 'data']) {
def dir = "infra/${env_name}/ap-southeast-1/${mod}"
def rc = sh(returnStatus: true, script: """
cd ${dir}
terragrunt init -upgrade >/dev/null 2>&1
terragrunt plan -detailed-exitcode -no-color > drift.txt 2>&1
""")
if (rc == 2) {
drifted << "${env_name}/${mod}"
archiveArtifacts artifacts: "${dir}/drift.txt"
}
}
}
if (drifted) {
slackSend channel: '#infra-alerts', color: 'warning',
message: "Phát hiện drift ở: ${drifted.join(', ')}\\nXem artifact để biết chi tiết."
// Không fail build — drift là thông tin, không phải lỗi pipeline
currentBuild.result = 'UNSTABLE'
}
}
}
}
}
}
}
most_recent = true.
Đây là drift lành tính.ignore_changes hoặc đừng quản chúng bằng Terraform ngay từ đầu.
# Atlantis chạy trong cluster, lắng nghe webhook của pull request.
# Người review điều khiển bằng comment trong PR:
atlantis plan # chạy plan, đăng kết quả vào PR
atlantis plan -d infra/prod/eks # plan một thư mục
atlantis apply # apply sau khi PR được approve
atlantis unlock # mở khoá nếu PR bị đóng mà còn khoá
version: 3
automerge: false
parallel_plan: true
parallel_apply: false # apply tuần tự để an toàn
projects:
- name: prod-network
dir: infra/prod/ap-southeast-1/network
terraform_version: v1.9.8
workflow: terragrunt
apply_requirements: [approved, mergeable]
autoplan:
when_modified: ["*.hcl", "../../env.hcl", "../region.hcl"]
- name: prod-eks
dir: infra/prod/ap-southeast-1/eks-cluster
workflow: terragrunt
apply_requirements: [approved, mergeable]
workflows:
terragrunt:
plan:
steps:
- run: terragrunt init -upgrade
- run: terragrunt plan -out=$PLANFILE -no-color
apply:
steps:
- run: terragrunt apply -no-color $PLANFILE
| Jenkins tự viết | Atlantis | |
|---|---|---|
| Mạnh ở | Kiểm soát hoàn toàn, tích hợp sẵn với pipeline ứng dụng, dùng chung credential và agent | Plan hiện ngay trong PR, khoá theo PR tự động, apply_requirements buộc PR phải
được approve |
| Yếu ở | Phải tự viết logic phê duyệt, đăng comment, và khoá | Thêm một thành phần phải vận hành; cần webhook từ Git tới cluster |
| Chọn khi | Đã có Jenkins và muốn một chỗ quản mọi pipeline | Nhiều người cùng sửa hạ tầng và muốn quy trình review chặt |
apply tfplan thay vì chạy apply không tham số?Pipeline hạ tầng cần quyền rộng hơn pipeline ứng dụng (nó tạo VPC, IAM role). Nên việc giới hạn phạm vi càng quan trọng.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::123456789012:oidc-provider/oidc.eks.ap-southeast-1.amazonaws.com/id/ABC123"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"oidc.eks.ap-southeast-1.amazonaws.com/id/ABC123:sub":
"system:serviceaccount:jenkins-agents:jenkins-terraform",
"oidc.eks.ap-southeast-1.amazonaws.com/id/ABC123:aud": "sts.amazonaws.com"
}
}
}]
}
dev nằm ở
account dev và không có đường nào tới account prod. Một lỗi trong pipeline dev không thể chạm
vào production — mạnh hơn mọi IAM policy viết cẩn thận trong cùng một account.
# Pipeline prod assume role ở account prod, qua một role trung gian có MFA/phê duyệt
provider "aws" {
region = var.aws_region
assume_role {
role_arn = "arn:aws:iam::${var.account_id}:role/TerraformExecution"
session_name = "jenkins-${var.environment}"
}
allowed_account_ids = [var.account_id] # chặn apply vào account sai
}
allowed_account_ids là một dòng đáng có. Nó chặn tình huống credential trỏ sai
account — ví dụ ai đó chạy pipeline prod với profile dev. Không có nó, Terraform sẽ vui vẻ tạo hạ tầng
prod trong account dev, hoặc tệ hơn là đề nghị xoá hạ tầng vì state không khớp.
| Cách | Đánh giá |
|---|---|
Biến sensitive = true |
Một phần Che trong output của plan, nhưng
vẫn nằm dạng rõ trong state. |
File .tfvars commit vào Git |
Không bao giờ Thêm *.tfvars vào
.gitignore. |
Biến môi trường TF_VAR_* |
Tạm được Không vào Git, nhưng vẫn vào state. |
| Terraform tạo secret rỗng, giá trị do người/ứng dụng điền | Khuyến nghị Terraform tạo aws_secretsmanager_secret
nhưng không quản secret_version. Giá trị không bao giờ đi qua Terraform. |
| Random password + rotation của AWS | Khuyến nghị Cho RDS: dùng
manage_master_user_password = true để AWS tự tạo và lưu vào Secrets Manager. |
# Cách tốt: Terraform tạo "vỏ" secret, không chạm vào giá trị
resource "aws_secretsmanager_secret" "app_db" {
name = "${var.environment}/order-service/db"
kms_key_id = aws_kms_key.secrets.arn
tags = var.tags
}
# KHÔNG khai aws_secretsmanager_secret_version ở đây.
# Giá trị được điền bằng CLI một lần, hoặc do rotation lambda quản.
# → giá trị không bao giờ nằm trong state Terraform.
# Với RDS: để AWS quản mật khẩu master hoàn toàn
resource "aws_db_instance" "main" {
identifier = "${var.environment}-postgres"
manage_master_user_password = true # AWS tạo và lưu vào Secrets Manager
master_user_secret_kms_key_id = aws_kms_key.secrets.arn
# KHÔNG có thuộc tính password → không có mật khẩu nào trong state
lifecycle {
prevent_destroy = true
}
}
# Tình huống thường gặp: hạ tầng được tạo bằng Console, giờ muốn quản bằng code.
# Bước 1: viết code khớp với tài nguyên thật
resource "aws_ecr_repository" "app" {
name = "order-service"
image_tag_mutability = "IMMUTABLE"
}
# Bước 2: khai báo import (Terraform 1.5+) — tốt hơn lệnh import vì có trong Git và có plan
import {
to = aws_ecr_repository.app
id = "order-service"
}
# Bước 3: plan và đọc kỹ
terraform plan
# Nếu plan báo "will be imported" và KHÔNG có thay đổi nào → code khớp. Tốt.
# Nếu plan báo thay đổi → code chưa khớp thực tế. SỬA CODE, đừng apply.
# Bước 4: apply, rồi XOÁ khối import khỏi code
# Công cụ hỗ trợ: sinh code từ hạ tầng đã có
terraform plan -generate-config-out=generated.tf
apply đầu sẽ
sửa tài nguyên thật về khớp code — có thể là thay thế nó. Với RDS hoặc EBS đang chứa dữ liệu,
đó là mất dữ liệu. Quy tắc: import chỉ được apply khi plan hiện đúng 0 thay đổi.
# Ghim phiên bản: cho phép patch, chặn minor/major tự nhảy
terraform {
required_version = "~> 1.9.0" # 1.9.x, không lên 1.10
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.70" # 5.70.x - 5.x, không lên 6.0
}
}
}
# COMMIT file .terraform.lock.hcl vào Git — nó ghim hash của provider.
# Giống package-lock.json: đảm bảo mọi người và CI dùng đúng cùng phiên bản.
# Nâng provider:
terraform init -upgrade
terraform plan # đọc kỹ: provider mới có thể đổi giá trị mặc định
# Nâng cho nhiều kiến trúc (khi CI chạy linux nhưng dev dùng mac)
terraform providers lock \
-platform=linux_amd64 \
-platform=linux_arm64 \
-platform=darwin_arm64
| Triệu chứng | Nguyên nhân | Xử lý |
|---|---|---|
Error acquiring the state lock |
Apply trước bị ngắt giữa đường, khoá còn treo | Xác nhận không còn tiến trình nào chạy, rồi
terraform force-unlock <ID> |
| Plan đề nghị tạo lại mọi tài nguyên | Sai backend, hoặc state rỗng/không tìm thấy | Dừng ngay, đừng apply. Kiểm terraform state list và cấu hình backend |
Resource already exists |
Tài nguyên tồn tại thật nhưng không có trong state | import nó vào state, đừng xoá tài nguyên thật |
-/+ must be replaced trên RDS |
Sửa một field bất biến | Tìm dòng # forces replacement. Thường cần
ignore_changes hoặc đổi cách tiếp cận |
| Plan trống nhưng thực tế đã khác | Thiếu refresh, hoặc tài nguyên có ignore_changes |
terraform apply -refresh-only để đồng bộ state với thực tế |
cycle trong graph phụ thuộc |
Hai tài nguyên tham chiếu lẫn nhau | Tách ra: dùng aws_security_group_rule riêng thay vì khối
ingress lồng trong aws_security_group |
Terragrunt: dependency has no outputs |
Module phụ thuộc chưa được apply | Thêm mock_outputs cho lệnh plan, hoặc apply module kia trước |
| Apply thành công nhưng pod không dùng được IAM role | Thiếu annotation trên ServiceAccount, hoặc sub trong trust policy sai |
Kiểm kubectl get sa X -o yaml và so namespace:serviceaccount với
trust policy |
| Công cụ | Dùng để |
|---|---|
tflint | Bắt lỗi logic và cấu hình không hợp lệ mà validate không thấy (ví dụ instance type không tồn tại). |
trivy config / tfsec | Quét cấu hình sai về bảo mật: S3 public, security group mở 0.0.0.0/0, không mã hoá. |
terraform-docs | Sinh README.md cho module từ variables.tf và outputs.tf. |
infracost | Ước tính chi phí thay đổi ngay trong pull request. Rất hiệu quả để tránh bất ngờ hoá đơn. |
pre-commit | Chạy fmt, validate, tflint, quét secret trước mỗi commit. |
tfswitch / tenv | Đổi phiên bản Terraform theo từng thư mục. |
driftctl | So hạ tầng thật với state, tìm tài nguyên không được quản bởi Terraform. |
repos:
- repo: https://github.com/antonbabenko/pre-commit-terraform
rev: v1.96.2
hooks:
- id: terraform_fmt
- id: terraform_validate
- id: terraform_tflint
- id: terraform_docs
- id: terragrunt_fmt
- repo: https://github.com/gitleaks/gitleaks
rev: v8.21.2
hooks:
- id: gitleaks
import, plan hiện vài thay đổi. Nên làm gì?| Hạng mục | Vì sao | |
|---|---|---|
| ☐ | Terraform không quản Deployment, Service, ConfigMap | Nhịp thay đổi sai, không có điều chỉnh liên tục, và trộn hai tầng rủi ro vào một state. |
| ☐ | Provider helm chỉ dùng để bootstrap ArgoCD |
Và có ignore_changes = [values] để ArgoCD tự quản sau đó. |
| ☐ | IAM role cho IRSA do Terraform tạo, ARN truyền sang Helm values | Đây là điểm nối đúng giữa hai thế giới. |
| ☐ | NodePool của Karpenter do ArgoCD quản, IAM role do Terraform | NodePool là Custom Resource trong cluster, không phải tài nguyên AWS. |
| Hạng mục | Vì sao | |
|---|---|---|
| ☐ | Backend S3 với encrypt = true và khoá |
Hai người apply cùng lúc làm state hỏng. |
| ☐ | Versioning bật trên bucket state | Đây là cách duy nhất phục hồi khi state hỏng. |
| ☐ | Bucket state chặn truy cập công khai, mã hoá KMS | State chứa secret dạng rõ. |
| ☐ | State chia theo nhịp thay đổi, không dùng một state khổng lồ | Bán kính ảnh hưởng nhỏ, plan nhanh, khoá không chặn cả đội. |
| ☐ | *.tfstate, .terraform/, *.tfvars trong .gitignore |
Commit state vào Git là rò rỉ secret. |
| ☐ | .terraform.lock.hcl được commit |
Ghim hash provider để mọi người và CI dùng đúng cùng phiên bản. |
| ☐ | Backup state trước mọi can thiệp (state rm, force-unlock) |
terraform state pull > backup.tfstate |
| Hạng mục | Vì sao | |
|---|---|---|
| ☐ | Dùng for_each thay count |
count dùng chỉ số: xoá một phần tử làm Terraform tạo lại mọi phần tử sau nó. |
| ☐ | prevent_destroy = true cho mọi tài nguyên có trạng thái |
RDS, ElastiCache, S3 có dữ liệu, EFS. Biến sai sót thành lỗi pipeline. |
| ☐ | Module ghim bằtag, không dùng nhánh | ?ref=v2.4.0 chứ không ?ref=main. Cùng lý do với tag image. |
| ☐ | Có validation cho biến quan trọng |
Chặn giá trị sai lúc plan, với thông báo dễ hiểu. |
| ☐ | allowed_account_ids trong khối provider |
Chặn apply vào account sai — lỗi dễ xảy ra và rất tốn kém. |
| ☐ | Secret: Terraform tạo "vỏ", không quản giá trị | Giá trị không bao giờ nằm trong state. Với RDS dùng manage_master_user_password. |
| ☐ | Tag nhất quán qua default_tags |
Để phân bổ chi phí và để data source tìm được tài nguyên. |
| Hạng mục | Vì sao | |
|---|---|---|
| ☐ | Production luôn cần người phê duyệt sau khi đọc plan |
Hạ tầng không rollback dễ như ứng dụng; dữ liệu đã mất thì không lấy lại. |
| ☐ | Apply đúng file tfplan đã duyệt |
Đảm bảo áp dụng chính thứ người review đã đọc. |
| ☐ | submitter giới hạn ai bấm được phê duyệt |
Thiếu nó thì ai xem được job cũng duyệt được. |
| ☐ | disableConcurrentBuilds() |
Hai apply vào cùng state sẽ tranh khoá. |
| ☐ | CI dùng IRSA hoặc OIDC, không dùng access key | Không có key tồn tại lâu dài để rò rỉ. |
| ☐ | Tách account AWS theo môi trường | Biện pháp mạnh hơn mọi IAM policy: pipeline dev không có đường nào tới prod. |
| ☐ | Có job phát hiện drift định kỳ | Hạ tầng không có self-heal như ArgoCD; drift chỉ phát hiện được nếu chủ động kiểm. |
| ☐ | Có tflint và quét bảo mật trong pipeline |
Bắt S3 public, SG mở 0.0.0.0/0, tài nguyên không mã hoá. |
| ☐ | Có infracost trong pull request |
Thấy trước thay đổi chi phí thay vì phát hiện ở hoá đơn cuối tháng. |
| ☐ | Cảnh báo khi plan có must be replaced |
Đây là dấu hiệu nguy hiểm nhất trong output của plan. |
prevent_destroy trên RDS → một destroy sai là mất dữ liệucount rồi xoá phần tử giữa → Terraform tạo lại hàng loạt tài nguyênmust be replaced → tài nguyên có dữ liệu bị thay thế?ref=main → plan đổi theo commit của người khác