環境分離從第一天的目錄結構就定好

環境分離的本質是把「同一套基礎設施定義」複製成多份隔離的執行實例，每份有自己的 state、自己的雲端資源、自己的故障半徑。它承擔的責任是讓 dev 的實驗、staging 的驗證、prod 的真實流量彼此不可見也不可達 — 在 dev 跑壞一個資料庫、套錯一條 security group 規則，prod 完全無感。

這個邊界要在第一天就用目錄結構表達出來，原因是 state 一旦混在一起就難以無痛拆開。Terraform 這類工具用 state 檔記錄「哪個資源由哪段 code 管理」，如果 dev 跟 prod 的資源都登記在同一份 state，後續想把 prod 移出去，等於要對正在服務的資源做 state mv 或 import/remove 操作 — 任何一步算錯，工具可能判定資源該銷毀重建，而那是 prod 的資料庫。第一天就分目錄，dev 與 prod 從來不曾共用 state，這個風險根本不存在。

檢查自己的 repo：如果現在只有一份 main.tf、裡面同時宣告了 dev-db 跟 prod-db，或者 terraform.tfstate 裡同時記錄了兩個環境的資源，這個專案已經欠下環境分離的債，債齡每天都在增加。下一步路由是先確立目錄骨架，再決定差異怎麼參數化。

目錄分離 vs Terraform workspace 的取捨

切分環境有兩條主流路徑：每個環境一個獨立目錄（各自持有 backend 與 state），或共用一份 code 用 Terraform workspace 切換不同 state。兩者都能讓 state 隔離，差別在「環境差異藏在哪裡」以及「誤操作的故障半徑多大」。

隔離強度光譜

在挑這兩條路之前，先把它們放回完整的分離強度光譜。環境分離橫跨一條從帳號到 workspace、隔離由粗到細的階梯：

光譜越靠粗的一端，隔離越強、跨環境共用越少、初始與維運成本越高；越靠細的一端，重複越少、邊界越隱性。多數早期團隊在目錄分離這一格落腳，因為它在顯式邊界與維運成本之間平衡得宜。當隔離需求升高（例如 prod 要法規等級的帳務與權限隔離），再沿光譜往帳號級或獨立 repo 移。帳號級隔離的權限邊界設計見模組二：身分與憑證地基。

目錄分離的結構

目錄分離把每個環境寫成可獨立進入的工作目錄，差異透過各自的 terraform.tfvars 表達，prod 的 backend 設定、變數值、甚至 provider 版本都各自鎖定。

 1infra/
 2├── modules/                  # 可重用模組、不含任何環境專屬值
 3│   ├── network/
 4│   ├── database/
 5│   └── service/
 6└── environments/
 7    ├── dev/
 8    │   ├── main.tf           # 呼叫 modules、傳 dev 參數
 9    │   ├── backend.tf        # state 指向 dev 專屬位址
10    │   └── terraform.tfvars  # dev 的差異值
11    ├── staging/
12    │   └── ...
13    └── prod/
14        ├── main.tf
15        ├── backend.tf        # state 指向 prod 專屬位址
16        └── terraform.tfvars  # prod 的差異值

它的代價是目錄之間有重複的 boilerplate（main.tf 裡的 module 呼叫在每個環境幾乎一樣），好處是邊界顯式 — cd 進哪個目錄、apply 就只會動那個環境，prod 的 state 位址寫死在 prod 目錄的 backend 設定裡，不會因為忘記切換而打錯環境。

每個環境目錄的 backend.tf 各自指向獨立的 state 路徑，這是邊界的物理保證：

 1# environments/prod/backend.tf
 2terraform {
 3  backend "s3" {
 4    bucket         = "acme-tf-state"
 5    key            = "prod/terraform.tfstate"
 6    region         = "ap-northeast-1"
 7    encrypt        = true
 8    dynamodb_table = "acme-tf-lock"
 9  }
10}

 1# environments/dev/backend.tf
 2terraform {
 3  backend "s3" {
 4    bucket         = "acme-tf-state"
 5    key            = "dev/terraform.tfstate"
 6    region         = "ap-northeast-1"
 7    encrypt        = true
 8    dynamodb_table = "acme-tf-lock"
 9  }
10}

