以下步驟是寫第一行 IaC 之前需要就位的前置條件。如果已經備妥可以跳過。如果是第一次接觸雲端帳號，先讀拿到雲端帳號的第一天做安全底線和帳號現況判讀。

雲端帳號。需要一個 AWS 帳號（或 GCP / Azure，本模組以 AWS 為主要範例）。註冊完成後立刻對 root 帳號啟用 MFA（Multi-Factor Authentication）——root 帳號是整個雲端環境的最高權限，沒有 MFA 等於大門沒鎖。啟用路徑：AWS Console → 右上角帳號名稱 → Security credentials → Multi-factor authentication (MFA) → Assign MFA device。日常操作用 IAM user 或 IAM Identity Center 登入，root 帳號只在需要 root-only 操作時使用。

本機工具。安裝 IaC CLI（Terraform 或 OpenTofu）和雲端 CLI（AWS CLI）：

1# macOS
2brew install opentofu awscli
3
4# Arch Linux（opentofu 和 aws-cli-v2 在 AUR，需要 AUR helper）
5yay -S opentofu-bin aws-cli-v2
6
7# 驗證安裝
8tofu --version
9aws --version

雲端認證。本機需要能對雲端 API 認證。最直接的方式是用 AWS CLI 設定 credentials：

1aws configure
2# 輸入 Access Key ID、Secret Access Key、預設 region（如 ap-northeast-1）

這組 access key 來自 IAM user。如果帳號裡還沒有 IAM user，到 AWS Console → IAM → Users 建立一個、附加 AdministratorAccess policy、在 Security credentials 分頁建立 access key。正式環境應該用 SSO 或 short-lived credentials 取代長期 key（模組二會展開），但起步階段一組 IAM user key 足以讓 tofu apply 跑起來。

Git repo。IaC 程式碼從 day 1 就應該在版本控制裡——這是模組零「可重建路徑」的落地前提。建一個 Git repo，後續所有 .tf 檔都放在這裡：

1mkdir infra && cd infra
2git init
3echo '.terraform/' > .gitignore
4echo '*.tfstate'  >> .gitignore
5echo '*.tfstate.*' >> .gitignore
6git add .gitignore && git commit -m "init: gitignore for terraform"

.gitignore 排除 .terraform/（provider 快取）和 *.tfstate（state 檔含敏感值，存放策略見下方 remote state 段落）。

踏上成熟度階梯（從全手動到全程式碼治理的五階分級）第二階（宣告式 IaC，也就是 state 檔誕生那一階）的最小路徑，從兩件事開始：選對工具、把 state 管好。工具決定用什麼語言描述基礎設施，state 則是工具對雲端現實的唯一記憶。這份記憶存在哪、怎麼保護、怎麼防止並行寫壞，是整套 IaC 能不能站穩的地基。

IaC 工具選型：宣告式狀態管理 vs 程式語言抽象

IaC 工具的核心職責是把「我要的基礎設施長什麼樣」描述成可版本控制的程式碼，再由工具負責算出現況與目標的差異並收斂。市場上的工具分成兩條路線，差別落在「用什麼語言描述」與「狀態由誰持有」這兩個軸上，而非功能多寡。

宣告式 DSL 路線

第一條路線的代表是 Terraform 與其開源分支 OpenTofu。寫的是 HCL（HashiCorp Configuration Language），描述的是資源的最終樣貌，工具自己維護一份 state 來追蹤每個資源的真實 ID 與屬性。

 1resource "aws_s3_bucket" "artifacts" {
 2  bucket = "acme-deploy-artifacts"
 3}
 4
 5resource "aws_s3_bucket_versioning" "artifacts" {
 6  bucket = aws_s3_bucket.artifacts.id
 7  versioning_configuration {
 8    status = "Enabled"
 9  }
10}

這段 HCL 描述的是「一個開了 versioning 的 S3 bucket 應該存在」。第一次 apply 時工具建立它，之後每次 apply 時工具比對 state 與雲端現況，只做差異收斂。讀的人看 HCL 就知道最終結果長什麼樣，不需要在腦中追蹤執行順序。

這條路線適合團隊成員背景混雜、需要讓非專職後端的人也能讀懂 infra 定義的情境 — HCL 的閱讀門檻低，diff 直觀，review 時看得出「這個 PR 會新增一個 RDS、改掉一條 security group」。缺點是 HCL 的表達力有限：遇到需要大量條件分支或動態生成的場景時，語法會變得笨拙，count、for_each、dynamic 區塊很快就堆出難以閱讀的嵌套。

程式語言路線

第二條路線的代表是 AWS CDK 與 Pulumi。寫的是 TypeScript、Python、Go 這類語言，靠迴圈、函式、類別來生成資源。這條路線適合 infra 邏輯本身複雜、需要大量條件分支與抽象複用的團隊，例如要根據環境清單動態生成數十組對稱資源。

代價是 review 難度上升。一段 for 迴圈展開後到底建了哪些東西，得在腦中執行程式才看得出來，diff 不再等於變更本身。一個抽象類別改了一行建構子參數，展開後可能影響所有繼承它的資源，而 PR diff 上只看到那一行。對跨職能 review（PM、SRE、安全團隊都要看的變更）來說，這是可感知的閱讀成本。

CDK vs Pulumi：狀態由誰持有

CDK 與 Pulumi 同屬程式語言路線，但「狀態由誰持有」這個軸把它們再分開。

CDK 把程式碼 synth 成 CloudFormation 模板，再交給 CloudFormation 服務端執行與追蹤。state 由 AWS 代管 — 沒有一份 tfstate 檔要自己存放、加密、回捲，也不需要額外的鎖表來防並行。這份「狀態維運外包給雲端」正是 CDK 在 AWS 生態內的賣點之一。代價是綁定 CloudFormation 與單一雲 — CloudFormation 的更新速度、resource coverage、錯誤訊息品質都由 AWS 控制，團隊的 debug 能力受限於 CloudFormation 的回報粒度。

Pulumi 走另一邊：它維護一份自己的 state，預設交給 Pulumi Cloud 託管，也能改用 S3 之類的後端自管。形態上更接近 Terraform 的 state 模型，state 的存放、保護與並行控制重回團隊手上。同一條程式語言路線，選 CDK 等於把 state 責任讓給雲端，選 Pulumi 則保留對 state 落點的掌控。

選型判準

選型看的是團隊組成與變更的審查需求，可以用一張決策表歸納：

若多數變更要跨職能 review、希望 diff 一眼可讀，宣告式 DSL 較划算；若 infra 由專職平台團隊維護、抽象複用的收益大於審查透明度的損失，程式語言路線較划算。

Terraform 與 OpenTofu 之間，OpenTofu 是授權變更後社群分叉出的相容實作，HCL 與 provider 生態幾乎共用；選擇主要看對授權條款與治理模式的偏好，技術判準在這一階沒有實質差異。本模組後續一律以 HCL 示意，換成任一宣告式工具判準仍成立。

上述兩條路線之外，還有兩類工具走不同的運作模型。Kubernetes-native 路線（代表是 Crossplane）用 CRD 描述雲資源、由 controller 持續收斂，state 由 Kubernetes 的 etcd 持有，適合已經重度投入 Kubernetes 的團隊。Serverless-first 框架（代表是 SST）把部署與 IaC 合一，適合全 serverless 架構。這兩條路線的 state 模型與 CLI 驅動的 plan/apply 流程不同，本系列不展開。

state 是工具對現實的唯一記憶

state 是 IaC 工具用來記錄「上一次 apply 之後，每個資源在雲端真實長什麼樣」的快照。它的作用是讓工具能算出「現況」與「目標」之間的最小差異。沒有 state，工具每次都得把所有資源重新查一遍才知道該不該動，而且無法分辨「這個資源是我建的、該由我管」還是「別人手動建的、不歸我管」。

一份 state 的實際內容大致長這樣（簡化版）：

 1{
 2  "resources": [
 3    {
 4      "type": "aws_s3_bucket",
 5      "name": "artifacts",
 6      "instances": [
 7        {
 8          "attributes": {
 9            "id": "acme-deploy-artifacts",
10            "arn": "arn:aws:s3:::acme-deploy-artifacts",
11            "bucket": "acme-deploy-artifacts",
12            "tags": { "env": "prod", "owner": "platform" }
13          }
14        }
15      ]
16    }
17  ]
18}

state 裡通常含有資源的真實 ID、相依關係，以及部分敏感屬性 — 例如資料庫的初始密碼、private key 的輸出值、加密金鑰的 ARN。這帶來兩條硬邊界，違反任一條都會在未來製造代價高昂的事故。

state 絕不能進 git

state 含明文敏感值，一旦推進版控就等於把密碼寫進每個 clone 的歷史裡。事後 rotate 密碼也清不掉 git 歷史 — 因為 git 是 append-only 的，舊版本的 state 永遠留在 commit 裡，除非用 git filter-branch 或 git filter-repo 重寫整條歷史（這本身是一個破壞性操作，會影響所有已經 clone 的副本）。

在 .gitignore 裡搜尋 *.tfstate 和 *.tfstate.backup——如果這兩行不在，state 有進版控的風險。在 repo 根目錄執行一次搜索確認：

1git log --all --diff-filter=A -- '*.tfstate'

如果有任何結果，代表 state 曾經被 commit 過，那些 commit 裡的敏感值已經暴露。

state 不能只放本地

本地 state 的失敗模式是它把整份基礎設施的記憶綁在一台筆電上 — 換人接手、換台機器、或多人同時 apply 時，記憶就分裂了。

具體場景：工程師 A 在自己的筆電 apply 了一次，state 記住「已經建了 3 個 security group」。工程師 B 在另一台筆電上拉了同一份 code，但她的本地沒有 state（或有一份過時的 state），apply 時工具以為那 3 個 security group 不存在，又建了 3 個重複的。更糟的場景是 B 的 state 比 A 舊，工具對比後認為 A 後來新增的 security group「不在記憶裡、是多餘的」，於是 apply 時把它們刪掉 — 而 A 還以為那些規則還在保護服務。

這兩條邊界共同指向同一個結論：state 需要一個團隊共享、有版本、有存取控制、且能防止同時寫入的存放處。這就是 remote state backend 要解的問題。

remote state backend：自管 vs 託管

remote state backend 是把 state 從本地移到團隊共享儲存的機制，它要同時滿足三件事：持久保存、防止並行寫入衝突、以及保護敏感內容。達成方式分成自管儲存與託管服務兩種，差別在維運責任落在誰身上。

自管 backend

自管路線以雲端物件儲存加鎖機制為典型組合。以 AWS 為例，state 檔放 S3、用一張 DynamoDB 鎖表防止兩個人同時 apply：

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

這段設定的每一項都對應前一節的一條邊界：

encrypt = true 讓 state 在 S3 落地時加密，回應「state 含敏感值」的風險。加密用的是 S3 的 server-side encryption，搭配 KMS key 可以進一步控制誰能解密。

bucket versioning 是這段設定裡沒有出現、但在建立 bucket 時就該開的屬性。apply 寫壞或誤刪 state 時，versioning 是把記憶回捲到上一個正確版本的唯一退路。沒開的話一次壞寫就讓工具失去對現實的記憶，而回復的唯一方式是從雲端逐個資源重新 import。建立 state bucket 的 HCL 應該同時開 versioning 與刪除保護：

 1resource "aws_s3_bucket_versioning" "state" {
 2  bucket = aws_s3_bucket.tf_state.id
 3  versioning_configuration {
 4    status = "Enabled"
 5  }
 6}
 7
 8resource "aws_s3_bucket_lifecycle_configuration" "state" {
 9  bucket = aws_s3_bucket.tf_state.id
10
11  rule {
12    id     = "retain-old-versions"
13    status = "Enabled"
14
15    noncurrent_version_expiration {
16      noncurrent_days = 90
17    }
18  }
19}

舊版本的保留天數是成本與安全的取捨。90 天足以涵蓋大多數「發現 state 壞了再回去找正確版本」的時間差 — 超過 90 天才發現的 state 問題通常已經被後續 apply 覆蓋，回捲到更早的版本反而引入更大的落差。

dynamodb_table 指向一張鎖表。apply 開始時寫入一筆鎖、結束才釋放，第二個人同時跑就會被擋下並提示鎖被誰持有。這正是本地 state 無法提供、卻是多人協作底線的並行保護。鎖表本身的建立只需要幾行 HCL：

 1resource "aws_dynamodb_table" "tf_lock" {
 2  name         = "acme-tf-lock"
 3  billing_mode = "PAY_PER_REQUEST"
 4  hash_key     = "LockID"
 5
 6  attribute {
 7    name = "LockID"
 8    type = "S"
 9  }
10}

