這個結構的操作極限會在兩個時間點浮現：第一次需要在正式環境以外的地方驗證變更時，以及第二個人開始操作同一組資源時。以下依序說明每個階段的操作現實與對應的 infra 需求。

資料庫變更需要驗證環境

應用新增功能時經常需要改資料庫的表結構 — 加欄位、改索引、拆表。這類操作（database migration）如果語法有誤或邏輯有缺，可能導致服務中斷或資料不一致。正常做法是先在非正式環境驗證通過，再推到 production 執行。

單一環境的情況下沒有驗證的場所。三種應對方式各有不同的風險邊界：

直接在 production 執行。成本最低，風險最高。migration 腳本跑下去的那一刻，正在使用服務的使用者直接承受後果 — 一個鎖住整張大表的 ALTER TABLE 會讓所有查詢卡住，一個 DROP COLUMN 刪錯欄位會造成不可逆的資料遺失。服務規模小、使用者少時代價尚可承受；一旦服務開始承載營收或外部依賴，這個做法的風險代價就超過了它省下的時間。

手動複製一套環境。到 Console 上照 production 的設定重新建一台 EC2、開一台 RDS、配一組 security group，得到一套「看起來一樣」的 staging。migration 先在 staging 驗證再推 production。這解決了驗證場所的問題，但引入了漂移問題 — 下一節說明。

用程式碼描述環境，讓工具複製。把 production 的設定寫成描述檔，用 Terraform 或 OpenTofu 根據同一份描述建出 staging。初始成本比手動複製高（要學工具、寫描述檔），但它保證了手動複製保證不了的一件事：staging 和 production 的結構來自同一份描述，差異只存在於刻意不同的參數（機器規格、備份天數）。這就是 Infrastructure as Code（IaC）的起點。

手動複製的環境會漂移

手動複製的 staging 在建立當天跟 production 一致。一個月後通常不再一致。

漂移的來源是日常操作中的局部調整：staging 的 security group 多了一條規則（某次除錯時加的，事後忘了刪）、production 的 RDS 參數被調過（線上出現慢查詢，DBA 改了 work_mem 但沒同步 staging）、staging 的 IAM role 多了一條 policy（測試新功能時加的，測完沒拿掉）。每一筆差異都很小，小到不值得專門同步，但它們會累積。

漂移引爆的時機跟產生的時機通常隔很遠。一個 migration 在 staging 通過、推到 production 失敗，排查半天後發現是一個月前的參數調整造成的 — staging 的 work_mem 跟 production 不同，剛好影響了這次 migration 的執行計畫。這種因果關係跨越時間的錯誤，排查成本遠高於錯誤本身。

漂移的根源是「兩套環境各自獨立維護」。只要兩份設定各自存在，同步就完全依賴操作者的記憶與紀律，而記憶會衰退、紀律會在壓力下鬆懈。結構性的解法是讓兩套環境共用同一份設定，差異只存在於刻意控制的參數。

同一份描述、不同的參數

IaC 工具消除漂移的方式，是把環境的結構寫成一份 module，用不同的參數值建出不同環境。程式碼只有一份，結構保證相同；差異全部收斂在參數裡，每一處「故意不同」都是明確且可審查的。

一個描述資料庫的 module：

 1variable "instance_class" {
 2  type = string
 3}
 4
 5variable "backup_retention_days" {
 6  type    = number
 7  default = 7
 8}
 9
10resource "aws_db_instance" "main" {
11  engine                  = "postgres"
12  instance_class          = var.instance_class
13  backup_retention_period = var.backup_retention_days
14}

Production 傳入大機器和長備份，staging 傳入小機器和短備份：

 1# production
 2module "database" {
 3  source                = "./modules/database"
 4  instance_class        = "db.r6g.large"
 5  backup_retention_days = 14
 6}
 7
 8# staging
 9module "database" {
10  source                = "./modules/database"
11  instance_class        = "db.t3.small"
12  backup_retention_days = 3
13}

兩個環境跑的是同一段 module 程式碼。引擎版本、連線方式、安全設定完全相同（寫在 module 裡、不是參數），差異只有機器規格和備份天數（刻意透過參數控制）。改動 module 一次、兩個環境同時生效，漂移的空間被結構性消除。

IaC 工具會維護一份 state 記錄，追蹤每個環境裡實際建了哪些資源和它們的屬性。改了程式碼後跑 terraform plan，工具會比對新的程式碼和 state 的差異，列出「會新增 / 修改 / 刪除什麼」。確認差異符合預期後才執行 apply。state 的角色與安全存放方式在模組一：最小可行 IaC 展開，環境的目錄結構與 module 設計在模組四：環境分離與模組化 展開。

環境分離牽出的後續關注點

環境分離解決了「在哪裡驗證」和「為什麼 staging 跟 production 不同」的問題。但多環境運行後，一組後續的操作需求會依序浮現，每一個對應 infra 的一個能力層：

