以下步驟是寫第一行 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 導入路徑

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 與現實的落差

本篇的操作流程從盤點差距開始，經過 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 操作
• → 過渡期操作：兩套真相並存時的安全操作規則

本章從 source of truth 的責任分層開始、引入 CQRS / event sourcing / materialized view 等模式、最後處理四種 query 邊界的設計。讀完後讀者能回答：哪些資料是正式狀態、什麼時候該分讀寫 model、materialized view 怎麼用、replica lag 怎麼影響 query。

State Ownership

State ownership 的責任是判斷哪些資料是 source of truth、哪些資料屬於 cache、search index、event log 或報表副本。正式狀態會影響交易結果、權限判斷、對帳與客服修復、因此需要清楚的 owner、schema、驗證方式與變更流程。

訂單狀態、付款狀態、會員方案、權限授權與發票紀錄通常屬於正式狀態。商品搜尋索引、快取值、統計摘要與推薦結果通常是派生狀態；派生狀態可以錯過短暫更新、但正式狀態需要能被追溯、修復與稽核。

Canonical State vs Derived State

Canonical state 的特徵：

• 業務決策依據（付款、權限）
• 不能從其他地方重建（一旦丟、無法找回）
• 需要 audit log、point-in-time recovery、backup
• 通常在 OLTP DB（PostgreSQL / Aurora / Spanner）

Derived state 的特徵：

• 從 canonical 推算出來
• 可以「rebuild」（lazy 或 eager）
• 失效可接受（用戶可能看到舊的）
• 通常在 cache / search / analytics store
• 對應案例：9.C6 Tinder ElastiCache 配對快取、9.C25 Tubi ML feature store feature

設計原則：

• 同一資料 不能 同時是兩個地方的 canonical → 衝突時不知道信誰
• 寫入永遠先寫 canonical、再 propagate 到 derived
• derived 出錯只能 rebuild、不能拿來「修正 canonical」

CQRS 在資料庫情境的應用

CQRS 的概念定義、設計判準與代價見知識卡。本段聚焦在資料庫層面：state ownership 的決策如何影響你要不要分離讀寫模型。

State ownership 跟 CQRS 的交叉點是：當 canonical state 的 schema 為寫入正確性最佳化（normalize、強一致、transaction boundary 清楚），但讀取面的多種消費者各自需要不同的反正規化形狀（列表頁要扁平 summary、報表要聚合、搜尋要全文索引），canonical schema 無法同時服務這些讀取需求。這時候分離 write model 跟 read model 是解決形狀不對稱的方式。

資料庫情境的 CQRS 有不同的實作強度：

最輕量 — 同 DB 不同 query path：寫入走 canonical table，讀取走 materialized view 或反正規化 view。同一個 PostgreSQL 裡用 materialized view 就能實現最基本的讀寫分離，不需要兩個 DB、不需要事件同步。適合讀寫形狀不同但流量規模還不需要獨立擴展的階段。

中度 — 同 DB 加 read replica：寫入走 primary，列表跟報表走 read replica。Replica lag 決定哪些 query 能走 replica（見下方 Replica Lag 段）。適合讀取流量開始壓迫寫入的階段。

完整 — 獨立 read store：寫入走 OLTP DB，讀取走獨立的 analytics store（BigQuery、Athena）或搜尋引擎（Elasticsearch）。透過 CDC 或事件同步維護 read store。適合讀取形狀、流量、SLA 都跟寫入完全不同的階段。

對應案例：9.C17 BookMyShow — 交易層（OLTP）跟資料層（BigQuery / Athena）分開。9.C22 Wayfair — on-prem OLTP + GCP BigQuery analytics。

Event Sourcing 與 State Ownership

Event sourcing 的概念定義、設計判準與代價見知識卡。本段聚焦在資料庫層面：event sourcing 怎麼改變 state ownership 跟 query boundary。

Event sourcing 把 state ownership 的正式紀錄從 mutable row 改成 append-only event log。這個改變影響本章的每一個面向：

對 canonical / derived 分類的影響：採用 event sourcing 後，event log 是 canonical state，current state 變成 derived state。這跟傳統 CRUD 架構相反 — 傳統架構中 current state（mutable row）是 canonical，歷史紀錄（audit log）是 derived。