鎖表用 PAY_PER_REQUEST 模式足夠，因為它的讀寫頻率很低（只在 apply 開始和結束時各一次）。鎖卡住時（apply 中途失敗、沒有正常釋放鎖），用 terraform force-unlock <lock-id> 手動釋放，但前提是確認沒有其他 apply 正在執行。

key 是 state 在 bucket 內的路徑，這裡先用 prod/network 之類的分層命名。實際怎麼依環境切分 state 留待模組四：環境分離與模組化展開。

自管 backend 的雞生蛋問題

自管 backend 有一個啟動悖論：state bucket 和 lock table 本身也是雲端資源，它們該由誰來管理？用 Terraform 管理 Terraform 的 backend？

務實的做法是接受這個循環：用一份獨立的、最小化的 Terraform code 來建立 state bucket 和 lock table，這份 code 用 local state（因為它只在啟動那一次跑）。建立完成後，所有後續的 Terraform code 都指向這個 remote backend。這份啟動 code 的 local state 可以 commit 進 repo（它不含敏感值，只有 bucket 和 DynamoDB table 的 ID），或直接在跑完後丟棄 — 因為這些資源如果需要重建，幾行 CLI 就能做到。

 1# bootstrap/main.tf — 只用一次，建立 state 基礎設施
 2terraform {
 3  # 刻意用 local state，因為 remote backend 還不存在
 4}
 5
 6resource "aws_s3_bucket" "tf_state" {
 7  bucket = "acme-tf-state"
 8}
 9
10# ... versioning, encryption, lock table

託管 backend

託管路線把上述維運細節包起來，由 Terraform Cloud、Spacelift、env0 這類平台代管 state、鎖與加密，附帶 web UI 與 audit log。

判讀訊號是團隊規模與維運餘裕。自管 backend 的成本是要自己把 bucket versioning、加密、鎖表、IAM 權限配對，配錯任何一項都可能讓 state 失去保護 — 例如忘了開 versioning，一次壞寫就回不去。託管服務用月費換掉這份配置與維運負擔，代價是 state 託付給第三方、且進階治理功能常綁在付費級距。

小團隊起步、不想第一週就花在配 backend 上，託管較划算。對 state 存放位置有合規或主權要求、或希望基礎設施盡量自持的團隊，自管較划算。託管服務（Terraform Cloud / Spacelift）的免費方案涵蓋基本功能，付費級距約 $20-70/user/月；自管 backend 的成本是初次配置半天到一天的工程師時間，加上持續的 IAM 權限與 versioning 維護。

導入時程參考：最小可行 IaC（state backend + 第一批地基資源）的導入約需 2-3 天工程師時間。第一個可見里程碑是「一條指令能在新帳號重建整個地基環境」。之後每批服務的納管約 1-2 天/批，依資源複雜度而定。

State 地基設好後，下一步是立 Console 唯讀鐵律、並用最小可行資源集合驗證整條鏈路，見Console 唯讀鐵律與最小可行資源集合。

跨分類引用

• → Console 唯讀鐵律與最小可行資源集合：state 管好之後，Console 唯讀紀律與最小 apply 閉環
• → 模組二：身分與憑證地基：Console 唯讀鐵律靠權限落地
• → 模組四：環境分離與模組化：state 的 key 怎麼依環境切分

IaC 工具選型：宣告式狀態管理 vs 程式語言抽象

IaC 工具的核心職責是把「我要的基礎設施長什麼樣」描述成可版本控制的程式碼，再由工具負責算出現況與目標的差異並收斂。市場上的工具分成兩條路線，差別落在「用什麼語言描述」與「狀態由誰持有」這兩個軸上，而非功能多寡。

第一條路線是宣告式 DSL，代表是 Terraform 與其開源分支 OpenTofu。寫的是 HCL，描述的是資源的最終樣貌，工具自己維護一份 state 來追蹤每個資源的真實 ID 與屬性。這條路線適合團隊成員背景混雜、需要讓非專職後端的人也能讀懂 infra 定義的情境 — HCL 的閱讀門檻低，diff 直觀，review 時看得出「這個 PR 會新增一個 RDS、改掉一條 security group」。

第二條路線是用通用程式語言寫 infra，代表是 AWS CDK 與 Pulumi。寫的是 TypeScript、Python、Go 這類語言，靠迴圈、函式、類別來生成資源。這條路線適合 infra 邏輯本身複雜、需要大量條件分支與抽象複用的團隊，例如要根據環境清單動態生成數十組對稱資源。代價是 review 難度上升：一段 for 迴圈展開後到底建了哪些東西，得在腦中執行程式才看得出來，diff 不再等於變更本身。

CDK 與 Pulumi 同屬程式語言路線，但「狀態由誰持有」這個軸把它們再分開。CDK 把程式碼 synth 成 CloudFormation 模板，再交給 CloudFormation 服務端執行與追蹤，state 由 AWS 代管 — 沒有一份 tfstate 檔要自己存放、加密、回捲，也不需要額外的鎖表來防並行，這份「狀態維運外包給雲端」正是 CDK 在 AWS 生態內的賣點之一，代價是綁定 CloudFormation 與單一雲。Pulumi 走的是另一邊：它維護一份自己的 state，預設交給 Pulumi Cloud 託管，也能改用 S3 之類的後端自管 — 形態上更接近 Terraform 的 state 模型，state 的存放、保護與並行控制重回團隊手上。同一條程式語言路線，選 CDK 等於把 state 責任讓給雲端，選 Pulumi 則保留對 state 落點的掌控。

選型看的是團隊組成與變更的審查需求。若多數變更要跨職能 review、希望 diff 一眼可讀，宣告式 DSL 較划算；若 infra 由專職平台團隊維護、抽象複用的收益大於審查透明度的損失，程式語言路線較划算。Terraform 與 OpenTofu 之間，OpenTofu 是授權變更後社群分叉出的相容實作，HCL 與 provider 生態幾乎共用；選擇主要看對授權條款與治理模式的偏好，技術判準在這一階沒有實質差異。本模組後續一律以 HCL 示意，換成任一宣告式工具判準仍成立。

state 是工具對現實的唯一記憶

state 是 IaC 工具用來記錄「上一次 apply 之後，每個資源在雲端真實長什麼樣」的快照，它的作用是讓工具能算出「現況」與「目標」之間的最小差異。沒有 state，工具每次都得把所有資源重新查一遍才知道該不該動，而且無法分辨「這個資源是我建的、該由我管」還是「別人手動建的、不歸我管」。

state 裡通常含有資源的真實 ID、相依關係，以及部分敏感屬性 — 例如資料庫的初始密碼、private key 的輸出值。這帶來兩條邊界。

第一條：state 絕不能進 git。state 含明文敏感值，一旦推進版控就等於把密碼寫進每個 clone 的歷史裡，事後 rotate 也清不掉 git 歷史。

第二條：state 不能只放本地。本地 state 的失敗模式是它把整份基礎設施的記憶綁在一台筆電上 — 換人接手、換台機器、或多人同時 apply 時，記憶就分裂了。兩個人各自拿著不同版本的本地 state 去 apply，工具會用各自過時的記憶去算差異，互相把對方建的資源判定成「不該存在、刪掉」，基礎設施被反覆來回破壞。

這兩條邊界共同指向同一個結論：state 需要一個團隊共享、有版本、有存取控制、且能防止同時寫入的存放處。這就是 remote state backend 要解的問題。

remote state backend：自管 vs 託管

remote state backend 是把 state 從本地移到團隊共享儲存的機制，它要同時滿足三件事：持久保存、防止並行寫入衝突、以及保護敏感內容。達成方式分成自管儲存與託管服務兩種，差別在維運責任落在誰身上。

自管路線以雲端物件儲存加鎖機制為典型組合。以 AWS 為例，state 檔放 S3、用一張鎖表防止兩個人同時 apply：

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

這段設定的每一項都對應前一節的一條邊界，值得逐項拆開。encrypt = true 讓 state 在 S3 落地時加密，回應「state 含敏感值」的風險。承載 state 的 bucket 必須開 versioning：apply 寫壞或誤刪 state 時，versioning 是把記憶回捲到上一個正確版本的唯一退路，沒開的話一次壞寫就讓工具失去對現實的記憶。dynamodb_table 指向一張鎖表，apply 開始時寫入一筆鎖、結束才釋放，第二個人同時跑就會被擋下並提示鎖被誰持有 — 這正是本地 state 無法提供、卻是多人協作底線的並行保護。key 則是 state 在 bucket 內的路徑，這裡先用 prod/network 之類的分層命名，實際怎麼依環境切分 state 留待模組四：環境分離與模組化展開。

託管路線把這些維運細節包起來，由 Terraform Cloud、Spacelift 這類平台代管 state、鎖與加密，附帶 web UI 與 audit log。判讀訊號是團隊規模與維運餘裕：自管 backend 的成本是要自己把 bucket versioning、加密、鎖表、IAM 權限配對，配錯任何一項都可能讓 state 失去保護；託管服務用月費換掉這份配置與維運負擔，代價是 state 託付給第三方、且進階治理功能常綁在付費級距。小團隊起步、不想第一週就花在配 backend 上，託管較划算；對 state 存放位置有合規或主權要求、或希望基礎設施盡量自持的團隊，自管較划算。

Console 唯讀鐵律：把 Console 當儀表板，不當方向盤

Console 唯讀鐵律是一條操作紀律：雲端 Console 只用來觀察與排查，所有會改變資源的動作都回到程式碼走 apply。這條紀律維護的是 state 與現實的一致 — IaC 工具能正確運作的前提，是它的 state 反映得了真實世界，而每一次在 Console 點按鈕改設定，都是在 state 不知情的情況下動了現實。

這種 state 與現實的分歧叫 drift。drift 的代價會延遲引爆，而非當下浮現。某人在 Console 臨時把一條 security group 規則打開救火，state 並不知道；下一次別人為了不相干的變更跑 apply，工具拿過時的 state 去比對，會把那條手動規則判定成「不在我的記憶裡、刪掉」，於是悄悄關掉，救火的洞重新出現，而且沒人在 PR 裡看得到這件事發生過。Console 改得越多、與程式碼分歧越久，某次例行 apply 就越可能掃掉一批沒人記得的手動設定。

鐵律越早立越好，因為回頭納管的代價隨時間累積。手動建的資源要納入 IaC，得先用 terraform import 把現實資源綁進 state，再補一段與現實完全吻合的 HCL：

1terraform import aws_security_group.web sg-0abc123def456

import 只把資源 ID 寫進 state，不會幫忙生程式碼。那個資源在 Console 上被點出來的每一個屬性 — 每條 ingress 規則、每個 tag、每項關聯設定 — 都得一字不差地補成 HCL，任何一項對不上，下次 apply 就會試圖把現實改回程式碼寫的版本。一個資源還能忍，等到累積了幾十個各自手動微調過的資源才想納管，逆向工程的工作量會大到讓人乾脆放棄，基礎設施就此分裂成「程式碼管的」與「沒人敢動的」兩塊。第一天就立鐵律，要納管的存量永遠是零。

讓鐵律落地靠的是權限、不是自律。光靠約定「別在 Console 改」撐不久，救火當下手最快的永遠是 Console。真正讓鐵律站得住的，是把人的日常身分收斂成唯讀、把寫入權限留給跑 apply 的自動化身分，讓「在 Console 改不動」變成預設狀態 — 這道權限地基屬於模組二：身分與憑證地基的範圍，本階先確立紀律方向。

最小可行：能 apply 出一個完整環境的最小資源集合

最小可行 IaC 的目標是用最少的資源，跑出一條「改程式碼 → review → apply → 環境真的變了」的完整迴路。它承擔的責任是驗證地基本身能動，把所有服務都搬上來是後面的事。判準是這套程式碼能獨立 apply 出一個雖小但自洽、別人能重現的環境。

這一階的最小集合通常包含：一個設定好 versioning、加密與鎖表的 remote state backend；一個收斂後人類唯讀的身分權限基線；一個能放東西的網路骨架（一個 VPC 加最少的 subnet）；以及一個微不足道但真實存在的資源（例如一個 S3 bucket 或一台最小的測試機），用來證明 apply 確實作用到了雲端。把這個微小資源刻意留在最小集合裡，是因為它是最便宜的端到端驗證 — apply 跑完後它真的出現、terraform destroy 後它真的消失，就證明從程式碼到雲端的整條鏈路是通的。