Terragrunt 收斂 boilerplate

目錄分離的 boilerplate 重複可以用 Terragrunt 收斂。Terragrunt 的存在理由正是把跨環境目錄共通的 backend、provider、module 呼叫抽成一份範本，各環境目錄只留差異值，等於在保留目錄顯式邊界的前提下補上一層 DRY。它值得引入的情境是環境數量多（超過三個）、共通 boilerplate 開始拖慢維護時；環境只有兩三個時，直接維護幾份目錄的成本通常還低於多引入一個工具與它的學習曲線。

Workspace 的邊界

Workspace 共用同一份 code、用 terraform workspace select prod 在執行期切換 state。它的好處是零重複，所有環境的 code 保證同步；代價是環境差異只能靠 terraform.workspace 在 code 裡寫條件判斷，而當前選中哪個 workspace 是 shell 的隱性狀態。

這個隱性狀態正是早期最該避免的失誤來源。在 dev workspace 以為自己在改 dev、其實上一個指令切到了 prod，apply 下去才發現故障半徑是 prod。沒有任何檔案層級的信號能防止這件事 — workspace 的當前狀態存在本地的 .terraform/ 目錄裡，git diff 看不到、code review 也看不到。

早期推薦目錄分離，理由是故障半徑與認知負荷的取捨在小團隊明顯偏向「顯式邊界」這一側：團隊還沒有成熟的 CI gate 攔截誤 apply，顯式目錄是最便宜的防呆。Workspace 較划算的情境是環境數量多且高度同構（例如每個客戶一個隔離環境、差異只有名稱與配額），重複目錄的維護成本開始超過 workspace 隱性狀態的風險時，再切過去。每個環境的 state 要怎麼各自隔離、backend 怎麼設定，見模組一：最小可行 IaC。

module 化：同一套 code、不同參數

Module 是把一組會被多環境重複使用的資源封裝成有輸入參數的單元，承擔的責任是讓 dev 與 prod 共享同一份邏輯定義、只在參數上分歧。沒有 module 時，dev 與 prod 各自維護一份 copy-paste 的資源宣告，兩份會隨時間漂移 — 有人只在 prod 補了一條 security group 規則、忘了同步 dev，於是「dev 能跑、prod 卻爆掉」或更糟的「dev 測過了、prod 行為不同」。

避免漂移的關鍵是讓環境之間唯一合法的差異來源是傳進 module 的參數，而不是 module 內部的 code 分支。Module 內部不寫 if env == "prod" 這類判斷，所有環境相關的值都從 variable 進來：

 1# modules/database/variables.tf — module 只宣告它需要什麼參數
 2variable "instance_class" {
 3  type        = string
 4  description = "RDS instance type"
 5}
 6
 7variable "multi_az" {
 8  type    = bool
 9  default = false
10}
11
12variable "backup_retention_days" {
13  type    = number
14  default = 7
15}
16
17variable "deletion_protection" {
18  type    = bool
19  default = true
20}

 1# modules/database/main.tf — module 用參數建資源，不含環境判斷
 2resource "aws_db_instance" "primary" {
 3  identifier              = "${var.service_name}-${var.env}"
 4  engine                  = "postgres"
 5  engine_version          = var.engine_version
 6  instance_class          = var.instance_class
 7  multi_az                = var.multi_az
 8  backup_retention_period = var.backup_retention_days
 9  deletion_protection     = var.deletion_protection
10  db_subnet_group_name    = var.subnet_group_name
11  vpc_security_group_ids  = var.security_group_ids
12}

 1# environments/prod/main.tf — prod 傳自己的值
 2module "database" {
 3  source                = "../../modules/database"
 4  service_name          = "payments"
 5  env                   = "prod"
 6  instance_class        = "db.r6g.xlarge"
 7  engine_version        = "16.3"
 8  multi_az              = true
 9  backup_retention_days = 30
10  deletion_protection   = true
11  subnet_group_name     = module.network.private_subnet_group
12  security_group_ids    = [module.network.db_security_group_id]
13}

 1# environments/dev/main.tf — dev 傳縮小版的值
 2module "database" {
 3  source                = "../../modules/database"
 4  service_name          = "payments"
 5  env                   = "dev"
 6  instance_class        = "db.t3.micro"
 7  engine_version        = "16.3"
 8  multi_az              = false
 9  backup_retention_days = 1
10  deletion_protection   = false
11  subnet_group_name     = module.network.private_subnet_group
12  security_group_ids    = [module.network.db_security_group_id]
13}

