Why Terragrunt

ไอเดียในหนึ่งประโยค

Terragrunt คือ wrapper บาง ๆ ที่ห่อรอบ terraform (หรือ tofu) binary จริง คอย generate และจัดการ boilerplate ของ backend, provider, และ input ที่ซ้ำกันข้าม environment ทำให้ได้ทั้ง configuration ที่ DRY และ isolation ที่แข็งแรงพร้อมกัน แทนที่จะต้องแลกอย่างใดอย่างหนึ่งไป

ช่องว่างที่ทั้งสองวิธีของ Terraform เองปิดไม่ได้

สองบทที่แล้วพาไปดูสองคำตอบที่ Terraform เองมีให้กับปัญหา multi-environment และแต่ละคำตอบปิดช่องว่างได้แค่ครึ่งเดียว

• workspace เก่งเรื่อง DRY reuse มาก configuration เดียว, backend เดียว, state file หลายชุด แต่ isolation อ่อนแอ ทุก workspace แชร์ backend เดียวกัน, provider configuration เดียวกัน, และโค้ด .tf เดียวกัน มีแค่ string ที่ CLI เลือกไว้เป็นตัวแยกเท่านั้น
• directory-per-environment เก่งเรื่อง isolation มาก directory จริง, backend จริง, อาจมี AWS account แยกกันจริงต่อ environment แต่พา duplication กลับมา backend block, provider block, และ argument source ของ module จบลงด้วยการ copy-paste แทบทุกตัวอักษรในทุก environment directory

Terraform เปล่า ๆ ไม่มี primitive ระดับ first-class ที่ให้ทั้ง isolation ที่แข็งแรงและ configuration ที่ไม่ duplicate เลยพร้อมกัน เลือก pattern ของ Terraform เองแบบไหนก็ต้องยอมรับจุดอ่อนของอีก pattern หนึ่งเสมอ

Terragrunt คืออะไรจริง ๆ

Terragrunt คือ wrapper และ orchestrator บาง ๆ ที่วางอยู่บน setup Terraform (หรือ OpenTofu) ที่มีอยู่แล้ว ไม่ได้เพิ่ม resource syntax ใหม่ และไม่ได้แทนที่อะไรข้างใน modules/app เลย โค้ด module จริงของคุณไม่เปลี่ยนแปลงเลย ยังเป็น Terraform ธรรมดา เหมือนที่เห็นมาในทุกบทก่อนหน้านี้ สิ่งที่ Terragrunt เพิ่มเข้ามาคือ layer ที่อยู่ข้างบนนั้น รับผิดชอบ boilerplate ที่เพิ่งเห็นสะสมอยู่ใน directory-per-environment pattern

• generate backend configuration ของแต่ละ environment จาก definition ศูนย์กลางเดียว แทนที่จะเอา backend "s3" block ไปใส่มือในทุก environment directory
• generate provider configuration ของแต่ละ environment ด้วยวิธีเดียวกัน
• ใส่ input variable ของแต่ละ environment ไว้จุดเดียวต่อ environment โดยไม่ต้องทำ boilerplate ของ module block รอบ ๆ ซ้ำ
• เข้าใจ dependency ordering เมื่อ infrastructure ถูกแยกเป็นหลาย unit ที่ apply แยกกันอิสระ เช่น unit vpc ที่ unit ec2 ต้องใช้ output

Terragrunt unit เล็ก ๆ สำหรับ environment dev จากบทที่แล้วหน้าตาเป็นแบบนี้ สังเกตว่า field ของ backend เป็นตัวเดียวกับที่เขียนมือไว้ก่อนหน้านี้เป๊ะ เพียงแต่ตอนนี้ generate มาจาก configuration แทนที่จะ copy-paste

environments/dev/app/terragrunt.hcl

remote_state {
  backend = "s3"
  generate = {
    path      = "backend.tf"
    if_exists = "overwrite"
  }
  config = {
    bucket       = "acme-terraform-state-dev"
    key          = "app/terraform.tfstate"
    region       = "us-east-1"
    use_lockfile = true
  }
}

terraform {
  source = "../../../modules/app"
}

inputs = {
  environment    = "dev"
  instance_type  = "t3.micro"
  instance_count = 1
}