刻意不放進來的東西同樣重要：正式的應用服務、資料庫、跨環境的複製、複雜的模組抽象，全部留到地基驗證通過之後。在 state 與 Console 唯讀都還沒站穩前就堆服務，等於把房子蓋在還沒灌漿的地基上。網路骨架怎麼長、身分怎麼切，分別由模組三：網路地基與模組二：身分與憑證地基接手深入；這一階只需要它們各自最薄的一層，湊出一個能 apply、能 destroy、能交接的閉環。

第一篇文章開頭有一段「動手前的前提」，列出寫第一行 IaC 之前需要就位的前置條件（雲端帳號 + MFA、CLI 工具安裝、雲端認證、Git repo 初始化）。已經備妥的讀者可以跳過。

章節文章

跨分類引用

• → 模組二：身分與憑證地基：Console 唯讀鐵律靠權限落地，人類唯讀、自動化身分持有寫入權
• → 模組三：網路地基：最小集合裡的 VPC 與 subnet 怎麼設計
• → 模組四：環境分離與模組化：state 的 key 怎麼依環境切分、state 跟環境怎麼對應
• → 模組七：infra 走 PR 流程：state 變更與 apply 怎麼納入 review
• → 接手維運：接手既有環境後的 IaC 導入路徑

Console 唯讀鐵律：把 Console 當儀表板，不當方向盤

Console 唯讀鐵律是一條操作紀律：雲端 Console 只用來觀察與排查，所有會改變資源的動作都回到程式碼走 apply。這條紀律維護的是 state 與現實的一致 — IaC 工具能正確運作的前提，是它的 state 反映得了真實世界，而每一次在 Console 點按鈕改設定，都是在 state 不知情的情況下動了現實。

drift 的延遲浮現

state 與現實的分歧叫 drift。drift 的後果在後續某次 apply 時才浮現——工具用過時的 state 比對雲端現況、把手動設定判定為「不該存在」並覆蓋掉，手動改的當下一切正常。手動改的當下一切正常，後果要等到下一次不相關的 apply 才出現。

常見的 drift 路徑：在 Console 手動加了一條 security group 規則（例如讓外部監控系統連進來），state 不知道這條規則存在。後續某次 apply 時，工具比對 state 和雲端現況、把這條規則判定為「不在記憶裡」而刪除。同樣的機制也發生在手動調整的 RDS parameter group（例如增加 max_connections）— 後續 apply 會把參數重設回程式碼裡的值。

Console 改得越多、與程式碼分歧越久，某次例行 apply 就越可能掃掉一批沒人記得的手動設定。drift 的累積是單調遞增的 — 每一次手動改動都加一筆，沒有任何自然機制會讓它減少。

drift 偵測

主動偵測 drift 的方式是定期跑 terraform plan 而不做 apply — plan 的輸出會列出「code 描述的狀態」與「雲端現況」之間的差異。如果 plan 在沒有 code 變更的情況下顯示非零差異，代表有人在背後動了資源。

1# 定期 drift 偵測：plan 結果非零就告警
2terraform plan -detailed-exitcode
3# exit code 0 = 無差異, 1 = 錯誤, 2 = 有差異

把這個 plan 接進 CI，讓 drift 在累積之前就被發現。判讀 plan 輸出時，重點看那些「會被 Terraform 改回去」的差異 — 它們就是手動變更的痕跡。

import 的痛苦

鐵律越早立越好，因為回頭納管的代價隨時間累積。手動建的資源要納入 IaC，得先用 terraform import 把現實資源綁進 state，再補一段與現實完全吻合的 HCL：

1terraform import aws_security_group.web sg-0abc123def456

import 只把資源 ID 寫進 state，不會幫忙生程式碼。那個資源在 Console 上被點出來的每一個屬性 — 每條 ingress 規則、每個 tag、每項關聯設定 — 都得一字不差地補成 HCL。任何一項對不上，下次 apply 就會試圖把現實改回程式碼寫的版本 — 對 security group 來說可能是把一條正在用的規則刪掉，對 RDS 來說可能是觸發一次重啟。

Terraform 1.5 之後提供了 import 區塊，可以在 HCL 裡宣告式地寫 import，配合 terraform plan -generate-config-out=generated.tf 自動生成對應的資源描述。這比手寫減少了大量逆向工程，但生成的 code 仍然需要人工確認每一個屬性是否正確 — 自動生成是起點，不是終點。

1import {
2  to = aws_security_group.web
3  id = "sg-0abc123def456"
4}

import 成本隨資源數量非線性增長。一個資源的逆向工程可控，幾十個各自手動微調過的資源累積起來，團隊會停止嘗試納管，環境分裂成 IaC 管理的部分和手動管理的部分。第一天就立鐵律，要納管的存量永遠是零。

鐵律靠權限落地，不靠自律

光靠約定「別在 Console 改」撐不久，救火當下手最快的永遠是 Console。真正讓鐵律站得住的，是把人的日常身分收斂成唯讀、把寫入權限留給跑 apply 的自動化身分，讓「在 Console 改不動」變成預設狀態。

這道權限地基屬於模組二：身分與憑證地基的範圍，本階先確立紀律方向：人類日常用的 IAM 身分只有 ReadOnlyAccess，寫入權限只存在於 CI pipeline 使用的 role，這個 role 靠 OIDC 取得短期憑證（不存長期 key）。具體的 IAM 設計和 OIDC 信任關係在模組二展開。

最小可行：能 apply 出一個完整環境的最小資源集合

最小可行 IaC 的目標是用最少的資源，跑出一條「改程式碼 → review → apply → 環境真的變了」的完整迴路。它承擔的責任是驗證地基本身能動，把所有服務都搬上來是後面的事。判準是這套程式碼能獨立 apply 出一個雖小但自洽、別人能重現的環境。

最小集合的組成

把一個微小資源（例如一個 S3 bucket 或一台最小的測試 EC2）刻意留在最小集合裡，是因為它是最便宜的端到端驗證。apply 跑完後它確實出現、terraform destroy 後它確實消失，就證明從程式碼到雲端的整條鏈路是通的。

1resource "aws_s3_bucket" "smoke_test" {
2  bucket = "acme-smoke-test-${var.env}"
3
4  tags = {
5    purpose = "validate-iac-pipeline"
6    env     = var.env
7    owner   = "platform"
8  }
9}

刻意不放進來的東西

正式的應用服務、資料庫、跨環境的複製、複雜的模組抽象，全部留到地基驗證通過之後。在 state 與 Console 唯讀都還沒站穩前就堆服務，等於把房子蓋在還沒灌漿的地基上。

常見的過早引入包括：在最小集合裡就加 RDS（state 操作出問題時資料庫可能被影響）、在還沒有環境分離前就建多層 module 嵌套（驗證地基的複雜度不應該來自抽象層）、在一個人開發時就配好 Atlantis 或 Terraform Cloud 的完整 PR 流程（固定成本太高、且需要模組七的完整護欄才能發揮價值）。

網路骨架怎麼長、身分怎麼切，分別由模組三：網路地基與模組二：身分與憑證地基接手深入；這一階只需要它們各自最薄的一層，湊出一個能 apply、能 destroy、能交接的閉環。

驗證閉環

最小集合就位後的驗證步驟：

1. terraform init — 確認 backend 設定正確、provider 能下載
2. terraform plan — 確認 plan 輸出符合預期、沒有意外的 destroy 或 replace
3. terraform apply — 確認資源在雲端確實出現
4. terraform plan（再跑一次）— 確認輸出是零差異，代表 state 與現實一致
5. terraform destroy — 確認資源能被乾淨拆除（smoke test 資源）

第四步「再跑一次 plan」是容易被跳過卻最關鍵的一步。如果第一次 apply 之後立刻 plan 就出現差異，代表 provider 的行為和 HCL 描述之間有落差（例如某些屬性是雲端自動設的、HCL 沒寫），這類落差要在最小集合階段就修掉，等到正式服務上線後再修，成本會高很多。

最小可行 IaC 跑通後，下一步是收斂身分與憑證——把 Console 唯讀鐵律從紀律升級成權限限制，見模組二：身分與憑證地基。

跨分類引用

• → IaC 工具選型與 state 地基：state 怎麼管、backend 怎麼選
• → 模組二：身分與憑證地基：Console 唯讀鐵律靠權限落地，人類唯讀、自動化身分持有寫入權
• → 模組三：網路地基：最小集合裡的 VPC 與 subnet 怎麼設計
• → 模組七：infra 走 PR 流程：state 變更與 apply 怎麼納入 review

State 裡通常含有資源的真實 ID、相依關係，以及部分敏感屬性（例如資料庫的初始密碼、private key 的輸出值）。這帶來兩條硬邊界：state 不能進 git（含敏感值，推進版控等於把密碼寫進每個 clone 的歷史）、state 不能只放本地（本地 state 的失敗模式是記憶綁在一台筆電上，多人並行 apply 會互相覆蓋）。

概念位置

State 是 IaC 的記憶機制。模組一：最小可行 IaC 的核心主題就是怎麼把 state 管好——remote backend、加密、鎖機制。State 管不好，後續所有 IaC 操作都建立在不可靠的記憶上。

可觀察訊號

State 出問題的訊號包括：terraform plan 顯示大量非預期的變更（state 與現實不一致）、兩個人同時 apply 後環境出現矛盾狀態、state list 的資源數與 Console 上看到的不一致。

設計責任

管理 state 時要決定：

• 存放位置：S3 + DynamoDB（自管）vs Terraform Cloud（託管），取捨在維運負擔 vs 控制權
• 加密：state 含敏感值，落地加密（S3 SSE）是底線
• 版本保留：bucket versioning 讓 state 損壞時能回捲到上一個正確版本
• 鎖機制：防止兩個人同時 apply 互相覆蓋
• 分割策略：一個大 state vs 多個小 state，取捨在引用便利性 vs 影響範圍控制

鄰卡

• IaC — state 是 IaC 工具的核心依賴
• Drift — state 與現實的落差

Pipeline 的兩個階段

整條 pipeline 分成兩個觸發時機，各自承擔不同責任：

兩個階段用不同的 IAM role：plan role 只有唯讀權限（能跑 terraform plan 但不能改任何資源），apply role 有寫入權限。這個分離確保 PR 階段的任何 code 都沒辦法偷偷改動雲端資源。

Plan 階段的完整 workflow

 1name: Terraform Plan
 2on:
 3  pull_request:
 4    paths:
 5      - 'infra/**'
 6
 7permissions:
 8  id-token: write
 9  contents: read
10  pull-requests: write
11
12jobs:
13  plan:
14    runs-on: ubuntu-latest
15    defaults:
16      run:
17        working-directory: infra/environments/prod
18
19    steps:
20      - uses: actions/checkout@v4
21
22      - uses: aws-actions/configure-aws-credentials@v4
23        with:
24          role-to-assume: arn:aws:iam::123456789012:role/infra-plan
25          aws-region: ap-northeast-1
26
27      - uses: hashicorp/setup-terraform@v3
28        with:
29          terraform_version: 1.9.0
30
31      - name: Format check
32        run: terraform fmt -check -recursive -diff
33
34      - name: Init
35        run: terraform init -input=false
36
37      - name: Validate
38        run: terraform validate
39
40      - name: TFLint
41        uses: terraform-linters/setup-tflint@v4
42        with:
43          tflint_version: latest
44      - run: tflint --recursive --format compact
45
46      - name: Plan
47        id: plan
48        run: |
49          terraform plan -no-color -input=false -out=tfplan \
50            -detailed-exitcode 2>&1 | tee plan-output.txt
51        continue-on-error: true
52
53      - name: Comment plan on PR
54        uses: actions/github-script@v7
55        with:
56          script: |
57            const fs = require('fs');
58            const plan = fs.readFileSync('infra/environments/prod/plan-output.txt', 'utf8');
59            const truncated = plan.length > 60000
60              ? plan.substring(0, 60000) + '\n\n... (truncated)'
61              : plan;
62            await github.rest.issues.createComment({
63              owner: context.repo.owner,
64              repo: context.repo.repo,
65              issue_number: context.issue.number,
66              body: `### Terraform Plan\n\`\`\`\n${truncated}\n\`\`\``
67            });
68
69      - name: Fail if plan errored
70        if: steps.plan.outcome == 'failure'
71        run: exit 1