這樣 dev 與 prod 跑的是位元層級相同的 module code，差異全部收斂在 main.tf 的呼叫參數裡、一眼可審。Review 時只要 diff 各環境的參數區塊就能看完所有環境差異。如果發現有人為了某環境的特例去改 module 內部，那是漂移正在發生的徵兆——該把特例改寫成新的參數，而非在 module 裡加 if env == "prod" 分支。核心服務怎麼用 module 跨環境重用，見模組五：核心服務上 IaC。

環境差異參數化：prod 放大、dev 縮小

環境之間真正該不同的是規模與冗餘等級，而這些差異全部表達成參數值、不表達成不同的 code。Prod 承擔真實流量與可用性承諾，所以跨多個可用區（multi-AZ）部署、機器規格放大、備份保留更久、開啟刪除保護；dev 承擔的是迭代速度與成本控制，所以單 AZ、最小機型、短備份甚至無備份，壞了重建即可。

把這些差異參數化的好處是「環境拓樸的形狀一致、只有刻度不同」。Dev 與 prod 都經過同一段 module 邏輯，prod 不會出現一段 dev 從未執行過的 code path — 真正上線的設定，在 dev 已經以縮小版驗證過邏輯正確性。

常見陷阱是把成本差異做成「dev 直接砍掉某個元件」：例如 dev 為了省錢不建負載平衡器、prod 才建，結果 prod 的 LB 相關設定從來沒在 dev 測過。較合理的做法是 dev 也建同型元件、只把規格與數量縮到最小，讓拓樸保持同構、只縮放刻度。

邊界在於少數差異無法只靠刻度表達。Prod 需要合規要求的稽核 log、dev 不需要；prod 要開 WAF、dev 不需要。這類差異用 count 或 for_each 配一個布林參數開關：

1resource "aws_cloudwatch_log_group" "audit" {
2  count             = var.enable_audit_log ? 1 : 0
3  name              = "/app/${var.env}/audit"
4  retention_in_days = 365
5}

仍然走參數化、不分叉 code — 分叉 code 是漂移的起點。跨可用區與冗餘的網路面怎麼鋪，見模組三：網路地基。

retrofit 路徑：把單環境拆成 per-env module

很多專案是先在單一環境把 IAM、VPC、核心資源都建起來、跑通了，才意識到需要環境分離 — 這是常見且合理的演進順序，尤其是先救火上線、之後才回頭納管的情況。Retrofit 的目標是在不破壞正在服務的資源前提下，把這份「隱含為 prod」的單環境，重構成「modules + per-env 呼叫」的結構，並讓現有資源平移成 prod 環境。

安全的步驟順序是先重構 code、再動資源歸屬，且每一步都用 terraform plan 確認「零變更」。

第一步：抽 module、宣告搬遷

把現有資源宣告抽成 module：把 main.tf 裡的資源搬進 modules/，原地用 module 呼叫取代，所有值先寫死成現況。資源在 state 裡的位址會從 aws_db_instance.primary 變成 module.database.aws_db_instance.primary，用 moved {} 區塊宣告搬遷，避免工具誤判為「銷毀舊的、建新的」：

1moved {
2  from = aws_db_instance.primary
3  to   = module.database.aws_db_instance.primary
4}
5
6moved {
7  from = aws_security_group.db
8  to   = module.database.aws_security_group.db
9}

此時 plan 必須顯示無任何新增或銷毀 — 只是重新組織 code。如果 plan 出現任何 destroy 或 forces replacement，在 prod 路徑上停下來查 moved 區塊哪裡寫錯。

第二步：參數化

把寫死的值換成 prod 的參數：把現況值搬進 environments/prod/terraform.tfvars，module 改吃參數。plan 仍須零變更，因為參數值就等於現況值。這一步的驗證方式很機械：每個從字面值改成變數引用的欄位，都能在 tfvars 裡找到完全相同的值。