對 query boundary 的影響：event log 不適合直接服務交易查詢跟列表查詢（每次 replay 整條事件流太慢）。Event sourcing 幾乎必然搭配 projection 維護 read model — projection 持續消費事件流、更新反正規化的查詢 view。交易查詢讀 projection 的輸出而非直接讀 event log。

對修復流程的影響：傳統架構的資料修復是「直接改 row」；event sourcing 的修復是「發一筆補償事件（compensating event）」。修復本身也是事件、會被記錄在 event log 裡、提供完整的修復 audit trail。

Event sourcing 的設計門檻在於 projection 的維護跟 event schema evolution。Projection 數量增長後，每次 event schema 改版都需要同步更新所有 projection；projection 的 replay 跟 reconciliation 是長期運維的主要成本。這些代價決定了 event sourcing 適合「需要完整變更歷史」的業務場景（金融帳務、訂單流程、法規合規），而非所有資料存取場景。

Materialized View 在資料庫的應用

Materialized view 的概念定義見知識卡。本段聚焦在 OLTP 資料庫裡 materialized view 作為最輕量 read model 的具體實作。

Materialized view 是「同 DB 內最簡單的讀寫分離」。不需要事件同步、不需要獨立 read store、不需要 projection consumer — 資料庫自己定期執行查詢、存放結果。

跟 regular view 的差別：regular view 是 SQL 別名，每次 query 重跑底層查詢；materialized view 有實體儲存，query 時直接讀預計算結果。差別在 query-time cost — 複雜 JOIN / aggregation 重複跑時，materialized view 把計算推到 refresh 時、query 時接近零成本。

Refresh 策略：

• 全量 refresh：PostgreSQL 的 REFRESH MATERIALIZED VIEW，refresh 期間 view 預設 unavailable。
• Concurrent refresh：PostgreSQL 的 CONCURRENTLY 模式，refresh 期間 view 仍可讀但資料可能 stale。
• 增量 refresh：PostgreSQL 的 pg_ivm、Oracle 的 fast refresh — 只更新變更的部分，成本低但配置複雜。
• Trigger-based：特定 event 觸發 refresh，適合低頻變更的資料。

在 state ownership 的定位：materialized view 是 derived state，修復方式是 refresh（重建）而非直接修改。大量 materialized view 會拖累寫入吞吐 — 每次 base table 變更都可能觸發 refresh 計算。設計時要平衡 refresh 頻率跟 query freshness 需求。

跟觀測領域的對照：觀測領域的 recording rule 在概念上等同於 TSDB 層的 materialized view — 定期執行 query expression、把結果寫成新 series。兩者面對同樣的設計問題：refresh 頻率、freshness lag、維護成本與儲存增長。觀測領域的 CQRS 特化應用見 4.23 觀測查詢設計。

Query Boundary 四種

Query boundary 的責任是讓不同查詢路徑承擔不同服務問題。交易查詢、列表查詢、報表查詢與對帳查詢都可能讀同一張表、但它們的正確性、延遲與資料新鮮度要求不同。

這四種查詢混在一起時、資料庫會同時承擔低延遲交易與高成本分析、最後讓任何一種資料庫選型都變得模糊。

交易路徑的邊界

交易路徑的責任是維持使用者動作的即時正確性。它需要短查詢、明確 index、可控 transaction boundary 與清楚 timeout。

交易路徑的設計要把報表聚合或長時間掃描移到其他查詢路徑。若下單 API 同時查歷史報表、計算大範圍統計或同步重建派生狀態、交易延遲會被非交易責任拖慢。

對應 9.C4 DraftKings — 200 個獨立 Aurora cluster 把不同業務 transaction 分開、避免互相影響。

列表與報表的邊界

列表查詢的責任是支援產品體驗中的瀏覽與定位。列表查詢需要穩定排序、分頁策略、篩選條件與查詢成本界線；它應建立自己的讀取模型或索引策略、避免直接借用交易查詢的資料模型造成 slow query、排序漂移與 pagination 重複。

報表查詢的責任是支援分析與決策。報表通常可以接受資料延遲、因此更適合使用 read replica、materialized view、ETL 或 analytics store。把報表直接壓在線上 primary 上、會讓交易服務承擔不必要的容量風險。

對應 9.C22 Wayfair hybrid burst、9.C17 BookMyShow — 交易層跟資料層分開部署。

對帳查詢的邊界