各步驟的職責

Format check 驗證 HCL 是否符合標準排版。它不影響功能，但消除 diff 噪音——排版不一致時 PR diff 會混入純格式變更，reviewer 分不清哪些是邏輯改動。-diff flag 讓 CI 輸出具體哪幾行不符合，作者在本地跑 terraform fmt 就能修。

Init 初始化 provider 和 backend。-input=false 避免 CI 卡在等待互動式輸入。如果 backend 設定錯了（bucket 不存在、權限不足），這一步就會失敗，不會跑到後面浪費時間。

Validate 檢查 HCL 的語法和內部一致性——變數沒宣告、型別不匹配、必填參數缺漏。它不連線雲端，只讀 code，所以不需要 AWS credential 也能跑（但放在 init 之後是因為 validate 需要 provider schema）。

TFLint 做 provider 層的正確性檢查：instance type 在該 region 不存在、已棄用的參數、命名不符規範。它補的是 validate 抓不到的「語法對但值不對」的問題。

Plan 是整條 pipeline 的核心產出。-detailed-exitcode 讓 exit code 區分三種狀態：0 = 無差異、1 = 錯誤、2 = 有差異。-out=tfplan 把 plan 結果存成二進位檔，apply 階段可以直接用這份 plan 執行，避免 plan 和 apply 之間的時間差導致不一致。

Comment 把 plan 輸出貼回 PR，reviewer 看 code diff 的同時看到 plan 的實際變更。plan 輸出可能很長（幾百行），超過 GitHub comment 上限時截斷，但保留開頭（通常包含 add/change/destroy 的摘要行）。

Apply 階段

 1name: Terraform Apply
 2on:
 3  push:
 4    branches: [main]
 5    paths:
 6      - 'infra/**'
 7
 8permissions:
 9  id-token: write
10  contents: read
11
12jobs:
13  apply:
14    runs-on: ubuntu-latest
15    environment: production
16    defaults:
17      run:
18        working-directory: infra/environments/prod
19
20    steps:
21      - uses: actions/checkout@v4
22
23      - uses: aws-actions/configure-aws-credentials@v4
24        with:
25          role-to-assume: arn:aws:iam::123456789012:role/infra-apply
26          aws-region: ap-northeast-1
27
28      - uses: hashicorp/setup-terraform@v3
29        with:
30          terraform_version: 1.9.0
31
32      - name: Init
33        run: terraform init -input=false
34
35      - name: Plan (verify)
36        run: terraform plan -no-color -input=false -detailed-exitcode
37
38      - name: Apply
39        run: terraform apply -auto-approve -input=false

environment protection rule

environment: production 這一行啟用 GitHub 的環境保護功能。在 repo 的 Settings → Environments → production 設定：

• Required reviewers：指定至少一個人 approve 才能執行 apply job
• Wait timer：合併後等 N 分鐘才開始 apply（給人反應時間）
• Deployment branches：限定只有 main branch 能觸發

這層保護讓高風險的變更（plan 顯示 destroy 或 replace）在 apply 前多一道人工確認。日常低風險變更（加一個 tag、調一個參數）可以直接通過。取捨點是：每次 apply 都要人按確認會拖慢頻繁的小變更，可以用 deployment rule 的條件只攔 production 環境。

Apply 階段重跑 plan 的理由

apply 之前重跑一次 plan，是為了驗證合併後的現實跟 PR review 時看到的一致。PR 從開啟到合併可能隔了幾小時或幾天，期間有人可能手動改了雲端資源（drift）或別的 PR 先 apply 了。重跑 plan 確認差異跟預期一致，不一致就停下來而非盲目 apply。

如果使用了 plan 階段的 -out=tfplan 保存 plan 檔，apply 可以改為 terraform apply tfplan 直接執行已 review 過的 plan。代價是 plan 檔需要跨 job 傳遞（GitHub Actions 的 artifact），且 plan 檔有時效——state 在 plan 之後被修改，apply 會拒絕執行。

多環境的 pipeline 設計

管理 dev / staging / prod 三個環境時，pipeline 有兩種常見結構：

單 workflow 加 matrix：一份 YAML 用 strategy.matrix 跑三個環境，每個環境有自己的 working directory 和 IAM role。好處是維護一份 YAML；代價是三個環境的 plan 都在同一次 PR run 裡，reviewer 要看三份 plan 輸出。

每環境獨立 workflow：三份 YAML 各自觸發在對應環境目錄的變更上（paths: ['infra/environments/dev/**']）。好處是只有改到的環境才跑、PR comment 乾淨；代價是三份 YAML 有重複。

多數團隊起步時用單 workflow + matrix，環境數量超過三個或各環境的 apply 策略不同（dev 自動、prod 要 approval）時切到獨立 workflow。

安全邊界

CI pipeline 是 infra 變更的自動化執行者，它的安全性等同於 apply role 的權限。幾個邊界要守住：

OIDC claim 收斂：apply role 的 trust policy 只允許特定 repo 的 main branch 假扮（見 OIDC Trust Policy 設定）。如果 claim 只驗 repo 不驗 branch，任何人在 feature branch 推一個修改過的 workflow 就能觸發 apply。

Workflow 修改的 review：.github/workflows/ 底下的 YAML 變更應該跟 infra code 一樣走 PR review。修改 workflow 等於修改 pipeline 的行為——加一個 terraform destroy step 就能在合併時清掉整個環境。GitHub 的 CODEOWNERS 功能可以強制特定人 review workflow 變更。

Secret 與 environment variable：OIDC 取代了存在 repo secrets 裡的 access key，但 workflow 可能還用到其他 secret（Terraform Cloud token、Slack webhook URL）。這些 secret 要限定在特定 environment 才能存取，不開放給所有 branch。

本篇聚焦 GitHub Actions。如果團隊選擇 Atlantis（常駐服務、內建 state lock 與 apply 語意），見主文章的 Atlantis 段的選型討論。

跨分類引用

• → OIDC Trust Policy 設定：pipeline 的 credential 來源
• → checkov / tfsec 規則配置：pipeline 裡的靜態安全掃描怎麼配
• → infra 走 PR 流程與自動化護欄：pipeline 背後的審查原則
• → 模組四：環境分離與模組化：多環境的目錄結構決定 pipeline 的 working directory

Provider 離線管理

Provider Mirror

Terraform 的 providers mirror 指令在有網路的環境把指定 provider 的二進位檔下載到本地目錄，產出符合 filesystem mirror 結構的檔案：

 1# 在有網路的工作站執行
 2mkdir -p /path/to/mirror
 3terraform providers mirror -platform=linux_amd64 /path/to/mirror
 4
 5# mirror 目錄結構
 6# /path/to/mirror/
 7# └── registry.terraform.io/
 8#     └── hashicorp/
 9#         └── aws/
10#             └── 5.50.0/
11#                 └── terraform-provider-aws_5.50.0_linux_amd64.zip

把整個 mirror 目錄搬進隔離網路後，在 Terraform 設定裡指定 filesystem mirror：

 1# ~/.terraformrc 或 terraform.rc（Windows）
 2provider_installation {
 3  filesystem_mirror {
 4    path    = "/opt/terraform/providers"
 5    include = ["registry.terraform.io/*/*"]
 6  }
 7  direct {
 8    exclude = ["registry.terraform.io/*/*"]
 9  }
10}

direct 區塊的 exclude 確保 Terraform 不會嘗試連網下載——如果 mirror 裡沒有某個 provider，init 會直接報錯而非 hang 在網路連線。

Plugin Cache

替代 mirror 的另一個做法是 plugin cache directory。在有網路的環境跑過 init 後，.terraform/providers/ 裡會有已下載的 plugin。把這整個目錄搬進隔離網路，用 TF_PLUGIN_CACHE_DIR 環境變數指向它：

1export TF_PLUGIN_CACHE_DIR="/opt/terraform/plugin-cache"
2terraform init

mirror 跟 plugin cache 的差別：mirror 是正式的離線分發機制（有版本結構、支援多平台）、plugin cache 是快取機制（省重複下載、但目錄結構跟 mirror 不同）。長期運作用 mirror，臨時驗證用 cache。

Provider 版本鎖定

斷網環境的 provider 版本管理比連網更嚴格——升級一個 provider 代表要重新搬運整個 provider binary。在 versions.tf 裡鎖定精確版本（= 5.50.0 而非 ~> 5.50），避免 init 期待一個 mirror 裡沒有的版本：

1terraform {
2  required_providers {
3    aws = {
4      source  = "hashicorp/aws"
5      version = "= 5.50.0"
6    }
7  }
8}

Module 離線來源

連網環境的 module source 常指向 Terraform Registry 或 GitHub：source = "terraform-aws-modules/vpc/aws"。斷網環境要改成本地路徑或內部 git server。

本地路徑

最簡單——module 放在同一個 repo 或共用檔案系統的目錄裡：

1module "network" {
2  source = "../../modules/network"
3}

內部 Git Server

如果有架 Gitea 或 GitLab CE（見斷網通用原則），module 可以指向內部的 git repo：

1module "network" {
2  source = "git::http://gitea.internal/infra/modules.git//network?ref=v1.2.0"
3}

ref=v1.2.0 鎖定版本。內部 git server 的 module repo 用 git bundle 從外部搬運更新。

State Backend：沒有 S3 時的替代

連網環境的 state 通常放 S3 + DynamoDB lock。斷網環境如果沒有 AWS（地端機房或隔離網路），state backend 的替代選項：

最常見的組合是 PostgreSQL backend——多數環境已經有 PostgreSQL，不需要額外裝服務：

1terraform {
2  backend "pg" {
3    conn_str = "postgres://terraform:password@db.internal/terraform_state?sslmode=disable"
4  }
5}

PostgreSQL backend 的 lock 機制用 PostgreSQL 的 advisory lock，多人同時 apply 時第二個人會被擋住。

state 的備份紀律不變——定期 terraform state pull > backup.json，backup 存在版本控制或另一台機器上。

Plan / Apply 流程

斷網不影響 plan 和 apply 的執行——它們操作的是本地 provider 和目標基礎設施（地端伺服器、內部雲、VMware vSphere 等）。影響的是 provider 初始化和 module 取得，這些在前面幾節已處理。

沒有雲端 API 的情境

如果基礎設施不是雲端（地端 VMware、OpenStack、裸機），Terraform 有對應的 provider：

• VMware vSphere：hashicorp/vsphere
• OpenStack：terraform-provider-openstack/openstack
• Proxmox：telmate/proxmox（社群維護）
• 裸機管理：用 null_resource + local-exec 呼叫 Ansible 或 shell script

provider 的離線管理方式相同——mirror 或 plugin cache。

Plan 輸出的離線 Review

沒有 GitHub PR 的環境，plan 輸出用檔案分享 review：

1# 產出 plan 並存成可讀格式
2terraform plan -out=plan.tfplan
3terraform show plan.tfplan > plan-review-$(date +%Y%m%d).txt
4
5# 把 review 檔放到內部共用位置供 reviewer 閱讀
6cp plan-review-*.txt /shared/reviews/

reviewer 讀完後以 email、內部 chat、或直接在 review 檔旁邊放一個 approved-by-alice-20260626.txt 標記核准。不優雅但可追溯。

內網 CI/CD

斷網環境的 CI/CD 用自架的 CI server：

CI server 本身也需要離線安裝——GitLab CE 有 offline 安裝指南（.deb / .rpm 包）、Gitea 是單一二進位。CI runner 執行 Terraform 時使用內部的 provider mirror 和 module source。

CI workflow 的離線版本跟連網版本結構相同（init → fmt → validate → plan → review → apply），差別在 init 用 -plugin-dir 而非連網下載。

時程參考：內網 CI server 的初次建置（含 git server + CI runner + Terraform 離線環境）約需 3-5 天。之後的維護主要是 provider 版本更新的搬運（每次 1-2 小時）。

跨分類引用

• → 斷網環境的通用原則：provider 和 module 的搬運走 content ferry 模式
• → 模組一：最小可行 IaC：連網環境的 IaC 選型和 state 管理
• → 模組七：infra 走 PR 流程：連網環境的 CI pipeline 設定

本篇的操作流程從盤點差距開始，經過 state 健康檢查、drift 收斂、文件重建，到最後排出收斂的優先序。每一步都在不影響線上服務的前提下進行。

state 與現實的差距盤點