สิ่งที่ Terragrunt ไม่ใช่

ตรงนี้ควรพูดให้ชัด เพราะเป็นความเข้าใจผิดที่พบบ่อยที่สุด Terragrunt ไม่ใช่ fork ของ Terraform และไม่ได้ compile configuration ของคุณไปเป็นภาษา infrastructure-as-code แบบอื่น ทุกคำสั่งของ Terragrunt สุดท้ายแล้ว shell out ไปเรียกคำสั่ง terraform หรือ tofu จริง ๆ ข้างใต้เสมอ รันกับ backend และ provider configuration ตัวเดียวกับที่ Terragrunt เพิ่ง assemble ไว้ สั่ง terragrunt plan แล้วข้างใต้คือ terraform plan ธรรมดาที่รันอยู่ หน้าที่ของ Terragrunt จบแค่การ generate input แล้ว orchestrate ว่าคำสั่งจริงนั้นควรรันตอนไหน

ปัญหา dependency-ordering ที่ Terragrunt แก้ได้ด้วย

Terraform configuration เดียวเข้าใจลำดับ dependency ระหว่าง resource ภายใน state file เดียวอยู่แล้ว ถ้า security group อ้างถึง ID ของ VPC ตัวหนึ่ง Terraform คิดเองได้ว่าต้องสร้าง VPC ก่อน อัตโนมัติ แต่ graph นั้นหยุดอยู่ที่ขอบของ state file เดียว ทันทีที่ infrastructure ถูกแยกเป็นหลาย unit ที่ apply แยกกันอิสระ เช่น unit vpc ที่มี state ของตัวเอง กับ unit ec2 แยกที่มี state ของตัวเองซึ่งต้องใช้ subnet ID ของ VPC ไม่มีอะไรใน terraform apply ของแต่ละอันที่รู้เลยว่าอีก unit ต้องรันก่อน เพราะแต่ละอันคือ process คนละตัวที่ทำงานบน state file คนละไฟล์กันเลย

Terragrunt ปิดช่องว่างนั้นด้วย dependency block ที่อ่าน output ของ unit อื่น และ run queue ที่ apply unit ตามลำดับที่ถูกต้องให้อัตโนมัติ

# Terragrunt determines vpc must run before ec2, then applies both in order
terragrunt run --all apply

flowchart LR
  ws["Workspaces: DRY, weak isolation"] --> gap["The gap: no primitive gives both at once"]
  dirEnv["Directory-per-environment: isolated, duplicated boilerplate"] --> gap
  gap --> tg["Terragrunt: generates config, orders units"]
  tg --> tf["Real terraform / tofu binary"]

Workspace (DRY, isolation อ่อนแอ) กับ directory-per-environment (isolate ดี แต่ duplicate) ต่างทิ้งช่องว่างไว้ Terragrunt ห่อ terraform binary จริงเพื่อปิดช่องว่างนั้น

พิสูจน์: terraform_remote_state เทียบ dependency ทั้งคู่รันจริง

Terraform เปล่า ๆ มีวิธีอ่าน output ของ state อื่นอยู่แล้ว ไม่ต้องมี Terragrunt เลย: terraform_remote_state พิสูจน์จริง two-unit vpc apply ก่อนด้วย local backend:

vpc/main.tf

resource "local_file" "vpc" {
  filename = "${path.module}/vpc-id.txt"
  content  = "vpc-0123456789abcdef0\n"
}
output "vpc_id" {
  value = "vpc-0123456789abcdef0"
}

ec2/main.tf

data "terraform_remote_state" "vpc" {
  backend = "local"

  config = {
    path = "../vpc/terraform.tfstate"
  }
}

resource "local_file" "ec2" {
  filename = "${path.module}/ec2-vpc-ref.txt"
  content  = "launched into ${data.terraform_remote_state.vpc.outputs.vpc_id}\n"
}

apply จริงใน ec2/ หลังจาก vpc/ apply ไปแล้ว:

$ terraform apply -auto-approve
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
$ cat ec2-vpc-ref.txt
launched into vpc-0123456789abcdef0