第三步：新增其他環境

複製 prod 的呼叫結構成 environments/dev/，給它自己的 backend（獨立 state）與縮小的參數值。這一步是純新增、不碰 prod。先在 dev apply 出一套完整的縮小版環境、確認 module 在新環境也能 plan/apply 乾淨，再回頭確信 prod 的重構沒有副作用。

風險控制

最大的風險集中在前兩步：現有資源是活的，任何讓工具判定「需要替換」的改動，對 IAM 角色可能是短暫權限真空、對 VPC 可能是子網重建導致服務中斷。防護措施有三個層級：

第一，把每一次 plan 的輸出當成必須為零的驗收條件。非零就停下來查 moved 區塊或參數值哪裡跟現況不符。狀態危險的訊號是 plan 出現任何 destroy 或 forces replacement，在 prod 路徑上這幾乎都該暫停。

第二，在 retrofit 開始前備份 state 檔。S3 backend 有 versioning 可以回捲，但多一份本地備份增加保險層：

1# retrofit 前備份 state
2aws s3 cp s3://acme-tf-state/prod/terraform.tfstate \
3  ./state-backup-$(date +%Y%m%d).tfstate

第三，moved 區塊優先用宣告式（可 review、可回滾），手動 state mv 留給 moved 表達不了的跨 module 搬遷。整個 retrofit 走 PR 流程、讓 plan 輸出在 review 時可見，見模組七：infra 走 PR 流程。

時程參考：10-20 個資源的典型環境，從單環境拆成 module + per-env 結構約需 1-2 週（含每步 plan 驗證與跨環境推送）。50 個以上資源的環境需要 3-4 週分階段執行，每階段以一組功能相關的資源為單位。這些時程的主要變數是 stateful 資源的數量——每個 stateful 資源的 moved/import 操作都需要額外的 plan 驗證與備份保險。

跨分類引用

• → 模組一：最小可行 IaC：每個環境的 state 怎麼隔開
• → 模組二：身分與憑證地基：帳號級隔離的權限邊界
• → 模組三：網路地基：跨可用區冗餘的網路面
• → 模組五：核心服務上 IaC：核心服務怎麼用 module 跨環境重用
• → 模組七：infra 走 PR 流程：retrofit 的 plan 輸出怎麼進 review
• → 跨帳號策略：帳號級隔離是環境分離光譜最粗的一端

Retrofit 前的準備

Retrofit 操作的是正在服務的 production 資源，每一步都要確認「plan 顯示零變更」才能往下走。準備工作的目的是降低操作過程中的風險。

State 備份

開始之前把 state 拉一份完整備份到本地：

1terraform state pull > state-backup-$(date +%Y%m%d).json

這份備份是最後的回退手段。如果 retrofit 過程中 state 被弄壞（例如 moved block 指向錯誤的位置），可以用 terraform state push state-backup.json 回到起點重來。state push 會覆蓋遠端 state，屬於危險操作——只在回退時使用。

識別 stateful 資源

列出所有 state 裡的資源，標記哪些是 stateful（RDS、S3 含資料、EBS volume）：

1terraform state list | sort

Stateful 資源在 retrofit 過程中的風險最高：如果 moved block 寫錯導致 Terraform 判定需要 replace（先刪後建），stateful 資源的 replace 代表資料遺失。後面每一步的 plan 輸出都要特別檢查 stateful 資源有沒有出現 must be replaced 或 forces replacement。

確認 plan baseline

在還沒改任何 code 之前先跑一次 plan，確認起點是乾淨的：

1terraform plan -detailed-exitcode

Exit code 0 代表 state 與現實一致、沒有 drift。如果此時就有 drift（exit code 2），先解決 drift 再做 retrofit——在已經有 drift 的基礎上做結構重構，plan 的差異訊號會被 drift 淹沒，無法區分「drift 造成的差異」和「retrofit 造成的差異」。

步驟一：把資源宣告抽成 module

第一步純粹是程式碼重組——把 main.tf 裡的資源宣告搬進 modules/ 目錄，原地改成 module 呼叫。這一步不改任何資源屬性、不改 backend、不改 provider，所有值先寫死成當前的值。