盤點的第一步是跑 terraform plan 但不 apply — plan 的輸出就是程式碼描述的狀態與雲端現實之間的完整差距清單。

1terraform plan -no-color > plan-baseline-$(date +%Y%m%d).txt

把這份輸出存進 repo，它是接手時的基線快照。之後每一次收斂動作的效果都用「跟這份基線比少了幾項 diff」來衡量。

三類 diff 的判讀

plan 輸出的每一項 diff 歸屬三類，各自的風險等級與處理方式不同：

「要刪」是最危險的一類。常見成因是：前人在 Console 手動刪了某個資源但沒同步從程式碼移除（state 裡還有紀錄），或者前人在程式碼裡移除了某段 HCL 但沒跑 apply（雲端資源還在、state 記得它）。兩種情況都需要先確認該資源在雲端是否存在、是否仍被服務依賴，再決定是從 state 移除（terraform state rm）還是補回 HCL。

另一個需要留意的標記是 -/+（forces replacement）— 它代表 Terraform 判定這個屬性的變更無法原地更新，必須先刪除再重建。對 stateful 資源（RDS、EBS volume）來說這等於資料遺失，在接手階段看到這個標記要先暫停、查清楚是哪個屬性觸發了 replacement。

哪些資源在 state 裡、哪些不在

terraform state list 列出所有被 IaC 管理的資源。配合 terraform show -json 可以取得更結構化的 managed resource 摘要：

1# state 裡有什麼（清單）
2terraform state list > managed-resources.txt
3
4# state 裡有什麼（結構化摘要：type + name + provider）
5terraform show -json | jq '.values.root_module.resources[] | {type, name, provider}' > managed-summary.json

但 state 只是一份已知的清單 — 雲端上可能還有大量不在這份清單裡的資源。用 CLI 列舉雲端資源跟 state 做比對：

1
2# 雲端上有什麼（以 EC2 + RDS + SG 為例）
3aws ec2 describe-instances --query 'Reservations[].Instances[].InstanceId' --output text > cloud-ec2.txt
4aws rds describe-db-instances --query 'DBInstances[].DBInstanceIdentifier' --output text > cloud-rds.txt
5aws ec2 describe-security-groups --query 'SecurityGroups[].GroupId' --output text > cloud-sg.txt

用這兩份清單做比對，分成三類：

未管理的資源需要逐一判斷：這個資源是前人刻意排除在 IaC 外的（例如一個還在實驗的測試機），還是應該納管但漏了？判斷依據是它的角色 — security group、IAM role、VPC 這類地基資源應該優先 import；一台跑完就該關的測試 EC2 可以暫時留在手動。

手動比對 state list 與 CLI 輸出的效率有限，driftctl（現由 Snyk 維護、開源）可以自動掃描雲端資源與 Terraform state 的差異，一次列出所有 unmanaged resource。它跟 terraform plan 的差別在於 plan 只看已管理資源的 drift，driftctl 同時涵蓋根本不在 state 裡的資源。兩者互補：先用 driftctl 產出完整的 unmanaged 清單，再用 plan 處理已管理資源的 drift。

state 的健康檢查

state 本身的存放方式決定了後續所有操作的安全性。接手後第一件事是確認 state 的健康狀態。

存放位置

1# 查看 backend 設定
2grep -A 10 'backend' *.tf

如果 backend 是 local（或沒有 backend 設定），state 檔只存在某台機器的磁碟上。這代表如果有第二個人從自己的機器跑 apply，兩人會用不同版本的 state 互相覆蓋。把 state 搬到 remote backend（S3 + DynamoDB lock）是接手後的第一優先事項，做法見IaC 工具選型與 state 地基。

加密與版本控制

如果 state 已經在 S3，確認三件事：

1# bucket 有沒有 versioning
2aws s3api get-bucket-versioning --bucket <state-bucket>
3
4# bucket 有沒有加密
5aws s3api get-bucket-encryption --bucket <state-bucket>
6
7# 有沒有 lock table
8aws dynamodb describe-table --table-name <lock-table> 2>/dev/null

versioning 沒開的話，一次壞掉的 apply 寫壞 state 就回不去了。加密沒開的話，state 裡的敏感值（資料庫密碼、private key 輸出）以明文存在 S3。

state 裡的敏感值

state 檔經常包含不該暴露的值。確認 state 有沒有在 Git 歷史裡：

1git log --all --diff-filter=A -- '*.tfstate' '*.tfstate.backup'

如果命中，代表 state 曾經被推進 repo。此時 Git 歷史裡的敏感值已經無法徹底清除（git filter-branch 或 git filter-repo 可以嘗試，但無法保證所有 clone 都更新）。務實的處理是：列出 state 裡的敏感值，全部輪替。

1# 用 jq 從 state JSON 撈敏感值候選
2terraform show -json | jq -r '
3  [.. | objects | to_entries[] |
4   select(.key | test("password|secret|key|token"; "i"))] |
5  unique_by(.key) | .[] | "\(.key): \(.value)"
6' 2>/dev/null

這個 jq 查詢會遞迴掃描 state JSON 裡所有欄位名稱含 password / secret / key / token 的值。命中的每一筆都要確認是否為真實密鑰、是否需要輪替。

drift 收斂策略

盤點完差距、確認 state 健康之後，逐項收斂 drift。對 plan 輸出的每一項 diff 做一個二選一的決定：採納手動變更（改 HCL 去符合現實），或回退到程式碼版本（讓下一次 apply 把現實改回來）。

採納 vs 回退的判斷

多數 drift 應該採納。前人在 Console 手動改設定通常有一個操作理由（即使沒有記錄下來）— 加了一條 security group 規則可能是為了讓某個新服務連進來，改了 RDS 的 max_connections 可能是為了解決連線數不足。在沒有充分理解這些改動的背景之前，回退它們等於撤銷一個可能正在支撐服務運作的設定。

回退適用的情境是：drift 明顯是誤操作（例如 0.0.0.0/0 打開了不該打開的埠）、或 drift 的屬性是有標準答案的（例如 S3 的 block_public_access 被關掉了）。

操作步驟

1# 1. 刷新 state 到最新雲端狀態（不改資源、只更新 state 的快照）
2terraform apply -refresh-only
3
4# 2. 再跑一次 plan — 刷新後 diff 會減少（純 state 過期的 diff 消失）
5terraform plan -no-color > plan-after-refresh.txt
6
7# 3. 對剩餘的 diff 逐項處理
8#    採納：改 HCL 讓程式碼跟現實一致 → plan 確認該項 diff 消失
9#    回退：不改 HCL、讓 apply 把現實改回程式碼版本 → 先確認影響

-refresh-only 是安全的操作 — 它只更新 state 裡的屬性快照，不會改動任何雲端資源。但它會把手動變更「記進」state，讓後續 plan 的 diff 只剩程式碼與 state 的差異（而非程式碼與雲端的差異）。刷新後 plan 的 diff 更精確、更少、更容易逐項處理。

import 未管理的資源

對未管理的資源，用 import 區塊一次處理一個，每次 import 後都跑 plan 確認零新增 diff：

1import {
2  to = aws_security_group.legacy_app
3  id = "sg-0abc123def456"
4}

1# 生成對應的 HCL
2terraform plan -generate-config-out=generated_legacy_app.tf
3
4# 確認生成的 HCL 跟現實一致
5terraform plan
6# 預期：只有 import 動作、沒有 change/destroy

生成的 HCL 需要人工確認 — 有些屬性是雲端自動設的預設值，Terraform 會把它們全部列出來，造成 HCL 冗長。移除純預設值的屬性、只保留有意義的設定，讓 HCL 反映設計意圖而非雲端預設。

對於大量未管理資源需要一次性反推 HCL 的情境，Former2 可以從現有 AWS 資源批量生成 Terraform code。它掃描帳號裡的資源、產出對應的 HCL，品質不完美（命名會用資源 ID 而非有意義的名稱、屬性可能包含大量預設值），但作為起點比從零手寫每個資源快得多。產出後仍需逐檔清理命名與移除預設值。

文件重建

接手的環境通常沒有文件、或者文件已經過時到比沒有更糟（記載的是兩個版本前的架構）。文件重建的目標是讓下一個接手者不需要重複同樣的盤點過程，而非追求一份完美的架構文件。

來源

能重建的資訊來源有限，但每個都有價值：

terraform-docs 用一條指令就能從現有 HCL 產出每個 module 的 inputs、outputs 和 resources 清單，省去手動整理 module 介面的時間。Inframap 從 state 或 HCL 產出依賴關係圖，比 terraform graph | dot 好用的地方在於它自動過濾掉 provider 和 data source 的噪音，大型 state 也能產出可讀的圖。

最小可行文件

寫一份 INFRA-STATE.md 放在 repo 根目錄，包含：

• 管理範圍：哪些資源由 IaC 管理、哪些是手動的、為什麼手動的沒有 import（例：還在實驗、不穩定、計畫廢棄）
• 已知 drift：目前 plan 輸出裡還有哪些未處理的 diff、每個 diff 的處理方向（採納/回退/待調查）
• state 存放位置：backend 設定、bucket 名稱、lock table 名稱
• credential 狀態：有幾把 access key、哪些還在用、上次輪替時間
• 接手日期與盤點結果：盤點時的資源數量、覆蓋率（managed / total）

這份文件不需要精美，需要的是準確且持續更新。每次收斂一項 drift 或 import 一個資源，就更新對應的段落。前任團隊的知識已經不在了，這份文件取代它成為環境的記憶。

收斂到完整 IaC 的優先序

把整個收斂過程排成四個階段，每個階段都能獨立交付價值：

每個階段的驗證方式相同：terraform plan 的輸出是否比上一階段乾淨。階段一完成後，plan 的可信度才成立；階段二和三是把 plan 的 diff 清到零；階段四是擴大 plan 的管轄範圍。

每一步操作之前都先備份 state：

1# 手動備份 state（不論 bucket 有沒有 versioning 都先拉一份）
2terraform state pull > state-backup-$(date +%Y%m%d).json

state 操作失敗時的回退路徑是 terraform state push state-backup.json 從備份還原 — 資源本身不受影響，只是工具對現實的記憶回到上一個正確的版本。state push 是覆寫操作，只在確認備份版本正確時使用。

需要搬移資源在 state 裡的位址時（例如重構 module 結構），優先用 moved {} 區塊而非 terraform state mv。moved 是宣告式的、寫在 HCL 裡、可以被 PR review、plan 時會顯示搬移動作。state mv 是指令式的、直接改 state、沒有 review 機制、操作紀錄只在 CLI 歷史裡。

1moved {
2  from = aws_security_group.old_name
3  to   = module.network.aws_security_group.app
4}

跨分類引用

• → IaC 工具選型與 state 地基：state 怎麼從 local 搬到 remote backend
• → Console 唯讀鐵律：drift 的來源與偵測
• → 環境分離與模組化：收斂完成後怎麼把單環境拆成 per-env module
• → infra 走 PR 流程：收斂完成後的變更怎麼走 review
• → State 修復與清理：state 損壞的操作修復步驟
• → Drift 分類處理：逐項判斷 adopt vs revert
• → 批次 Import 工作流：unmanaged resource 的 import 操作
• → 過渡期操作：兩套真相並存時的安全操作規則

本文是跨 vendor migration playbook、cross-link Terraform（source）跟 OpenTofu（target）。Type B drop-in migration 標準形態、跑 migration-playbook-methodology 6 維 audit 後對映 6 維皆 Low → Type B drop-in；本文驗證 skill 的 Type B anatomy 在 IaC 領域成立。

HCL / state file / provider 三層 diff sample

跟前批 Redis → DragonflyDB 同為 Type B drop-in、本文用 code-led entry — 直接給 3 種 diff sample 證明「真 drop-in」：

1# 1. HCL syntax: 完全相同 (Terraform 1.5.x baseline)
2resource "aws_s3_bucket" "logs" {
3  bucket = "myapp-logs"
4  tags = {
5    Env = "production"
6  }
7}
8# 兩家 binary 都接受、執行結果一致

 1# 2. State file: 完全相同 schema
 2$ cat terraform.tfstate | jq '.version, .terraform_version'
 34
 4"1.5.7"
 5
 6# 切 OpenTofu 後 re-init、state 保留
 7$ tofu init
 8$ cat terraform.tfstate | jq '.version, .terraform_version'
 94