นี่ทำงานได้จริงโดยไม่มี Terragrunt เกี่ยวข้องเลย Terraform เปล่า ๆ, data block, อ่านข้าม state จริง ความต่างจริง ๆ จาก dependency block ของ Terragrunt (บทที่แล้ว) โผล่มาทันทีที่ upstream state ยังไม่มีอยู่ ec2/main.tf เดิม ลบ vpc/terraform.tfstate ทิ้งก่อน:

$ terraform plan
Error: Unable to find remote state
No stored state was found for the given workspace in the given backend.

เทียบกับพิสูจน์จริงของบทที่แล้วเรื่อง dependency + mock_outputs: สถานการณ์ “state ยังไม่มีอยู่” เดียวกันเป๊ะ แต่ที่นั่น plan สำเร็จได้ ใช้ค่า placeholder ส่วน apply ปฏิเสธแยกต่างหากอย่างชัดเจน terraform_remote_state ไม่มีอะไรเทียบเท่าเลย — มัน hard-fail ทันที ทุกครั้ง ทั้ง plan และ apply ไม่มี mock fallback ไม่มี allow-list ต่อ command ช่องว่างนั้น — ไม่ใช่ “อ่าน state ของ unit อื่น” ซึ่ง Terraform เปล่า ๆ ทำได้อยู่แล้ว — คือสิ่งที่ dependency เพิ่มเข้ามาจริง ๆ

รักษาความตรงไปตรงมา: Terraform เปล่า ๆ ทำอะไรได้อยู่แล้วบ้าง

จะไม่ตรงไปตรงมาถ้าปล่อยให้เข้าใจว่า Terraform เปล่า ๆ ไม่มี คำตอบให้กับปัญหา configuration duplication เลย — -backend-config กับ -var-file ลด duplication ได้จริง พิสูจน์จริง main.tf ไฟล์เดียวใช้ซ้ำได้สอง environment โดยไม่มี directory ซ้ำเลย:

# env/main.tf — the only .tf file, used for every environment
terraform {
  backend "local" {}
}
variable "environment" { type = string }
variable "instance_count" { type = number }
resource "local_file" "app" {
  filename = "${path.module}/app-${var.environment}.txt"
  content  = "environment=${var.environment} count=${var.instance_count}\n"
}

dev.backend.tfvars

path = "dev.tfstate"

dev.tfvars

environment    = "dev"
instance_count = 1

init กับ apply จริง parameterize ทั้ง backend และ input ทั้งหมดจาก command line ไม่ต้องมี directory environments/dev/ เลย:

$ terraform init -backend-config=../dev.backend.tfvars
$ terraform apply -var-file=../dev.tfvars -auto-approve
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
$ cat app-dev.txt
environment=dev count=1

คู่ staging.backend.tfvars/staging.tfvars หรือสคริปต์ wrapper เล็ก ๆ ที่ loop ผ่านชื่อ environment ก็เข้าใกล้สิ่งที่ directory-per-environment ให้ได้เกือบหมด — .tf ไฟล์เดียว backend และ input ต่อ environment ส่งเข้ามาจากภายนอก สิ่งที่วิธีนี้ ไม่ได้ ให้จริง ๆ คือ: การอ่าน output ข้าม unit แบบ dependency พร้อม mock_outputs (พิสูจน์ข้างบน terraform_remote_state คือสิ่งที่ใกล้เคียงที่สุดของ Terraform เปล่า ๆ และมันไม่มี mock fallback เลย), การจัดลำดับหลาย unit อัตโนมัติ (run --all — สคริปต์ที่เขียนมือต้อง encode ลำดับนั้นเอง หรือ apply unit ทีละตัวตามลำดับตายตัวโดยไม่มี dependency-graph awareness เลย), และจุดเดียวสำหรับเปลี่ยน รูปร่าง ของ logic การ generate backend/provider เอง ไม่ใช่แค่ค่าที่ป้อนเข้าไป คุณค่าจริงของ Terragrunt แคบกว่าและตรงไปตรงมากว่า “Terraform เปล่า ๆ ทำอะไรพวกนี้ไม่ได้เลย” — มันคือ dependency graph, generation logic, และ orchestration ข้ามหลาย unit โดยเฉพาะ ไม่ใช่ parameterization เอง

อ่านโค้ดที่ AI สร้าง