身分與權限隔離。三個環境代表三組資源。如果所有人對所有環境都有完整操作權限，一次誤操作就可能改壞 production。production 的修改權限應該比 staging 嚴格、操作身分應該分開。這是模組二：身分與憑證地基的範圍。

變更審查流程。多人同時操作 infra 時，沒有經過 review 的變更會互相覆蓋。把 infra 變更接上跟應用程式碼相同的 PR 流程 — 開分支、自動跑 plan、review 通過才 apply — 讓每一次改動都有提案、審查和歷史。這是模組七：infra 走 PR 流程的範圍。

機密值管理。資料庫密碼、API key 這些機密值在有版本控制之前可能直接寫在 .env 或 CI 變數裡。一旦有了 IaC 和 git，這些值如果跟著程式碼進了版本歷史，就會隨著每一次 clone 擴散。機密值要存在專用的密鑰管理服務裡，程式碼只持有指向它的參照。這是模組八：治理好習慣的範圍。

可觀測性。三個環境各自需要 log、metric 和告警，這些監控要跟環境本身一起建立，而非等服務中斷後才發現沒有可查的資料。這是模組六：可觀測性與 log 的範圍。

網路邊界。三個環境如果共用同一個網段和防火牆規則，staging 的某個被入侵的服務可能橫向觸及 production 的資料庫。每個環境需要有自己的網路邊界。這是模組三：網路地基的範圍。

這些關注點的共同根源是同一件事：當服務從單人單環境長成多人多環境，原本藏在記憶和手動操作裡的決策，必須變成可描述、可審查、可重建的規則。整套教材的地圖在模組零：infra 是什麼，每個模組各自處理一個能力層。

跨分類引用

• → 模組零：infra 是什麼：責任邊界與成熟度階梯（從全手動到全程式碼治理的五階分級）的完整定義
• → 模組負一：還沒有 infra 的環境：導入 IaC 之前的低成本護欄
• → 模組一：最小可行 IaC：state 與 IaC 工具的選型與起步
• → 模組四：環境分離與模組化：目錄結構、module、參數化的完整設計

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

環境分離的本質是把「同一套基礎設施定義」複製成多份隔離的執行實例，每份有自己的 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

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

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

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

判讀訊號很簡單：如果現在只有一份 main.tf、裡面同時宣告了 dev-db 跟 prod-db，這個專案已經欠下環境分離的債，債齡每天都在增加。下一步路由是先確立目錄骨架，再決定差異怎麼參數化。

目錄分離 vs Terraform workspace 的取捨

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

在挑這兩條路之前，先把它們放回完整的分離強度光譜：環境分離橫跨一條從帳號到 workspace、隔離由粗到細的階梯，目錄與 workspace 只是相鄰的兩格，依隔離需求與維運成本取捨決定落在哪一格。最粗也最強的是帳號級隔離 — dev 與 prod 落在不同雲端帳號，憑證、計費與權限邊界天然分開，帳號邊界讓誤操作止於單一帳號（見模組二：身分與憑證地基）。次強的是每環境一個獨立 repo，把 code、IAM 權限與 CI pipeline 都按環境切開，適合各環境由不同團隊維護或受不同合規等級約束。再往細是本章主要討論的目錄分離 — 同一 repo 內各環境有獨立目錄與 state，邊界仍顯式、但共用一套 code 與一組權限。最細的是 workspace，code 完全共用、只在執行期切換 state。光譜越靠粗的一端，隔離越強、跨環境共用越少、初始與維運成本越高；越靠細的一端，重複越少、邊界越隱性。多數早期團隊在目錄分離這一格落腳，因為它在顯式邊界與維運成本之間平衡得宜；當隔離需求升高（例如 prod 要法規等級的帳務與權限隔離），再沿光譜往帳號級或獨立 repo 移。

目錄分離把每個環境寫成可獨立進入的工作目錄，差異透過各自的 terraform.tfvars 表達，prod 的 backend 設定、變數值、甚至 provider 版本都各自鎖定。它的代價是目錄之間有重複的 boilerplate，好處是邊界顯式 — 你 cd 進哪個目錄、apply 就只會動那個環境，prod 的 state 位址寫死在 prod 目錄的 backend 設定裡，不會因為忘記切換而打錯環境。

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

 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 的差異值

Workspace 共用同一份 code、用 terraform workspace select prod 在執行期切換 state。它的好處是零重複，所有環境的 code 保證同步；代價是環境差異只能靠 terraform.workspace 在 code 裡寫條件判斷，而當前選中哪個 workspace 是 shell 的隱性狀態 — 在 dev workspace 以為自己在改 dev、其實上一個指令切到了 prod，apply 下去才發現故障半徑是 prod。這個隱性狀態正是早期最該避免的失誤來源。

早期推薦目錄分離，理由是故障半徑與認知負荷的取捨在小團隊明顯偏向「顯式邊界」這一側：團隊還沒有成熟的 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}
 5
 6variable "multi_az" {
 7  type    = bool
 8  default = false
 9}
10
11variable "backup_retention_days" {
12  type    = number
13  default = 7
14}