10"1.6.0"  # tool version 標記變、其他不變

 1# 3. Provider: registry 路徑唯一明顯差異
 2terraform {
 3  required_providers {
 4    aws = {
 5      source  = "hashicorp/aws"     # 兩家共用 source 字串
 6      version = "~> 5.0"
 7    }
 8  }
 9}
10# Terraform 從 registry.terraform.io 拉
11# OpenTofu 預設從 registry.opentofu.org 拉 (fallback 到 terraform registry)

3 層 diff sample 顯示：HCL / state schema / 主流 provider 配置完全相容；唯一明顯差異在 registry routing。

跑 6 維 diff dimension audit：

6 維皆 Low → Type B drop-in。

為什麼遷：license / governance / community 三條 driver

跟前批 Redis → DragonflyDB 不同（cost / performance driver）、Terraform → OpenTofu 主要 driver 在 governance：

反向 driver（OpenTofu → Terraform）：

• Terraform Cloud / Enterprise 特定 feature 依賴（policy as code 用 Sentinel、跟 OpenTofu 自家 OPA 不對等）
• 既有 module 在 Terraform registry 維護、未同步 OpenTofu registry

相容性 audit

Pre-cutover 必跑：

Audit output：列「100% drop-in」block + 「需處理」block；後者通常 < 5% 範圍。

Step-by-step cutover

 1# 1. Install OpenTofu (跨 OS)
 2brew install opentofu                # macOS
 3snap install --classic opentofu      # Ubuntu
 4# https://opentofu.org/docs/intro/install/
 5
 6# 2. 在 workspace 跑 tofu init
 7$ cd terraform-workspace/
 8$ tofu init -upgrade
 9# 升級 provider / module、re-init backend、保留 state
10
11# 3. Plan diff（應該 = 0 changes）
12$ tofu plan
13# Plan: 0 to add, 0 to change, 0 to destroy.
14# 如果有 diff、表示 provider version 不對齊、檢查 lock file
15
16# 4. Apply（保險起見、staging 先跑）
17$ tofu apply
18
19# 5. CI / CD pipeline 切 binary
20# Before
21terraform init
22terraform plan -out=tfplan
23terraform apply tfplan
24
25# After
26tofu init
27tofu plan -out=tfplan
28tofu apply tfplan
29# 或保留 terraform 字面、用 alias / symlink

整個 cutover 通常 < 1 天（單 workspace）；多 workspace organization 視規模 1-4 週逐個切。

Production 故障演練

Case 1：Provider version drift、staging plan 出現意外 diff

徵兆：tofu plan 顯示 100+ resource 有 in-place update、實際業務沒改任何 config。

根因：.terraform.lock.hcl 鎖的 provider version 在 Terraform / OpenTofu registry 不一致（同 version 但 binary checksum 微差）；OpenTofu 在 init 時拉新 checksum、視為「provider 變了」。

修法：

1. 預先對齊：tofu init -upgrade 重建 lock file、把 OpenTofu 端 checksum 寫進去
2. CI lockfile commit：lock file 進版控、不同 binary 端跑前先 lockfile 對齊
3. 若 plan 仍有差異：通常是 provider 內部 schema 對 nil 值處理不同、用 lifecycle.ignore_changes 暫忽略、後續逐項 fix

Case 2：State file lock 機制微差

徵兆：兩個 CI pipeline 同時跑 tofu apply、其中一個應該 lock 拒絕、實際兩個都跑、production 端 race condition。

根因：Terraform DynamoDB lock 跟 OpenTofu lock 用相同 schema 但 lock_id 規則略不同；舊 lock entry 殘留時 OpenTofu 端解析失敗、視為「無 lock」繼續跑。

修法：

1. DynamoDB lock table 手動清舊 entry：cutover 期間先 aws dynamodb delete-item 清舊 lock
2. 單向流量切換：cutover 期間 freeze 所有 CI、只一個 pipeline 跑、避免 race
3. 架構：用 fully replicated lock backend（如 Consul）avoid backend-specific lock 怪異

Case 3：Terraform Cloud workspace 不能直接搬

徵兆：team 已用 Terraform Cloud workspace 跑 100+ pipeline、想切 OpenTofu、發現 terraform login / workspace API / VCS integration 全 HashiCorp-specific。

根因：OpenTofu 沒對等 Terraform Cloud 服務；自家 backend 用 S3 + Atlantis / Spacelift / env0 等第三方 platform 對接、不是 1:1 替代。

修法：

1. 保留 Terraform Cloud 跑 production（OpenTofu 不替代）、用 OpenTofu 跑 dev / sandbox
2. 遷出 Terraform Cloud：state 遷 S3 + 用 Atlantis 跑 PR-based plan/apply（mature open source）
3. 評估 Spacelift / env0 商業替代、支援 OpenTofu + 對等 workspace feature

Case 4：CI pipeline 寫死 terraform binary name

徵兆：cutover 後 CI 跑 terraform plan 報「command not found」；team 100+ pipeline / GitHub Action / GitLab CI / shell script 都寫死 terraform。

根因：rollout 計畫沒 grep 全 organization 找 binary name 引用。

修法：

1. Alias 策略：CI image 內 ln -s /usr/local/bin/tofu /usr/local/bin/terraform、保留兼容 1-3 個月
2. 逐步改 tofu：跟著 IaC team 修 pipeline file、target 100% 改完才 remove alias
3. 架構：避免在 pipeline / script 寫死 binary、用 env variable IAC_BINARY=${IAC_BINARY:-tofu}

Case 5：Registry routing、自家 module 拉不到

徵兆：cutover 後 tofu init 對自家 private module 報「not found」；同 module 在 Terraform 端跑得好好的。

根因：private module 註冊在 Terraform Cloud private registry、OpenTofu 預設不知道這個 endpoint；需要顯式設 registry source URL。

修法：

1. 顯式 source URL：source = "app.terraform.io/myorg/myapp/aws" 改 git source 或自架 module registry
2. 架構：用 git-based module source（source = "git::ssh://git@github.com/myorg/myapp.git"）、避開 registry lock-in
3. 長期：自家 module 同時 publish 到 OpenTofu registry / Terraform Cloud / git、跨 tool 兼容

Capacity / cost

判讀：純 IaC 用戶切 OpenTofu 風險低 + 省 license 風險；重度依賴 Terraform Cloud feature 的 organization 保留或評估 commercial alternatives（Spacelift / env0）。

整合 / 下一步

跟 Atlantis / Spacelift / env0 整合

OpenTofu 沒對等 Terraform Cloud、需要 third-party orchestrator：

• Atlantis：自架、開源、輕量、適合中小型 team
• Spacelift：SaaS、policy as code、支援 OpenTofu first-class
• env0：SaaS、cost estimation、workflow 完整

跟 Terragrunt 整合

Terragrunt（OpenTofu / Terraform 共用 wrapper）已支援 OpenTofu 1.6+；多環境配置抽象保留、底層 binary 切換無感。

反向 migration（OpenTofu → Terraform）

罕見、通常是 organization 走商業合約綁 HashiCorp Enterprise 才會做；流程鏡像對稱、注意 OpenTofu 1.6+ 自家 feature（state encryption / provider for_each）在 Terraform 端可能缺。

下一步議題

• State encryption（OpenTofu 1.7+）：sensitive state 加密、Terraform 商業版才有對等 feature
• 跨 IaC tool（Pulumi / CDK）：Pulumi / AWS CDK 是不同 paradigm（imperative）、不在本 migration scope
• Provider ecosystem 長期分裂：兩家 registry 自我演化、需要 quarterly review provider compat

相關連結

• Source vendor：Terraform
• 平行 migration playbook（Type B）：Redis → DragonflyDB
• Methodology：Migration playbook methodology / #127 Process content 結構由最大差異維度決定

診斷 state 的健康狀態

terraform plan 的輸出是診斷 state 健康度的主要工具。在不做任何 code 變更的前提下跑 plan，輸出的每一行差異都代表 state 與現實的落差：

1terraform plan -detailed-exitcode -no-color > plan-diagnosis.txt 2>&1
2# exit code: 0=無差異, 1=錯誤, 2=有差異

Plan 的差異分三類，每一類的處理方式不同：

Plan 跑到一半報錯（exit code 1）而非產出差異，通常代表更嚴重的問題：provider 版本不相容、state 格式損壞、或 state 引用的資源 ID 在雲端已經不存在。錯誤訊息裡的 resource address 指向問題所在。

Orphaned entry 的辨認

State 裡有一筆資源記錄，但雲端已經沒有對應的資源（手動刪除、帳號切換、或 region 不對），plan 會顯示 - destroy 或直接報 Error: reading ... NotFound。這種 orphaned entry 需要從 state 移除，否則每次 plan 都會嘗試操作一個不存在的目標。

1# 列出 state 裡所有資源，逐一確認是否還存在
2terraform state list | while read addr; do
3  echo "Checking: $addr"
4  terraform state show "$addr" > /dev/null 2>&1 || echo "  POSSIBLY ORPHANED: $addr"
5done

這個腳本不連雲端驗證（只檢查 state 內部一致性），真正的驗證要靠 plan 輸出。如果 plan 對某個資源報 NotFound，那就是 orphaned。

State 操作前的備份

所有 state 操作（rm、mv、push、import）都是直接改寫 state 檔的破壞性操作。操作前的備份是唯一的回退路徑。

1# 從遠端 backend 拉一份完整的 state 到本地
2terraform state pull > state-backup-$(date +%Y%m%d-%H%M).json
3
4# 確認備份可用：檢查 JSON 格式和 resource 數量
5jq '.resources | length' state-backup-*.json

如果 state 存在 S3 且 bucket 有開 versioning（應該有，見模組一），S3 的版本歷史是第二道保險。但 state pull 的本地備份更可控——S3 versioning 的回復要操作 bucket、權限要對、而且版本 ID 需要另外查。

移除 orphaned entry：state rm

terraform state rm 把一筆資源從 state 裡移除，但不觸碰雲端的實際資源。用途是清理 state 裡對應不到雲端的記錄，讓 plan 不再嘗試操作不存在的目標。

1# 移除單一 orphaned resource
2terraform state rm 'aws_instance.old_bastion'
3
4# 移除整個 module 的記錄（module 被拆掉但資源還在雲端、要重新 import）
5terraform state rm 'module.legacy_network'

移除後立刻跑 plan 驗證：原本針對這個資源的 destroy / error 應該消失。如果移除後 plan 反而出現 + create（想重建這個資源），代表 code 裡還有對應的 resource block——要麼也刪 code，要麼這個資源需要 import 而不是 rm。

判斷「該 rm 還是該 import」的依據：資源在雲端還存在嗎？存在就 import（讓 state 重新追蹤它），不存在就 rm（清掉過時的記錄）。

搬移資源：state mv 與 moved block

重構 Terraform code（把資源搬進 module、改 resource name、改 module 結構）時，state 裡的 resource address 會跟著變。如果不處理，plan 會判定「舊 address 要 destroy、新 address 要 create」——對 stateless 資源只是多等一次重建，對 RDS 這類 stateful 資源是資料遺失。

Terraform 1.1+ 的 moved block 是宣告式的搬遷，寫在 HCL 裡、可 review、可回滾：

1moved {
2  from = aws_security_group.web
3  to   = module.network.aws_security_group.web
4}

跑 plan 時 Terraform 會把 state 裡的舊 address 自動對應到新 address，plan 顯示 (moved) 而非 destroy + create。驗證 plan 為零變更後 apply，moved block 生效後可以從 code 裡刪掉。

terraform state mv 是指令式的搬遷，直接操作 state 檔。它比 moved block 靈活（可以跨 state 搬）、但不可 review、不進版本控制、操作錯了只能靠備份回退。

優先用 moved block，state mv 留給 moved 做不到的場景。

手動編輯 state：pull → 改 → push

極少數情況需要直接編輯 state JSON——例如修正一個 resource 的 ID（某次 import 用了錯的 ID）、或手動修改一個 attribute 讓 plan 不再觸發不必要的變更。

1# 拉到本地
2terraform state pull > state-edit.json
3
4# 編輯（用 jq 或文字編輯器，改目標 resource 的 attributes）
5# 極度小心：改錯任何欄位都可能讓 plan 產生破壞性差異
6
7# 推回遠端
8terraform state push state-edit.json

state push 有 lineage 和 serial 檢查——如果本地的 state 跟遠端的 lineage 不同（來自不同的 init），push 會被拒絕。加 -force 可以繞過，但這意味著覆蓋遠端、丟棄遠端從你 pull 之後的所有變更。