ตอนรีวิว justification แบบ “ทำไมเราต้องใช้ Terragrunt” (จาก AI หรือเพื่อนร่วมทีม) ให้เช็คสิ่งเหล่านี้:

• คำกล่าวอ้างว่า Terraform เปล่า ๆ “ทำไม่ได้” เรื่องปรับ configuration ต่อ environment เลย — พิสูจน์ข้างบนด้วย -backend-config/-var-file run จริง นี่คือการพูดเกินจริง และมองข้ามสิ่งที่ plain-Terraform setup ที่จัดระเบียบดีทำได้อยู่แล้ว
• terraform_remote_state ที่ใช้ข้าม unit โดยไม่จัดการกรณี “state ยังไม่มีอยู่” เลย — พิสูจน์ข้างบน มัน hard-fail ด้วย Unable to find remote state ไม่มี mock_outputs-เทียบเท่าเลย โค้ดที่สมมติว่ามัน degrade อย่างนุ่มนวลแบบ dependency จะพังทันทีที่ environment ใหม่ถูกตั้งขึ้นครั้งแรก
• แผน migration ที่มองว่า Terragrunt แทนที่โค้ด module ของ Terraform — พิสูจน์ข้างบน terraform { source = ... } block ของ environments/dev/app/terragrunt.hcl ยังชี้ไปที่ modules/app ตัวเดียวกันเป๊ะจากบทที่แล้ว ไม่มีอะไรเกี่ยวกับตัว module เองเปลี่ยนเลย

🐛 หา bug ในโค้ดนี้

ec2/main.tf

data "terraform_remote_state" "vpc" {
backend = "local"
config = {
  path = "../vpc/terraform.tfstate"
}
}

resource "aws_instance" "app" {
subnet_id = data.terraform_remote_state.vpc.outputs.subnet_id
}

เฉลย

นี่ถูก apply เป็นส่วนหนึ่งของ terraform apply ครั้งแรกสุดของ environment ใหม่เอี่ยม ก่อนที่ vpc จะเคย apply เลย พิสูจน์ข้างบน terraform_remote_state ไม่มีกลไก mock-output เลย — ต่างจาก Terragrunt dependency block ไม่มีทางให้ plan นี้สำเร็จด้วย placeholder พร้อมส่งสัญญาณว่า apply ควรยังปฏิเสธอยู่ ผลลัพธ์จริงที่เลี่ยงไม่ได้ตรงนี้คือ Error: Unable to find remote state และทางแก้เดียวภายใน Terraform เปล่า ๆ คือเรียง apply ด้วยมือ (apply vpc ก่อนเสมอ ด้วยมือหรือด้วยสคริปต์ที่ encode ลำดับนั้นไว้) — คือปัญหาเรื่องลำดับเป๊ะ ๆ ที่ dependency กับ run --all แก้ให้อัตโนมัติ พิสูจน์แล้วใน module terragrunt-fundamentals

Mental Model

คุณค่าของ Terragrunt เข้าใจได้ดีที่สุดว่า แคบและเจาะจง ไม่ใช่ “ทำทุกอย่างที่ Terraform เปล่า ๆ ทำไม่ได้” พิสูจน์ข้างบน: terraform_remote_state ของ Terraform เปล่า ๆ อ่าน state ข้าม unit ได้ปกติ และ -backend-config/-var-file parameterize ต่อ environment ได้ปกติ สิ่งที่ Terraform เปล่า ๆ ไม่มี primitive เลยคือ graceful degradation ตอน dependency ยังไม่พร้อม (mock_outputs บทที่แล้ว) และการจัดลำดับอัตโนมัติข้ามหลาย unit ที่ apply แยกกันอิสระ (run --all) Terragrunt คือ wrapper ที่เพิ่มสองอย่างนี้เข้ามาเป๊ะ ๆ บวกกับ layer generation ที่เก็บ logic ของ backend/provider เอง (ไม่ใช่แค่ค่าของมัน) ไว้ที่เดียว

Trade-offs