目標目錄結構

 1infra/
 2├── modules/
 3│   ├── network/
 4│   │   ├── main.tf        # VPC、subnet、SG 從根目錄搬過來
 5│   │   ├── variables.tf   # 先把所有值寫死在 default 裡
 6│   │   └── outputs.tf     # 暴露 VPC ID、subnet IDs 等
 7│   └── database/
 8│       ├── main.tf        # RDS 從根目錄搬過來
 9│       ├── variables.tf
10│       └── outputs.tf
11├── main.tf                # 改成 module 呼叫
12├── backend.tf             # 不動
13└── terraform.tfvars       # 這一步還不存在

用 moved block 告訴 Terraform 搬家

資源從根目錄搬進 module 後，Terraform 的內部位址從 aws_vpc.main 變成 module.network.aws_vpc.main。如果不告訴 Terraform 這個對應關係，它會判定舊位址的資源「要刪」、新位址的資源「要建」——對 VPC 或 RDS 來說這代表服務中斷。

moved block 宣告式地描述搬遷：

 1moved {
 2  from = aws_vpc.main
 3  to   = module.network.aws_vpc.main
 4}
 5
 6moved {
 7  from = aws_subnet.public
 8  to   = module.network.aws_subnet.public
 9}
10
11moved {
12  from = aws_subnet.private
13  to   = module.network.aws_subnet.private
14}
15
16moved {
17  from = aws_db_instance.primary
18  to   = module.database.aws_db_instance.primary
19}

每個搬進 module 的資源都需要一條 moved block。遺漏任何一條，plan 就會顯示該資源要 destroy + create。

Zero-change plan 驗證

1terraform plan

這一步的 plan 輸出必須是：

1Plan: 0 to add, 0 to change, 0 to destroy.

如果 plan 顯示任何 add、change 或 destroy，先停下來檢查：

• destroy + create：moved block 遺漏或位址寫錯
• change：module 內的 resource 屬性跟搬進來之前不一致（漏了某個 attribute、default 值不同）
• add：新的 module output 或 data source 被 Terraform 當成新資源

修到 plan 顯示零變更才能 apply。apply 之後 state 裡的資源位址從 aws_vpc.main 更新成 module.network.aws_vpc.main，雲端資源本身不受影響。

安全暫停點：本步完成後 code 已重組、state 位址已更新、雲端資源未變，環境處於自洽狀態，可隔日繼續。

步驟二：把寫死的值換成參數

Module 內部的寫死值搬到 variables.tf，module 呼叫端從 terraform.tfvars 讀入。這一步的 plan 仍然必須是零變更——因為參數的值就等於原本寫死的值。

 1# modules/database/variables.tf
 2variable "instance_class" {
 3  type = string
 4}
 5
 6variable "multi_az" {
 7  type    = bool
 8  default = false
 9}
10
11variable "backup_retention_days" {
12  type    = number
13  default = 7
14}

1# main.tf — module 呼叫端
2module "database" {
3  source                = "./modules/database"
4  instance_class        = var.db_instance_class
5  multi_az              = var.db_multi_az
6  backup_retention_days = var.db_backup_retention_days
7}

1# terraform.tfvars — prod 的值
2db_instance_class        = "db.r6g.large"
3db_multi_az              = true
4db_backup_retention_days = 30

再跑一次 plan 確認零變更。值從寫死改成參數傳入，但傳入的值跟原來一樣，所以 Terraform 算出的差異是零。

安全暫停點：本步完成後 module 已參數化、prod 行為不變，可隔日繼續。

步驟三：建立新環境目錄

prod 確認穩定後，建 dev 環境的獨立目錄。這一步是純新增——不碰 prod 的任何檔案。

 1infra/
 2├── modules/           # 共用（不動）
 3├── environments/
 4│   ├── prod/
 5│   │   ├── main.tf          # 原本根目錄的 module 呼叫搬過來
 6│   │   ├── backend.tf       # prod 的 state 位址
 7│   │   └── terraform.tfvars # prod 的值
 8│   └── dev/
 9│       ├── main.tf          # 複製 prod 的 module 呼叫