手動編輯 state 的操作規則：備份 → 改一個欄位 → push → plan 驗證 → 確認只有預期的變化。批次改多個欄位時，每改一個就走一輪 push + plan，不要累積修改。

從錯誤的 state push 回復

如果 state push 推了一個錯誤的 state，回復路徑取決於 backend 有沒有版本歷史。

S3 backend 有 versioning

 1# 列出 state 檔的所有版本
 2aws s3api list-object-versions \
 3  --bucket acme-tf-state \
 4  --prefix prod/network/terraform.tfstate \
 5  --query 'Versions[].{VersionId:VersionId,LastModified:LastModified,Size:Size}' \
 6  --output table
 7
 8# 下載上一個正確的版本
 9aws s3api get-object \
10  --bucket acme-tf-state \
11  --key prod/network/terraform.tfstate \
12  --version-id "correct-version-id" \
13  state-recovered.json
14
15# 用 terraform state push 推回
16terraform state push state-recovered.json

沒有 versioning

如果 bucket 沒開 versioning、又沒有本地備份，state 的上一個版本就沒了。這時候的選項：

1. 從 plan 的輸出反推哪些 resource 的 state 記錄是錯的，逐一用 state rm + import 修正
2. 作為最後手段，刪掉整份 state、從零 import 所有資源——這等於重做一次完整的 IaC 導入

這正是模組一要求 state bucket 開 versioning 的理由——沒有版本歷史的 state backend，一次 push 錯誤就沒有回退路徑。

State backend 搬遷

接手的環境可能用本地 state（.terraform/terraform.tfstate）或者 state 放在不符合安全要求的位置（沒加密的 S3、沒有鎖表、甚至存在某個人的桌機上）。搬遷到正規的遠端 backend 是接手後的優先工作。

本地 → S3 + DynamoDB

 1# 在 backend.tf 加上遠端 backend 設定
 2terraform {
 3  backend "s3" {
 4    bucket         = "acme-tf-state"
 5    key            = "prod/network/terraform.tfstate"
 6    region         = "ap-northeast-1"
 7    encrypt        = true
 8    dynamodb_table = "acme-tf-lock"
 9  }
10}

1# 重新初始化，Terraform 會偵測到 backend 變更並提示搬遷
2terraform init -migrate-state
3
4# 確認搬遷成功
5terraform plan  # 應該顯示零變更

-migrate-state 會把本地 state 的內容寫入新的遠端 backend。搬遷後本地的 .terraform/terraform.tfstate 變成一個指向遠端 backend 的指標，不再存放實際 state 內容。

舊 S3 → 新 S3

跟本地搬遷流程相同——改 backend.tf 的 bucket/key/region，跑 terraform init -migrate-state。Terraform 會從舊 backend 讀 state、寫入新 backend。

搬遷後驗證：plan 為零變更、新 bucket 裡有 state 檔、舊 bucket 的 state 檔可以保留一段時間作為備份。搬遷過程中 DynamoDB 的 lock 會確保沒有人同時 apply。

搬遷期間的風險：如果有人在你改 backend.tf 之後、跑 init 之前，用舊 backend 跑了 apply，新 backend 的 state 會缺少那次變更。搬遷時通知團隊暫停所有 Terraform 操作，搬遷完成後再恢復。

時程參考：單一 orphaned entry 的 rm 操作約 15-30 分鐘（含備份和驗證）。Backend migration 約 1-2 小時。5-10 個問題項的完整 state 整理約半天到一天。

跨分類引用

• → 有半套 IaC 但文件缺失的環境接管：本篇的上層操作流程
• → Drift 分類處理：state 修復完成後，下一步是處理 managed resource 的 drift
• → 模組一：最小可行 IaC：state backend 的設計與 versioning 要求
• → 模組四：環境分離與模組化：moved block 在環境拆分 retrofit 裡的角色

讀 plan 輸出：三種變更類型

terraform plan 的輸出用符號標示每個資源的預期變更。三種類型的風險等級不同，處理方式也不同：

 1# in-place update（~）：修改屬性，資源本身不動
 2~ resource "aws_security_group_rule" "api_ingress" {
 3    ~ cidr_blocks = ["10.0.0.0/16"] -> ["10.0.1.0/24"]
 4  }
 5
 6# forces replacement（-/+）：刪除後重建，新資源取得新 ID
 7-/+ resource "aws_db_instance" "primary" {
 8    ~ identifier = "app-prod" -> "app-prod-v2" # forces replacement
 9  }
10
11# destroy（-）：刪除資源
12- resource "aws_security_group" "legacy_api" {
13  }

-（destroy）是最危險的類型。它代表某個資源存在於雲端但不在 Terraform code 裡——可能是手動建的、可能是從 state 被 state rm 移除過、也可能是前任維護者刪了 code 但沒跑 apply。不論原因，直接 apply 會把這個資源從雲端刪除。

-/+（forces replacement）的危險在於它看起來像修改但實際是先刪後建。對 stateless 資源（security group rule、IAM policy）影響有限，對 stateful 資源（RDS、EBS volume）意味著資料遺失。

故意的 drift vs 意外的 drift

不是所有 drift 都是問題。接手的環境裡，手動改動可能有兩種來源：

故意的改動是前任維護者為了解決特定問題而做的。常見形態：臨時開了一條 security group 規則讓外部監控系統連進來、調高了 RDS 的 max_connections 參數來應對流量成長、手動把 instance type 從 t3.small 升到 t3.medium 因為記憶體不夠。這類改動通常是正確的操作決策，只是沒有同步回 code。

意外的漂移是無意中造成的。常見形態：在 Console 測試時改了某個設定但忘了改回來、另一個 Terraform workspace 的 apply 動到了共用的資源、AWS 自動更新了某些屬性（如 default security group 的描述）。

區分兩者的方法是查 CloudTrail——看這個改動是誰做的、什麼時候、有沒有對應的 ticket 或 changelog 記錄。如果 CloudTrail 顯示改動發生在一次事故期間、由當時的值班工程師執行，大概率是故意的。如果改動來自一個不認識的 IAM user、或時間點跟任何已知事件對不上，可能是意外。

1aws cloudtrail lookup-events \
2  --lookup-attributes AttributeKey=ResourceName,AttributeValue=sg-0abc123 \
3  --start-time 2026-01-01 \
4  --query 'Events[].[EventTime,Username,EventName]' \
5  --output table

每條 drift 的處理決策

每條 plan 差異都需要一個明確的決定：保留手動改動（更新 HCL）、回退到 code 的版本（apply）、還是暫時擱置（不動）。

保留（adopt into HCL）

適用條件：手動改動是正確的操作決策，雲端的現況是期望狀態。處理方式是把 HCL 改成跟雲端一致，讓下次 plan 對這項顯示零差異。

多數 drift 應該走這條路。前任維護者調大了 instance type、加了一條 security group 規則、改了 RDS parameter——這些改動通常有操作上的理由。把 code 對齊現實，比把現實改回 code 安全。

回退（apply to revert）

適用條件：手動改動是錯誤的、或已經不再需要（如臨時開的除錯 port）。確認回退不會影響運行中的服務後，讓 Terraform apply 把設定改回 code 描述的版本。

回退前要確認的事：這條規則還有沒有服務在用？這個參數改回去會不會讓連線斷開？如果不確定，先 adopt 再說——adopt 的成本是改一行 HCL，回退錯誤的成本可能是服務中斷。

擱置（defer）

適用條件：目前無法判斷該保留還是回退（缺乏 context），或改動涉及 stateful 資源的 forces replacement 需要更多準備。擱置的做法是在 code 裡加 lifecycle { ignore_changes = [...] } 暫時跳過這項差異，並留下註解說明為什麼擱置、預計什麼時候處理。

1resource "aws_db_instance" "primary" {
2  # drift: identifier 被手動改過，forces replacement
3  # 擱置原因：直接 apply 會觸發 RDS 重建、資料遺失
4  # 預計處理：確認新 identifier 後更新 HCL + 用 moved block
5  lifecycle {
6    ignore_changes = [identifier]
7  }
8}

擱置不是永久解法。ignore_changes 會讓這個屬性脫離 IaC 管理，累積越多就越接近「回到手動」。定期回顧擱置清單，逐項決定保留或回退。

Stateful 資源的高風險 drift

stateful 資源（RDS、EBS volume、DynamoDB table）的 drift 需要特別處理，因為 forces replacement 意味著資料遺失。以下屬性的改動在 plan 裡會顯示 -/+（forces replacement），直接 apply 會先刪除再重建：

發現 stateful 資源的 forces replacement 時，處理步驟：

1. 在 lifecycle 加 ignore_changes 暫時跳過
2. 備份資源（RDS snapshot、EBS snapshot）
3. 確認正確的目標狀態後，用 moved block 或 terraform state mv 處理 identity 變更
4. 用 terraform plan 驗證變更類型從 -/+ 變成 ~（in-place）或零差異
5. 移除 ignore_changes

refresh-only：安全的 state 同步

terraform apply -refresh-only 只更新 state 來反映雲端現況，不改變任何雲端資源。它適用於「雲端被手動改了、想讓 state 跟上現實但還沒準備好改 HCL」的情境。

1terraform apply -refresh-only

refresh-only 之後，state 跟雲端一致了，但 state 跟 HCL 之間的差異仍然存在——下次跑 plan 仍會看到 drift。它解的是「state 過時」的問題，不是「code 跟現實不一致」的問題。兩者要分開處理：先 refresh-only 讓 state 乾淨，再逐項決定 HCL 要不要對齊。

使用 refresh-only 的前提是確認 state backend 有 versioning——如果 refresh-only 把 state 改壞了（例如併發操作導致 state 衝突），需要能回捲到上一個版本。

批次 drift 收斂工作流

接手環境的 drift 通常不是一兩條，可能有幾十條。逐條處理可以但效率低，按類型批次處理比較實際：

第一批：安全類。security group 規則、IAM policy 的 drift 優先處理，因為它們直接影響存取邊界。全開的規則該關就關（回退），故意開的規則 adopt 進 code。

第二批：stateless 資源的 in-place drift。tag 不一致、description 不一致、非關鍵屬性的變更。這類 drift 風險低，可以批次 adopt（把 HCL 改成跟雲端一致）然後一次 apply 驗證。

第三批：stateful 資源。RDS parameter、backup retention、instance class 的變更。逐個處理，每個都要確認是 in-place update 而非 forces replacement。

第四批：擱置項。forces replacement、無法判斷的改動。加 ignore_changes 暫緩，排進 backlog 定期回顧。

每一批處理完後跑一次 plan，確認該批的 drift 消失、其他批次的 drift 沒被影響。不要一次 apply 所有批次——分批的目的是控制每次 apply 的影響範圍。

整個 drift 收斂流程的時程取決於 drift 數量和 stateful 資源的比例。20 條以內的 drift、多數是 stateless 的 in-place 變更，2-3 天可以收完。50 條以上、含多個 stateful 資源的 forces replacement，需要 1-2 週分階段處理。

跨分類引用

• → 有半套 IaC 但文件缺失的環境接管：本文的上層總覽
• → State 修復與清理：drift 處理前先確認 state 本身是健康的
• → Unmanaged resource 批次 import：drift 收斂完成後，開始 import unmanaged resource
• → Console 唯讀鐵律：drift 的根本防線
• → 模組四：環境分離與模組化：drift 收斂後的環境拆分路徑

優先序：先 import 什麼

不是所有 unmanaged resource 都值得立刻 import。判斷依據是「這個資源不在 IaC 裡的風險有多高」和「import 的操作複雜度有多低」的交集。

優先級 1-2 的資源是地基層，import 後能讓後續的 IaC 引用鏈從 hardcode ID 換成資源屬性引用，這是 import 的結構性收益。優先級 5 的資源如果生命週期短（隨部署替換），用 IaC 重新定義再 apply 比逆向 import 划算。

import block 語法（Terraform 1.5+）

Terraform 1.5 引入了宣告式 import block，取代舊版的 terraform import CLI 指令。宣告式的優勢是 import 本身進版本控制、可 review、可回滾。

1import {
2  to = aws_security_group.api
3  id = "sg-0abc123def456"
4}
5
6import {
7  to = aws_db_instance.primary
8  id = "app-prod-primary"
9}

to 是 Terraform 裡的資源地址（resource type + name），id 是雲端的資源識別碼。每種資源的 id 格式不同：security group 用 sg-xxx、RDS 用 DB identifier、S3 用 bucket name、IAM role 用 role name。格式查 Terraform provider 文件的 Import 段。