1# environments/prod/main.tf — prod 傳自己的值
2module "database" {
3  source                = "../../modules/database"
4  instance_class        = "db.r6g.xlarge"
5  multi_az              = true
6  backup_retention_days = 30
7}

這樣 dev 與 prod 跑的是位元層級相同的 module code，差異全部收斂在 main.tf 的呼叫參數裡、一眼可審。判讀訊號是 review 時只要 diff 各環境的參數區塊就能看完所有環境差異；如果發現有人為了某環境的特例去改 module 內部，那是漂移正在發生的徵兆，該把特例改寫成新的參數。核心服務怎麼用 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 不需要。這類用 count 或 for_each 配一個布林參數開關，仍然走參數化、不分叉 code。跨可用區與冗餘的網路面怎麼鋪，見模組三：網路地基。

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

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

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

1. 把現有資源宣告抽成 module：把 main.tf 裡的資源搬進 modules/、原地用 module 呼叫取代，所有值先寫死成現況。此時 plan 必須顯示無任何新增或銷毀 — 只是重新組織 code，資源在 state 裡的位址若有變，用 moved {} 區塊宣告搬遷、避免工具誤判為「銷毀舊的、建新的」。
2. 把寫死的值換成 prod 的參數：把現況值搬進 environments/prod/terraform.tfvars，module 改吃參數。plan 仍須零變更，因為參數值就等於現況值。
3. 建立其他環境目錄：複製 prod 的呼叫結構成 environments/dev/，給它自己的 backend（獨立 state）與縮小的參數值。這一步是純新增、不碰 prod。
4. 逐一驗證：先在 dev apply 出一套完整的縮小版環境、確認 module 在新環境也能 plan/apply 乾淨，再回頭確信 prod 的重構沒有副作用。

最大的風險集中在前兩步：現有資源是活的，任何讓工具判定「需要替換」的改動，對 IAM 角色可能是短暫權限真空、對 VPC 可能是子網重建導致服務中斷。防護是把每一次 plan 的輸出當成必須為零的驗收條件，非零就停下來查 moved 區塊或參數值哪裡跟現況不符。狀態危險的訊號是 plan 出現任何 destroy 或 forces replacement，在 prod 路徑上這幾乎都該先暫停。第二個風險是 state 操作本身 — retrofit 期間務必先備份 state 檔，state mv 與 moved 區塊優先用後者（宣告式、可 review、可回滾），手動 state mv 留給 moved 表達不了的跨 module 搬遷。整個 retrofit 走 PR 流程、讓 plan 輸出在 review 時可見，見模組七：infra 走 PR 流程。

章節文章

跨分類引用

• → 模組一：最小可行 IaC：每個環境的 state 怎麼隔開
• → 模組五：核心服務上 IaC：核心服務怎麼用 module 跨環境重用

概念位置

Environment Protection 位在部署 job 與目標環境之間，包含 reviewer、wait timer、branch policy 與 secret scope。

可觀察訊號

• 測試綠燈後仍需要人工批准才能進 production。
• 不同環境需要不同發布權限與審核規則。
• 發布失誤常來自權限配置或保護規則缺失。

接近真實服務的例子

GitHub Actions deploy job 指向 production environment，需指定 reviewer 批准後才可部署。staging 則採自動放行。

設計責任

Environment Protection 要定義環境分層、審核責任、發布時窗與例外流程，讓高風險發布有明確控制面。

概念位置

環境分離在 infra 成熟度階梯上對應第三階。它建立在宣告式 IaC（第二階）的基礎上 — 有了 state 追蹤和模組化描述之後，才能用「同一份 code、不同參數」的方式複製出多個隔離環境。

分離的實作方式有一條隔離強度光譜：從帳號級（不同雲端帳號，最強隔離）到目錄級（同一 repo 內各環境一個目錄，各自持有 state）到 workspace 級（同一份 code 用執行期切換 state，隔離最弱）。多數早期團隊在目錄級落腳，因為它在顯式邊界與維運成本之間取得平衡。

可觀察訊號

以下狀況指向環境分離不足：

• 在 staging 測試的變更意外影響了 production 的資源 — dev 跟 prod 共用同一份 state
• 某人的 terraform apply 把另一個環境的資源改掉了 — workspace 的隱性狀態切換導致打錯環境
• dev 與 prod 的設定差異散落在 code 裡的 if env == "prod" 判斷 — 環境差異沒有集中在參數值裡

設計責任

環境分離的設計要決定：

• 隔離層級：帳號級、目錄級、還是 workspace 級。判斷依據是團隊規模、合規要求、與維運餘裕
• 參數化邊界：dev 與 prod 之間的差異全部用參數表達（instance size、multi-AZ、backup retention），module 內部不寫環境判斷
• state 位址分離：每個環境的 state backend 位址獨立，互不交叉

鄰卡

• IaC — 環境分離的前提是有可重用的 IaC 描述
• State — 每個環境持有獨立的 state 檔
• Drift — 環境分離降低 drift 的跨環境影響範圍