對帳查詢的責任是驗證正式狀態是否與外部事實一致。付款、發票、庫存與訂閱方案都需要對帳查詢、但對帳查詢要保留時間窗、資料來源、差異定義與人工修復入口。

對帳查詢承擔比報表更直接的修復責任。報表回答「現在看起來如何」、對帳回答「哪一筆正式狀態需要修復」。因此對帳查詢結果要能進入 Observability Evidence Package 與 Incident Decision Log。

詳見 1.9 Reconciliation 與 Data Repair。

Replica Lag 對 Query Boundary 的影響

當應用使用 read replica 擴 read traffic 時、replica lag 會直接影響 query boundary 設計。

典型 lag：

• PostgreSQL streaming：< 100ms（同 AZ）
• Aurora：10-30ms（同 region）
• 跨 region replica：秒級到分鐘級

不同 query 對 lag 的容忍：

• 交易查詢：不可容忍 lag、必須走 primary
• read-after-write（剛寫完查自己）：必須 primary、或 session sticky
• 列表查詢：通常容忍 lag < 1 秒
• 報表查詢：lag 分鐘級可接受
• 對帳查詢：通常用 batch、lag 不關鍵

Stale read 容忍策略：

• 「能容忍秒級 stale」的 read → replica（用戶 profile、報表）
• 「不能 stale」的 read → primary（剛寫入後的查詢、餘額確認）
• read-after-write：用 session token 標記「剛寫過」、N 秒內讀走 primary

對應 1.1 高併發資料存取 的「Read Replica Scaling」段。

選型前判準

資料庫選型前要先回答四個問題：

1. 哪些資料是正式狀態、哪些是派生狀態
2. 哪些查詢屬於交易路徑、哪些可以延遲或離線化
3. 哪些查詢結果會觸發修復、退款、補償或人工決策
4. 哪些資料需要 audit、masking、retention 或刪除責任

這些問題決定後續該比較 relational database、document database、search index、analytics store 還是 cache。工具差異要放在責任邊界之後討論。

實體服務討論承接點

實體資料庫文章要承接本篇的 state ownership 與 query boundary。PostgreSQL、MySQL、MSSQL 或其他 relational database 的比較、應先問它們如何支援正式狀態、交易查詢、列表查詢、報表查詢與對帳查詢、再進入索引、隔離層級、replica 或工具語法。

若主問題是正式狀態與交易一致性、後續文章要優先比較 transaction、isolation、index 與 migration 能力。若主問題是報表與搜尋、後續文章要評估 read replica、materialized view、search index 或 analytics store。若主問題是對帳與修復、後續文章要比較 validation query、audit log、backup/restore 與資料修復流程。

案例對照

跨模組路由

1. 與 1.2 的交接：欄位與索引語意回到 schema design
2. 與 1.3 的交接：transaction boundary 設計影響哪些 query 走 primary、哪些可走 replica
3. 與 1.7 的交接：正式狀態變更要進入 production rollout — Schema Migration Rollout Evidence
4. 與 1.9 的交接：對帳查詢的下游修復 — Reconciliation and Data Repair
5. 與 2 的交接：cache layer 是 derived state 最常見的形式 — 02 快取模組
6. 與 4.20 的交接：query evidence 跟 reconciliation evidence — Observability Evidence Package

下一步路由

要進一步處理 schema 與資料模型、接著讀 1.2 schema design 與資料建模。要處理 schema 演進與正式狀態變更、接著讀 1.6 Database Migration Playbook 跟 1.7 Schema Migration Rollout 證據。要處理對帳跟資料修復、接著讀 1.9 Reconciliation。要設計 KV / Document 的 state ownership、接著讀 1.10 KV / Document 容量規劃。

診斷 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 裡的角色

概念位置

State Lock 位在 IaC state backend、plan / apply workflow 與平台資源之間，常由 Terraform backend、Pulumi state 或平台鎖定機制提供。

可觀察訊號

• 多個 pipeline 同時 apply 同一個 workspace。
• state file 出現併發覆寫或 partial apply 後不一致。
• apply 長時間卡住需要判斷 lock 是否仍有效。

接近真實服務的例子

兩個 PR 同時修改 production network。第一個 workflow 取得 state lock 後進入 apply，第二個 workflow 等待或失敗，避免兩次變更同時寫入 state。

設計責任

State Lock 要定義 lock backend、timeout、人工解鎖條件、環境隔離與失敗處理，讓 IaC apply 保持序列化。