多個 import block 可以寫在同一個檔案裡（如 imports.tf），一次 plan/apply 處理整批。apply 完成後這些 import block 可以刪除——它們的作用是觸發 import 動作，import 完成後 state 已經記住了對應關係。

generate-config-out 工作流

import block 只把資源綁進 state，不會自動產生對應的 HCL 定義。Terraform 1.5+ 提供 -generate-config-out flag 自動反推 HCL：

1terraform plan -generate-config-out=generated_resources.tf

這個指令會：

1. 讀取所有 import block
2. 查詢每個資源在雲端的真實屬性
3. 把屬性寫成 HCL 資源定義，輸出到指定檔案
4. 在 plan 輸出中標示每個資源為 import（不是 create/change/destroy）

生成的 HCL 是起點，需要人工 review 後才能正式使用。

生成 HCL 的 review 要點

自動生成的 code 有幾個常見問題需要修正：

缺少 lifecycle 設定

生成的 code 不會包含 lifecycle block。有狀態資源（RDS、S3）需要手動加上保護：

1resource "aws_db_instance" "primary" {
2  # ... generated attributes ...
3
4  lifecycle {
5    prevent_destroy = true
6  }
7}

沒加 prevent_destroy 的 stateful 資源，未來某次 plan 如果判定需要 replace，apply 會先刪除再重建——資料跟著消失。

預設值與隱含屬性

雲端資源有些屬性是由平台自動設定的（如 RDS 的 ca_cert_identifier、EC2 的 credit_specification），生成的 code 會把這些都寫出來。下次平台更新預設值時，plan 會顯示 drift。review 時判斷：這個屬性是刻意設定的（保留），還是平台預設的（刪掉、讓 Terraform 接受平台預設）。

判斷方法：如果一個屬性的值跟 provider 文件裡的 default 一致，通常可以刪掉。如果不確定，先保留——保留多餘的屬性只是 code 冗長，刪錯屬性可能在下次 apply 時改變資源行為。

provider 特有的 quirk

不同 provider 有各自的 import 陷阱：

security group 的 inline vs 獨立規則問題最常見：如果生成的 code 用 inline ingress block，但環境裡同時有獨立的 aws_security_group_rule 指向同一個 SG，兩者會互相打架。統一選一種寫法——多數情況用獨立 rule 更彈性。

批次策略

一次 import 太多資源會讓 plan 輸出太長、review 不了。按服務類型分批，每批 5-15 個資源：

1批次 1: security groups (所有 SG + 對應的 rules)
2批次 2: VPC + subnets + route tables + NAT
3批次 3: IAM roles + policies
4批次 4: RDS instances + subnet groups + parameter groups
5批次 5: S3 buckets + bucket policies
6批次 6: ALB + listeners + target groups

每批的操作流程固定：

1. 寫 import block → imports-batch-N.tf
2. terraform plan -generate-config-out=generated-batch-N.tf → 檢查 plan 輸出全部是 import、沒有 create/destroy
3. review generated code → 修正 lifecycle、刪除平台預設屬性、處理 provider quirk
4. terraform plan → 確認零非預期變更（import 完後的 plan 應該只有 import 標記、沒有 change）
5. terraform apply → 執行 import
6. terraform plan → 再跑一次確認零 drift（import 後的 state 與雲端一致）
7. 刪除 imports-batch-N.tf（import block 已完成使命）、把 generated-batch-N.tf rename 成正式檔名

批次之間要按依賴順序：先 import 被依賴的資源（VPC → subnet → SG），再 import 依賴它們的資源（RDS → EC2）。這樣後面批次的 generated code 可以引用前面批次已經在 state 裡的資源，而非 hardcode ID。

驗證：plan 必須是零非預期變更

import 完成的判準是 terraform plan 輸出只有兩種結果之一：

• 完全零變更（“No changes”）— 最理想，代表 HCL 和雲端現實完全匹配
• 只有已知且可接受的差異 — 某些屬性在 HCL 裡省略了（用平台預設）、或 provider 的 plan 行為跟雲端有已知的格式差異（如 JSON 排序不同）

出現 change（要修改屬性）代表 HCL 跟雲端有落差，apply 會把雲端改成 HCL 的版本。在確認這個修改是安全的之前，不要 apply。

出現 replace（先刪後建）代表某個屬性的修改會觸發資源重建。對 stateful 資源這等於資料遺失，必須在 apply 之前解決——通常是 HCL 裡漏寫了某個 force-new 屬性。

常見 import 失敗與處理

import 操作本身不改變雲端資源——它只修改 state 檔。失敗時的回退方式是 terraform state rm <resource_address>，把 state 裡的對應記錄移除，資源本身不受影響。

時程參考

主要時間花在 generated HCL 的 review——生成是秒級的，確認每個屬性正確與否是人工判斷。第一批（security group）通常最慢，因為要建立 review 的肌肉記憶；後面的批次會加速。

跨分類引用

• → 有半套 IaC 但文件缺失的環境接管：import 前的盤點與 state 健康檢查
• → 兩套真相並存的過渡期操作：import 期間就是 dual-truth 狀態，操作規則見此篇
• → 模組一：IaC 工具選型與 state 地基：state backend 的設定與保護
• → 模組五：Stateful 資源保護：import stateful 資源後的 lifecycle 設定

為什麼半套比全手動更危險

兩個方向的風險同時存在，而且互相放大。

apply 可能摧毀未納管的資源

Terraform apply 只知道 state 裡有什麼。一個存在於雲端但不在 state 裡的資源，對 Terraform 來說「不存在」。如果某個 managed resource 引用了一個 unmanaged resource 的 ID（例如一個 security group 引用了一個手動建的 security group 作為 source），apply 不會主動碰那個 unmanaged resource——但如果有人重構了 HCL 並把那個引用移除或改掉，apply 會改動 managed 的那一端，可能讓依賴它的 unmanaged 資源失去連線。

更直接的風險是 terraform destroy 或 terraform apply 配合 count = 0 這類邏輯刪除：如果有人誤判某個資源已經不用了、但它其實只是不在 state 裡（被前人 state rm 過），destroy 不會碰它——但如果有人重新 import 它再 destroy，資源就真的被刪了。

手動改動讓 managed 資源 drift

有人在 Console 手動改了一個已經由 Terraform 管理的資源（例如加了一條 security group 規則），state 不知道這個改動。下一次任何人跑 apply，Terraform 會把手動加的規則判定為「不該存在」並刪除。手動改動的人以為規則已經加好了，直到某次不相關的 apply 把它默默清掉。

這兩個風險的交叉效應是：團隊對「能不能跑 apply」和「能不能手動改」都缺乏信心，結果是兩邊都不敢動，變更停滯，技術債累積速度比全手動還快。

過渡期操作規則

過渡期的操作紀律核心是一句話：每個資源在任何時刻都只有一個合法的變更路徑。managed 資源走 IaC，unmanaged 資源走 Console + 變更日誌。混用就是 drift 的來源。

規則一：apply 前必讀 plan

過渡期的每一次 terraform apply 之前，都要完整讀 terraform plan 的輸出，逐行確認每一項變更是預期內的。特別警惕以下訊號：

• will be destroyed：確認這個資源是否有其他依賴（即使它在 state 裡）
• will be updated in-place 且變更的屬性不是這次修改的：代表有人手動改了這個屬性，apply 會覆蓋回去
• must be replaced：資源會被先刪後建，stateful 資源（RDS、EBS）在這裡要暫停確認

過渡期禁止 terraform apply -auto-approve。即使 CI pipeline 也要把 apply 設為手動觸發（GitHub Actions 的 environment protection rule），確保有人看過 plan。

規則二：不手動改 managed 資源

一個資源一旦進了 Terraform state，所有對它的變更都走 HCL → plan → apply。在 Console 改它會製造 drift，而 drift 在過渡期特別危險——因為下一次 apply 可能已經隔了好幾天，中間的手動改動已經忘了。

如果遇到緊急情況必須手動改 managed 資源（例如安全事件需要立即封鎖某個 port），操作流程是：

1. 在 Console 做緊急變更
2. 立刻在變更日誌記錄：時間、資源、改了什麼、為什麼
3. 在 HCL 裡同步這個變更，提 PR
4. PR 裡的 plan 應該顯示零變更（因為 HCL 已經對齊了手動改動）
5. 合併 PR，state 透過下一次 apply 或 refresh 更新

規則三：記錄哪些資源歸誰管

維護一份「管理歸屬清單」——哪些資源在 Terraform state 裡、哪些還在手動管理。格式可以是 repo 裡的一個 markdown 表格：

 1## 資源管理歸屬
 2
 3| 資源類型       | 資源名稱/ID         | 管理方式   | 備註             |
 4| -------------- | -------------------- | ---------- | ---------------- |
 5| VPC            | vpc-0abc123          | Terraform  |                  |
 6| Subnet (×4)   | subnet-0def...       | Terraform  |                  |
 7| RDS            | app-prod-primary     | Terraform  | stateful、謹慎操作 |
 8| SG web         | sg-0web456           | Terraform  |                  |
 9| SG legacy-api  | sg-0legacy789        | 手動       | 待 import        |
10| EC2 worker     | i-0worker123         | 手動       | 待 import        |
11| Lambda cron    | cleanup-job          | 手動       | 待評估是否納管   |

這份清單的維護者是跑 apply 的人——每次 import 一個新資源後更新清單。清單同時是 team communication 的基礎：team member 要改某個資源前，先查清單確認管理方式。

團隊溝通

過渡期最重要的溝通是讓所有會碰 Console 的人知道哪些資源「不能手動改」。溝通的形式是直接的操作指令：

在 team channel 發一則釘選訊息：

 1[Infra 過渡期操作規則]
 2
 3以下資源已由 Terraform 管理，變更請走 PR：
 4- VPC 和所有 subnet
 5- Security group: sg-0web456, sg-0app789
 6- RDS: app-prod-primary
 7- ALB: app-prod-alb
 8
 9以下資源仍為手動管理，變更請在 Console 操作後寫 changelog：
10- EC2: i-0worker123
11- Lambda: cleanup-job
12- SG: sg-0legacy789
13
14不確定的資源：先問再動。

隨著 import 進展更新這則訊息。如果團隊用的是 Slack，可以把這則訊息設成 channel bookmark。

縮短過渡期

過渡期越長、兩套真相並存越久、操作事故的機率越高。縮短的方式是用 import sprint 集中處理。

Import sprint 的排程

一個 import sprint 是 1-2 天的集中工作，目標是把一批相關的 unmanaged 資源納入 Terraform。按風險從低到高排序：

每批的操作流程：

1. 用 import block + terraform plan -generate-config-out 產生 HCL
2. 審查生成的 HCL，修正屬性差異
3. plan 確認零變更
4. 合併 PR
5. 更新管理歸屬清單

縮短期間不要追求完美

import sprint 的目標是「納管」，不是「重構」。一個手動建的資源 import 進來後，它的 HCL 可能很醜（自動生成的 code 有大量冗餘屬性），但只要 plan 顯示零變更，它就已經是 managed 的了。重構 HCL 是 import 完成之後的事。

同樣，import sprint 期間不要同時做 module 化或環境分離。先把所有資源納管到同一份 state，之後再拆——拆的前提是所有資源都在 state 裡。

過渡期結束的判準

過渡期結束的定義是兩個條件同時滿足：

1. terraform plan 在無 code 變更時顯示零差異：代表 state 與雲端現實一致，沒有 drift
2. 管理歸屬清單上的「手動」欄位清空：所有生產資源都進了 Terraform state

第一個條件用定期排程驗證（每天跑一次 plan，非零就告警）。第二個條件用資源盤點比對——雲端的 resource inventory 減去 terraform state list 的輸出，差集為空就完成。

過渡期結束後，操作規則簡化為：所有變更走 IaC + PR，Console 只用來觀察和排查。這就是模組一的 Console 唯讀鐵律。

跨分類引用

• → 有半套 IaC 但文件缺失的環境接管：本篇的前置操作（盤點、state 健康檢查、drift 收斂）
• → State 修復與清理：過渡期出問題時可能需要 state surgery
• → 模組一：Console 唯讀鐵律：過渡期結束後的操作紀律
• → 模組四：環境分離 retrofit：所有資源納管後的下一步
• → 模組七：infra 走 PR 流程：過渡期結束後的完整 PR 護欄