ทางเลือก	ได้อะไร	เสียอะไร
terraform_remote_state (Terraform เปล่า ๆ)	ไม่ต้องมี tooling เพิ่มเลย ใช้ได้วันนี้ พิสูจน์ข้างบนด้วยการอ่านข้าม state จริง	ไม่มี mock fallback เลย พิสูจน์ข้างบน — plan แรกของ environment ใหม่ hard-fail จนกว่า dependency จะถูก apply ตามลำดับที่ถูกต้องด้วยมือ
-backend-config/-var-file (Terraform เปล่า ๆ)	ลด duplication ได้จริง พิสูจน์ข้างบนด้วย main.tf เดียวรับใช้สอง environment	ไม่มี dependency graph ไม่มีการจัดลำดับอัตโนมัติ — สคริปต์ที่ wrap มันยังต้อง encode ลำดับ apply unit เองอยู่ดี
Terragrunt (dependency + run --all + generate)	mock-output graceful degradation และการจัดลำดับอัตโนมัติ ทั้งคู่พิสูจน์แล้วในบทก่อนหน้า	เครื่องมือเพิ่มอีกตัวใน stack มี CLI surface และ version ของตัวเองที่ต้อง track ควบคู่กับ Terraform เอง

ความเข้าใจผิดที่พบบ่อย

• “Terragrunt เป็นวิธีเดียวที่เลี่ยงการ copy-paste backend/provider block ได้” พิสูจน์ข้างบน: -backend-config/-var-file parameterize main.tf เดียวต่อ environment ได้จริงด้วย Terraform เปล่า ๆ ไม่ต้องมี Terragrunt เลย
• “terraform_remote_state กับ dependency ทำงานแบบเดียวกันตอนเป้าหมายยังไม่ถูก apply” พิสูจน์ข้างบนด้วยผลลัพธ์จริงที่ตรงข้ามกันสองแบบ: terraform_remote_state hard-fail ด้วย Unable to find remote state dependency (บทที่แล้ว) สำเร็จได้ตอน plan ผ่าน mock_outputs และปฏิเสธแค่ตอน apply
• “Terragrunt แทนที่หรือ fork โค้ด module ของ Terraform” พิสูจน์ข้างบน: terraform { source = ... } block ยังชี้ไปที่ modules/app ตัวเดียวกันเป๊ะที่ใช้ตลอด module นี้ — Terragrunt generate wrapper รอบ module ไม่เคย generate ตัว module เอง

🏗️ สรุปหนึ่งบรรทัด

Terraform workspace แก้ DRY reuse ได้ดีแต่ isolation อ่อนแอ directory-per-environment แก้ isolation ได้ดีแต่พา duplication ของ boilerplate กลับมา Terraform เปล่า ๆ ไม่มี primitive ที่ปิดทั้งสองช่องว่างพร้อมกัน Terragrunt คือ wrapper และ orchestrator บาง ๆ ไม่ใช่ fork ของ Terraform และไม่ใช่ภาษา IaC ใหม่ ที่ generate backend, provider, และ input configuration จาก definition ศูนย์กลางเดียวแทนที่จะ copy-paste boilerplate และทุกคำสั่งของ Terragrunt สุดท้าย shell out ไปเรียกคำสั่ง terraform/tofu จริงข้างใต้เสมอ คุณค่าจริงของมันแคบกว่า “Terraform เปล่า ๆ ทำสิ่งนี้ไม่ได้เลย” — พิสูจน์ข้างบน terraform_remote_state อ่าน state ข้าม unit ได้จริง และ -backend-config/-var-file parameterize ต่อ environment ได้จริง ทั้งคู่ด้วย Terraform เปล่า ๆ ไม่ต้องมี Terragrunt เลย สิ่งที่ Terragrunt เพิ่มเข้ามาโดยเฉพาะ พิสูจน์ข้างบนด้วยผลลัพธ์จริงที่ตรงข้ามกัน: graceful mock-output degradation ตอน dependency ยังไม่ถูก apply (terraform_remote_state hard-fail ด้วย “Unable to find remote state” ส่วน mock_outputs ของ dependency ทำให้ plan สำเร็จได้อยู่ดี) และ dependency ordering ข้าม unit หลายตัวที่ apply แยกกันอิสระด้วย state file คนละไฟล์ เช่น unit vpc ที่ unit ec2 ต้องพึ่งพา ซึ่ง graph ภายในของ Terraform configuration เดียวมองไม่เห็นข้าม เพราะ graph นั้นหยุดที่ขอบของ state file เดียว