10│       ├── backend.tf       # dev 的獨立 state 位址
11│       └── terraform.tfvars # dev 的縮小值

dev 的 terraform.tfvars 用縮小的規格：

1# environments/dev/terraform.tfvars
2db_instance_class        = "db.t3.micro"
3db_multi_az              = false
4db_backup_retention_days = 1

dev 的 backend.tf 指向獨立的 state 路徑——dev 和 prod 的 state 從一開始就是分開的，不存在「事後拆」的需求：

1terraform {
2  backend "s3" {
3    bucket         = "acme-tf-state"
4    key            = "dev/terraform.tfstate"
5    region         = "ap-northeast-1"
6    encrypt        = true
7    dynamodb_table = "acme-tf-lock"
8  }
9}

如果原本的 prod 是在根目錄操作（不是在 environments/prod/ 目錄），這一步還需要把 prod 的操作也搬進 environments/prod/。這個搬遷本身又是一次 moved block + zero-change plan 驗證的循環。

安全暫停點：本步是純新增（建目錄和檔案），不影響 prod 的 state 或資源，可隔日繼續。

步驟四：先在 dev apply 驗證

1cd environments/dev
2terraform init
3terraform plan
4terraform apply

dev 是全新環境、全新 state，apply 會建出一整套資源。這一步驗證的是 module 在「從零建立」的情境下能否正常運作。如果 dev apply 成功且環境可用，代表 module 的邏輯正確。

dev 環境 apply 後跑一次 plan 確認零 drift：

1terraform plan -detailed-exitcode
2# 預期 exit code 0

安全暫停點：dev 環境已驗證、prod 未受影響，可隔日繼續最後的 prod 驗證。

步驟五：驗證 prod 未受影響

回到 prod 目錄，跑 plan 確認 prod 的資源沒有任何變化：

1cd environments/prod
2terraform plan -detailed-exitcode
3# 預期 exit code 0

如果此時 prod plan 顯示差異，可能的原因：

• prod 的 module 呼叫路徑變了（source = "./modules/..." → source = "../../modules/..."）但 moved block 沒跟著更新
• terraform.tfvars 的某個值跟原本寫死的不一致
• provider 版本在 init 時升級了

修到零變更。這一步結束後 retrofit 完成——prod 和 dev 各持獨立 state、共用同一套 module、環境差異全部收斂在 tfvars 裡。

常見陷阱

moved block vs terraform state mv

兩者都能告訴 Terraform 資源搬了家。moved block 是宣告式的——寫在 HCL 裡、可以 review、可以 revert（刪掉 moved block 就回去）。terraform state mv 是命令式的——直接改 state，沒有 review 機制、改完沒有 undo。

優先用 moved block。state mv 留給 moved block 表達不了的情境：跨 state 搬遷（把資源從一份 state 移到另一份）、或 Terraform 版本太舊不支援 moved block（0.13 以下）。

forces replacement 觸發

某些 resource 的某些 attribute 是「改了就要重建」的（immutable attribute）。常見的觸發：

Retrofit 過程中如果不小心改了這些 attribute（例如把 identifier = "mydb" 參數化時打錯了值），plan 會顯示 must be replaced。stateful 資源的 replacement 代表先刪後建——對 RDS 來說就是資料遺失。所以每一步 plan 都要特別檢查有沒有 forces replacement 的輸出。

State locking 與並行操作

Retrofit 期間如果有其他人同時 apply（CI pipeline 被觸發、同事在操作），兩邊的 state 操作會衝突。DynamoDB lock table 會擋下並行的 apply，但 init 和 plan 不一定會被擋。

操作建議：retrofit 開始前在團隊頻道通知「infra 暫停操作」，retrofit 完成後再解除。如果用 Atlantis，可以暫時鎖定 apply 權限。時程參考：10-20 個資源的環境，步驟一到五約需半天到一天。

跨分類引用

• → 環境分離與模組化：retrofit 的目標結構與設計原則
• → IaC 工具選型與 state 地基：state backend 的設定與 lock 機制
• → 模組五：Stateful 資源保護：stateful 資源的 replacement 風險
• → infra 走 PR 流程：retrofit 的每一步走 PR 讓 plan 可被 review