ช่องว่างอะไรที่ยังเหลืออยู่หลังใช้ Terraform workspace หรือ directory-per-environment pattern อย่างใดอย่างหนึ่งเพียงลำพัง

ทั้งสองวิธีแก้ DRY reuse และ isolation ที่แข็งแรงได้พร้อมกันเต็มที่ จึงไม่มีช่องว่างเหลือ ไม่มีวิธีไหนให้ทั้ง configuration ที่ DRY และ isolation ที่แข็งแรงพร้อมกัน workspace แลก isolation ไปกับ reuse ส่วน directory-per-environment แลก reuse ไปกับ isolation workspace ใช้กับ S3 backend ไม่ได้เลย directory-per-environment ใช้ shared module ไม่ได้

Terragrunt คืออะไรกันแน่ อธิบายให้ถูกต้อง

fork ของ Terraform ที่มี resource syntax และ state format ของตัวเอง wrapper และ orchestrator บาง ๆ ที่ห่อรอบ terraform หรือ tofu binary จริง generate backend, provider, และ input configuration และจัดการ dependency ordering โดยไม่เปลี่ยนวิธีเขียนโค้ด module .tf เลย ตัวแทน HCL ที่ compile ไปเป็นภาษา infrastructure-as-code แบบอื่น managed cloud service ที่แทนที่ความจำเป็นต้องมี Terraform backend ไปเลย

Terragrunt มักถูกเข้าใจผิดว่าเป็นอะไร ทั้งที่จริง ๆ แล้วไม่ใช่

linter สำหรับ error ของ HCL syntax ภาษา infrastructure-as-code ใหม่ หรือ fork/ตัวแทนของ Terraform ทั้งที่จริง ๆ ทุกคำสั่ง shell out ไปเรียกคำสั่ง terraform/tofu จริงข้างใต้เสมอ testing framework สำหรับ Terraform module เครื่องมือประเมิน cost ของ AWS resource

Terragrunt แก้ปัญหาแบบไหนที่ dependency graph ภายในของ Terraform configuration เดียวแก้ไม่ได้

จัด format โค้ด HCL ให้เหมือนกันทั้งทีม จัดลำดับ apply ข้าม unit หลายตัวที่ apply แยกกันอิสระด้วย state file คนละไฟล์ เช่น unit vpc ที่ unit ec2 ต้องใช้ output เพราะ graph ของ configuration เดียวมองเห็นแค่ dependency ภายใน state file ของตัวเองเท่านั้น เข้ารหัส state file ตอนเก็บไว้ แก้ conflict ของ provider version ให้อัตโนมัติ

plain Terraform ec2/main.tf ใช้ data "terraform_remote_state" "vpc" อ่าน output ของ vpc บน environment ใหม่เอี่ยมที่ vpc ไม่เคยถูก apply เลย เกิดอะไรขึ้น พิสูจน์ข้างบน

fallback ไปใช้ค่า mock อัตโนมัติ เหมือน Terragrunt dependency block terraform plan hard-fail ทันทีด้วย "Error: Unable to find remote state" — ไม่มีอะไรเทียบเท่า mock-output สำหรับ terraform_remote_state เลย สำเร็จเงียบ ๆ โดย output ทุกตัวเป็น null รอและ retry จนกว่า vpc state จะปรากฏ

พูดว่า Terraform เปล่า ๆ "ทำไม่ได้" เรื่องปรับ configuration ต่อ environment โดยไม่มี Terragrunt ถูกต้องไหม

ถูก Terraform เปล่า ๆ ไม่มีกลไกอะไรเลยสำหรับ configuration ต่อ environment ไม่ถูก — พิสูจน์ข้างบน -backend-config กับ -var-file ทำให้ main.tf ไฟล์เดียวรับใช้หลาย environment ได้ด้วย init/apply จริง parameterize ทั้ง backend และ input จาก command line โดยไม่มี Terragrunt เกี่ยวข้องเลย ถูก เพราะ -backend-config ใช้ได้แค่กับ S3 backend เท่านั้น ไม่ถูก แต่เพราะ Terragrunt ต้องเป็นตัว generate ไฟล์ tfvars เหล่านั้นเองเท่านั้น

Submit

Mark as complete