infra 變更走 code 流程

infra 變更的標準路徑是 PR → plan → review diff → 合併 → apply。這個順序的核心責任是把「執行前先看清楚要改什麼」變成強制步驟，而不是 apply 之後才從事故裡發現改錯了。每個環節各自承擔一段審查責任，少掉任一段，infra 就退回到不可審查的狀態。

plan 是整條鏈最關鍵的一環

terraform plan 把當前 state、雲端實際資源、與目標設定三方比對，產出一份「會新增 / 修改 / 刪除哪些資源」的 diff。這份 diff 是 review 的對象：reviewer 直接看 plan 算出來的實際變更，而非讀 HCL 自行想像結果。

plan 輸出裡最關鍵的判讀訊號是操作類型。+ 是新增，~ 是就地更新，- 是銷毀，-/+ 是先銷毀再重建。前兩者多數情境是安全的，後兩者需要逐行細看。改一個看似無害的欄位可能觸發整個資源重建（-/+），例如某些雲資源的 name 或 identifier 是 immutable 屬性，改它的唯一方式就是銷毀再建。對有狀態的服務（RDS、帶資料的 EBS volume），-/+ 代表資料遺失或停機。Review 階段抓到這個 -/+，比 apply 到一半才發現便宜太多。

 1# plan 輸出中要特別警惕的標記
 2# forces replacement  — 某個 immutable 屬性被修改，將觸發銷毀重建
 3# must be replaced    — 跟上面同義，Terraform 新版的表達方式
 4# will be destroyed   — 資源將被刪除
 5
 6  # aws_db_instance.primary must be replaced
 7  -/+ resource "aws_db_instance" "primary" {
 8      ~ identifier = "app-prod" -> "app-production"  # forces replacement
 9        ...
10    }

把 plan 結果貼回 PR

把 plan 結果貼回 PR 是讓 review 真正生效的做法。流程上，PR 觸發 CI 跑 plan，plan 輸出回貼成 PR comment，reviewer 連同程式碼 diff 一起看；approve 後才允許合併，合併才觸發 apply。

這裡有個取捨：plan 與 apply 之間若隔了很久，雲端實際狀態可能已經漂移（有人手動改了、或別的 PR 先 apply 了），導致 apply 時的 plan 跟 review 時看到的不一致。應對方式分保守與務實兩種。保守做法是 apply 前重跑一次 plan 並比對結果 — 一致才繼續，不一致就中斷。務實做法是在合併觸發 apply 時自動跑 plan 並只在無 destroy / replace 時自動執行，有 destroy / replace 就停下來要人確認。多數團隊從務實做法開始，到遇過一次 plan-apply 不一致的事故後才升級到保守做法。

apply 失敗的回退邊界

infra apply 不像程式碼部署可以直接 rollback 到上一版 image — 中途失敗時部分資源已經建立、state 可能處於半完成狀態。例如 apply 建了一個新 subnet 但在建 route table 時 timeout，此時 subnet 存在於雲端和 state 裡，route table 只在雲端不在 state 裡（或反過來），下一次 plan 的計算基礎就不精準。

應對的紀律是：apply 失敗後，先跑一次 terraform plan 確認 state 與現實的差距，再決定是修正 code 重新 apply 還是手動清理殘留資源後 terraform state rm。在清理之前不要再改 code、不要連發第二次 apply — 第二次 apply 在不確定的 state 上跑，可能把問題擴大。

PR 流程的價值在這裡不只是事前審查，也是事後可追溯：每次變更都對應一個 commit 與一個 PR，要回溯時知道是哪次改的、為什麼改、誰 review 的。

fmt 與 validate：最便宜的第一道檢查

fmt 與 validate 是進到任何安全掃描之前的基礎檢查，責任是擋掉格式不一致與語法 / 型別錯誤這類不需要動腦判斷的問題。它們跑得快（通常不到五秒）、沒有誤判空間，適合放在 CI 最前面當作快速 fail 的關卡。

terraform fmt -check 驗證程式碼是否符合標準排版。它本身不影響基礎設施行為，價值在於消除 diff 噪音：當每個人的編輯器縮排習慣不同，PR diff 會混入大量純排版變動，把真正的邏輯變更淹沒，reviewer 更容易看漏。統一格式後，diff 裡剩下的就是語意變更。在本地開發階段配合 editor plugin 或 pre-commit hook 在存檔時自動 fmt，讓 CI 的 fmt check 幾乎不會再 fail — 它存在的意義是攔住那些沒裝 plugin 的人。

validate 則檢查設定在語法與內部一致性上是否成立 — reference 到不存在的變數、型別不匹配、必填參數缺漏、module 呼叫的 source 解析不了，這些在 validate 階段就會報錯，不必等到 plan 連線雲端才發現。validate 需要先跑 terraform init，但可以用 -backend=false 跳過連線 state backend，這樣在 CI 裡不需要雲端憑證就能跑完。

 1# .github/workflows/terraform.yml — plan 前的基礎檢查
 2jobs:
 3  validate:
 4    runs-on: ubuntu-latest
 5    steps:
 6      - uses: actions/checkout@v4
 7      - uses: hashicorp/setup-terraform@v3
 8      - run: terraform fmt -check -recursive
 9      - run: terraform init -backend=false
10      - run: terraform validate

判讀上，fmt 與 validate 失敗代表的是「這份 code 還沒準備好被認真 review」，屬於作者自己該先修掉的問題，不該佔用 reviewer 注意力。把它們設成 CI 必過的 gate，作者在本地就會先跑、先修，PR 送出時已經是乾淨的。

tflint / checkov / tfsec：抓壞寫法與安全漏洞

fmt 與 validate 確認 code「語法正確」，但語法正確的設定仍然可能是危險的設定。tflint、checkov、tfsec 這類靜態掃描工具承擔的是「語意正確」這層：在不實際建立資源的前提下，從 HCL 裡比對已知的壞寫法與安全反模式，把問題擋在 plan 之前。它們補的是 reviewer 肉眼容易漏掉的盲區 — 人會看漏一個 0.0.0.0/0，規則不會。

三者的側重

checkov 與 tfsec 的覆蓋範圍有重疊（都會掃 S3 公開與 SG 全開），差別在規則來源與報告格式。checkov 的規則對標 CIS benchmark 和多雲合規框架（AWS、Azure、GCP、Kubernetes），tfsec 更專注在 Terraform HCL 結構。兩者跑在一起時，重複的命中可以用其中一個的 skip 標記豁免。

兩個最常攔下的反模式

S3 bucket 對外公開。一個漏設 block_public_access 或 ACL 寫成 public-read 的 bucket，會讓裡面的物件對整個網際網路可讀。這類設定在 HCL 裡只是一兩行，肉眼 review 時很容易因為「看起來像樣板」而放過，但後果是資料外洩。checkov 規則 CKV_AWS_19（S3 bucket 未啟用 server-side encryption）和 CKV_AWS_53（block public access 未全開）會標記這類漏洞：

 1# checkov 會攔下的寫法 — 缺少 block_public_access
 2resource "aws_s3_bucket" "data" {
 3  bucket = "acme-customer-data"
 4}
 5
 6# 正確寫法 — 顯式關閉公開存取
 7resource "aws_s3_bucket_public_access_block" "data" {
 8  bucket                  = aws_s3_bucket.data.id
 9  block_public_acls       = true
10  block_public_policy     = true
11  ignore_public_acls      = true
12  restrict_public_buckets = true
13}

Security group 對全世界開放。一條 ingress 寫成 cidr_blocks = ["0.0.0.0/0"] 加上 port 22 或 3306，等於把 SSH 或資料庫埠暴露給全網掃描器。tfsec 與 checkov 都會標記這種「敏感埠 + 全開 CIDR」的組合。這條規則跟模組三：網路地基講的 security group 收斂原則是同一件事的兩端 — 模組三教怎麼把規則寫對，本章用靜態掃描確保寫錯時擋得下來。

1# 三道掃描串在一起，任一 fail 就中斷
2tflint --recursive
3checkov -d . --quiet --compact
4tfsec . --soft-fail=false

命中是候選不是判決

判讀這些工具的命中時，要區分「真漏洞」與「情境合理的例外」。並非每個 0.0.0.0/0 都是錯 — 一個對外的 HTTPS load balancer 在 port 443 開全網是設計本意。所以掃描的命中是候選不是判決。

多數工具支援用行內註解標記豁免。checkov 用 #checkov:skip=CKV_AWS_260:ALB 443 對外是設計本意，tfsec 用 #tfsec:ignore:aws-elb-alb-not-public。豁免的紀律是：每個 skip 都要寫理由、要在 PR 裡可見。沒有理由的 skip 跟關掉整條規則沒有差別 — review 時看到無理由的 skip 應該當成跟看到裸 0.0.0.0/0 一樣的警報。

把例外顯式化、留下為什麼豁免的紀錄，比關掉整條規則安全。隨時間累積的 skip 也要定期盤點：某個當初合理的例外，在架構演進後可能已經不再合理。

Atlantis 與 GitHub Actions：自動化 plan 與 apply

把上述流程自動化，需要一個能監聽 PR 事件、在對的時機跑 plan 與 apply 的執行層。兩種常見做法是直接用 CI 平台（如 GitHub Actions）寫 workflow，或用 Atlantis 這類專為 Terraform PR 流程設計的工具。

Atlantis

Atlantis 是一個常駐服務，掛在 git 平台的 webhook 上。PR 開啟時它自動跑 plan 並把結果貼回 PR comment，reviewer approve 後在 PR 留言 atlantis apply，它才執行 apply 並回報結果。它的價值在於把「誰能 apply、apply 前要不要 approve、plan 結果在哪看」這些規則收斂成一致的、可設定的流程。

Atlantis 內建的 state lock 語意在多 PR 並行時特別有用：當兩個 PR 都改到同一個 Terraform project，第二個 PR 的 plan 會被 lock 擋住，直到第一個 apply 完成或 PR 關閉。這避免了兩個 PR 各自拿到的 plan 基於不同的 state 快照、apply 時互相覆蓋的問題。用 GitHub Actions 要自己實作這個 lock 邏輯（通常靠 Terraform 自己的 state lock + workflow concurrency group），複雜度高得多。

Atlantis 的代價是它本身是一個要部署、要升級、要保護的常駐服務 — 它持有對雲端的寫入權限，所以它的部署環境必須嚴格控制存取。

GitHub Actions

GitHub Actions workflow 的優點是不必額外維運服務、跟既有 CI 共用同一套 runner。缺點是 apply 的 gating 邏輯要自己用 workflow 條件拼出來。一個完整的 workflow 通常分成兩個 job：PR 觸發 plan job（跑 fmt / validate / scan / plan、把結果貼回 PR），合併到 main 才觸發 apply job。

無論哪種執行層，自動化的 apply 都需要對雲端的寫入權限，而這個權限怎麼來是整條管線的安全根基。這裡正是模組二：身分與憑證地基鋪設的 OIDC 兌現的地方 — 管線不該存放長期的 access key，而是在 runner 執行時用 OIDC 向雲端換取短期 token。

 1# 合併到主幹後，用 OIDC 換短期憑證再 apply（呼應模組二）
 2jobs:
 3  apply:
 4    if: github.ref == 'refs/heads/main'
 5    runs-on: ubuntu-latest
 6    permissions:
 7      id-token: write   # 允許 runner 取得 OIDC token
 8      contents: read
 9    steps:
10      - uses: actions/checkout@v4
11      - uses: aws-actions/configure-aws-credentials@v4
12        with:
13          role-to-assume: arn:aws:iam::123456789012:role/infra-apply
14          aws-region: ap-northeast-1
15      - uses: hashicorp/setup-terraform@v3
16      - run: terraform init
17      - run: terraform apply -auto-approve

選型判準

判讀自動 apply 的邊界：對會觸發資源重建或刪除的高風險 plan，多數團隊會保留人工 apply 的關卡（Atlantis 的手動 atlantis apply、或 workflow 加 environment protection rule 要人按確認），不讓這類變更在合併瞬間無人看管地執行。自動化的目的是消除重複勞動與人為遺漏，不是把判斷也一起省掉。

知識留在 code，而不是留在個人腦中

走完整套 PR 流程後，infra 的真正收穫是知識從個人的記憶移到了 repo 裡。每一次「為什麼這個 security group 開這個埠」「為什麼這台機器選這個 instance type」的決策，都以 code + PR 描述 + review 討論的形式留下，新人讀 repo 就能還原當初的判斷，不必去問那個「只有他懂 infra」的人。基礎設施可被閱讀，等於它可被交接。PR 流程上線後，管理層可以從 repo 的 PR merge 歷史與 plan comment 確認所有 infra 變更都經過提案與審查——這本身就是稽核要求的變更紀錄證據，不需要額外產出。

git revert 的能力與邊界

可 revert 是 PR 流程最直接的兌現。當某次變更引發問題，回退手段是 git revert 那個 commit 再走一次 PR 流程，讓基礎設施回到變更前的設定 — 跟回退一段壞掉的程式碼是同一個動作。對照手動操作的舊狀態：回退靠的是當事人記得自己改了什麼、手動在 Console 改回去，記錯或人不在就無從回退。把變更歷史留在 git，回退就從「依賴某人的記憶」變成「依賴版本紀錄」。

這份 revert 能力的邊界要講清楚。revert code 救得回的是「設定」，救不回已經被銷毀的狀態與資料：

• revert 掉一個刪除 RDS 的 commit，只是讓設定回到「該資源應該存在」。apply 時 Terraform 會試圖建一個新的空資料庫 — 但被刪掉的資料庫裡的資料不會跟著回來。
• rename 或 replace 類的變更 revert 後，可能再觸發一次資源重建 — 因為 identifier 又改回去了，而 identifier 是 immutable 屬性。
• apply 到一半失敗的 state 不能直接 revert code 修復，得先處理 state 與雲端現實的不一致。

stateful 變更的真正回退仍然靠備份與快照，這正是模組五：核心服務上 IaC stateful 處理與模組八：治理好習慣 secret / state 保護要顧的事。把 git revert 當「設定層回退」就誠實，把它當「資料層回退」就會在事故裡踩空。

知識共享的判讀訊號

判讀一個團隊是否確實把知識留在 code 的訊號：當主要負責 infra 的人請假，其他人能不能只靠讀 repo 就理解現狀並安全地改一個小設定。如果答案是「得等他回來」，那不論工具鏈多完整，知識還在個人腦中，PR 流程只是形式。這個訊號比任何工具設定都更能反映 infra 的成熟度。

讓知識真正從個人腦中搬進 repo 的方式，除了 PR 流程本身，還需要組織層的配合 — 刻意的 review 輪替、on-call 輪值、配對操作。這條路線在模組九：怎麼把 infra 推動起來展開到組織層。本章解決的是技術機制 — code 留得住知識；模組九解決的是怎麼讓團隊實際願意走這套流程、把知識交出來。

跨分類引用

• → CI/CD 教學：infra 管線用的就是這套驗證 / 發布 gate，plan / apply 對應 build / deploy 階段
• → 模組二：身分與憑證地基：管線用 OIDC 取得 apply 權限，本章是該章 OIDC 設計的回報兌現處
• → 模組三：網路地基：security group 收斂原則，本章用 tfsec / checkov 在 CI 攔下寫錯的全開規則
• → 模組五：核心服務上 IaC：stateful 資源的保護策略，git revert 救不回資料層
• → 模組八：治理好習慣：secret / state 保護
• → 模組九：怎麼把 infra 推動起來：本章把知識留在 code 的技術機制，在該章展開成組織層的採用與知識共享
• → backend 模組七：資安與資料保護：S3 公開、敏感埠全開這類掃描攔截的反模式，對應的資料保護原則
• → 團隊權限分級：權限變更走 PR 流程，讓 policy 調整有審查紀錄
• → 職務交接設計：PR 歷史是交接時的知識載體
• → Terraform CI Pipeline 設定指南：GitHub Actions 完整 workflow
• → checkov 與 tfsec 規則配置：規則選擇、豁免管理、CI 整合

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

規則選擇策略

兩個工具的內建規則集都超過數百條，涵蓋從加密設定到命名慣例。全開跑會讓命中清單長到沒人看。規則選擇的判準是「這條規則命中後，團隊會不會真的去修」——答案是不會的規則，開著只是製造噪音。

分層啟用

把規則分成三層逐步啟用，而非一次全開：

地基層是即使其他規則都關掉也要開的——S3 bucket 對外公開（CKV_AWS_19、CKV_AWS_53）和 security group 全開（CKV_AWS_24、CKV_AWS_25）這類規則命中就是真問題。營運層在 IaC 覆蓋率夠高時啟用，否則會掃到大量不在 IaC 管理內的資源。規範層等團隊有能力消化命中量再開。

checkov 的規則過濾

1# 只跑地基層規則
2checkov -d . --check CKV_AWS_19,CKV_AWS_53,CKV_AWS_24,CKV_AWS_25,CKV_AWS_40,CKV_AWS_145
3
4# 或者用 framework 過濾（只掃 Terraform）
5checkov -d . --framework terraform --compact --quiet

checkov 支援 --check（白名單，只跑這些）和 --skip-check（黑名單，跳過這些）。初期用 --check 白名單比較可控——明確列出要跑的規則，而非從全集去扣。隨著團隊消化能力提升再擴大白名單。

tfsec 的嚴重度過濾

1# 只報 CRITICAL 和 HIGH
2tfsec . --minimum-severity HIGH
3
4# 排除特定規則
5tfsec . --exclude aws-s3-specify-public-access-block

tfsec 的嚴重度分 CRITICAL / HIGH / MEDIUM / LOW。初期設 --minimum-severity HIGH 把低嚴重度的過濾掉，減少噪音量。降低閾值的時機是 HIGH 以上的命中清零後。

豁免管理

不是每個命中都是錯——對外的 ALB 在 port 443 開 0.0.0.0/0 是設計意圖、不是漏洞。豁免的重點是讓例外顯式化、有理由、可被 review。

行內豁免

1resource "aws_security_group_rule" "alb_https" {
2  type        = "ingress"
3  from_port   = 443
4  to_port     = 443
5  protocol    = "tcp"
6  cidr_blocks = ["0.0.0.0/0"]
7  #checkov:skip=CKV_AWS_24:ALB 的 HTTPS 入站需要對外開放
8}

tfsec 的行內豁免：

1resource "aws_security_group_rule" "alb_https" {
2  #tfsec:ignore:aws-ec2-no-public-ingress-sgr -- ALB HTTPS listener requires public access
3  cidr_blocks = ["0.0.0.0/0"]
4}

行內豁免的好處是理由跟程式碼在一起，review 時一眼可見。壞處是散落在各檔案裡，盤點所有豁免要 grep。

集中式豁免

checkov 支援 .checkov.yaml 集中管理豁免：

1# .checkov.yaml
2skip-check:
3  - CKV_AWS_24  # ALB public-facing SG rules
4  - CKV_AWS_19  # Legacy S3 buckets pending migration

集中式的好處是一個地方看到所有豁免，適合全域性的例外（如「這批 legacy S3 bucket 還沒遷完、暫時跳過 public access 檢查」）。壞處是理由離程式碼太遠，三個月後沒人記得為什麼跳過。

豁免紀律

每個豁免都要寫理由（-- 之後的文字）。沒有理由的豁免等於靜默跳過——review 時看不出是故意的還是為了讓 CI 過而隨手加的。定期（每季度）跑一次豁免盤點：

1# 盤點所有 checkov 豁免
2grep -rn "checkov:skip" --include="*.tf" .
3
4# 盤點所有 tfsec 豁免
5grep -rn "tfsec:ignore" --include="*.tf" .

每個命中問一句：當初跳過的原因還成立嗎？legacy 遷移完了嗎？臨時的例外變成永久的了嗎？

自訂規則

內建規則覆蓋通用安全實踐，但專案特有的規範（如「所有 RDS 必須有 cost-center tag」「所有 S3 bucket 名稱必須以公司前綴開頭」）需要自訂。

checkov 自訂規則（Python）

 1# custom_checks/require_cost_center_tag.py
 2from checkov.terraform.checks.resource.base_resource_check import BaseResourceCheck
 3from checkov.common.models.enums import CheckResult, CheckCategories
 4
 5class CostCenterTagRequired(BaseResourceCheck):
 6    def __init__(self):
 7        name = "Ensure cost-center tag is present"
 8        id = "CUSTOM_001"
 9        supported_resources = ["aws_instance", "aws_db_instance", "aws_s3_bucket"]
10        categories = [CheckCategories.GENERAL_SECURITY]
11        super().__init__(name=name, id=id, categories=categories,
12                         supported_resources=supported_resources)
13
14    def scan_resource_conf(self, conf):
15        tags = conf.get("tags", [{}])[0]
16        if isinstance(tags, dict) and "cost-center" in tags:
17            return CheckResult.PASSED
18        return CheckResult.FAILED
19
20check = CostCenterTagRequired()

1# 跑自訂規則
2checkov -d . --external-checks-dir ./custom_checks

tfsec 自訂規則（YAML）

 1# .tfsec/custom_rules.yaml
 2- id: CUSTOM_001
 3  description: S3 bucket name must start with company prefix
 4  impact: Non-standard naming breaks cross-account policies
 5  resolution: Add company prefix to bucket name
 6  requiredTypes:
 7    - resource
 8  requiredLabels:
 9    - aws_s3_bucket
10  severity: MEDIUM
11  matchSpec:
12    name: bucket
13    action: startsWith
14    value: acme-

自訂規則的數量保持精簡——每條規則都是維護成本。只有「違反後會在後續流程造成問題」的規範值得寫成自動化規則，純粹的風格偏好留給 review 時口頭提醒。

CI 整合

把掃描接進 CI 的目標是「PR 合併前就攔下問題」，而非 apply 之後才發現。

GitHub Actions 範例

 1jobs:
 2  security-scan:
 3    runs-on: ubuntu-latest
 4    steps:
 5      - uses: actions/checkout@v4
 6
 7      - name: Run checkov
 8        uses: bridgecrewio/checkov-action@v12
 9        with:
10          directory: .
11          check: CKV_AWS_19,CKV_AWS_53,CKV_AWS_24,CKV_AWS_25
12          quiet: true
13          compact: true
14          soft_fail: false
15
16      - name: Run tfsec
17        uses: aquasecurity/tfsec-action@v1
18        with:
19          minimum_severity: HIGH
20          soft_fail: false

soft_fail: false 讓掃描命中時 CI 失敗、阻擋合併。初期可以先設 soft_fail: true（掃描報告但不阻擋），讓團隊觀察命中量，確認規則集合理後再切成強制。

掃描結果回貼 PR

checkov 和 tfsec 的 GitHub Actions 都支援把結果以 PR comment 回貼。讓 reviewer 在 PR 頁面直接看到掃描結果，不用去翻 CI log。checkov-action 預設會回貼；tfsec-action 需要額外的 github_token 設定。

漸進式導入

1Week 1-2：soft_fail=true，觀察命中量和 false positive 率
2Week 3：修完所有真問題，豁免所有合理的 false positive
3Week 4：切 soft_fail=false，掃描變成強制 gate

這個節奏讓團隊在掃描變成強制之前就清理完存量，避免「一開 hard fail 所有 PR 都過不了」的窘境。

False positive 處理

false positive 的處理有三條路，依復發頻率選：

最常見的 false positive 是 ALB 的 public-facing security group（設計就是要開 443）和開發環境的寬鬆設定（dev 允許、prod 不允許）。後者可以用 checkov 的 --var-file 搭配環境變數區分——dev 跑寬鬆規則集、prod 跑嚴格規則集。

處理 false positive 時要抵抗「加 skip 讓 CI 過」的捷徑衝動。每個 skip 都要問：這是設計意圖（ALB 要開放）還是技術債（dev 環境暫時放寬）？前者寫永久豁免加理由，後者寫臨時豁免加 TODO 和預計修復時間。

跨分類引用

• → infra 走 PR 流程與自動化護欄：掃描在 PR 流程裡的定位與 plan/apply 的關係
• → Terraform CI Pipeline 設定：掃描步驟怎麼嵌入完整的 CI workflow
• → 模組三：Security Group 稽核與清理：掃描命中 0.0.0.0/0 後的處理流程

GitLab CE vs Gitea：選型判準

兩個主流的自建版本控制方案定位不同：

選型判準是團隊規模和需要的功能範圍。5 人以下、只需要 VCS + 輕量 CI 的團隊，Gitea + Drone 的組合維護成本低。10 人以上、需要 MR review + CI pipeline + Container Registry 一站到位的團隊，GitLab CE 的整合度值得它的資源消耗。

接下來以 GitLab CE 為主線說明（功能最完整），Gitea 的差異在各段附註。

GitLab CE 離線安裝

GitLab Omnibus 包把所有依賴打包成單一安裝檔，不需要在目標機器上 apt install 任何前置套件。

在外網機器下載安裝包

1# Ubuntu/Debian
2wget https://packages.gitlab.com/gitlab/gitlab-ce/packages/ubuntu/jammy/gitlab-ce_17.0.0-ce.0_amd64.deb/download.deb
3
4# RHEL/CentOS
5wget https://packages.gitlab.com/gitlab/gitlab-ce/packages/el/9/gitlab-ce-17.0.0-ce.0.el9.x86_64.rpm/download.rpm

把下載的 .deb 或 .rpm 透過內容搬運機制（USB、光碟、跨邊界傳輸站）帶進斷網環境。

在斷網機器安裝

1# Ubuntu/Debian
2sudo dpkg -i gitlab-ce_17.0.0-ce.0_amd64.deb
3
4# RHEL/CentOS
5sudo yum localinstall gitlab-ce-17.0.0-ce.0.el9.x86_64.rpm

離線設定

安裝後編輯 /etc/gitlab/gitlab.rb，把所有外部連線關掉：

 1# 設定內部域名（不是公網域名）
 2external_url 'https://gitlab.internal.example.com'
 3
 4# 關閉 Gravatar（頭像服務、需要外網）
 5gitlab_rails['gravatar_enabled'] = false
 6
 7# 關閉 usage ping（回報使用統計到 GitLab Inc）
 8gitlab_rails['usage_ping_enabled'] = false
 9
10# 關閉 version check
11gitlab_rails['gitlab_check_on_connect'] = false
12
13# 如果沒有內部 SMTP，用 sendmail 或關閉 email
14gitlab_rails['smtp_enable'] = false
15
16# TLS 憑證用內部 CA 簽發
17nginx['ssl_certificate'] = "/etc/gitlab/ssl/gitlab.crt"
18nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/gitlab.key"

1sudo gitlab-ctl reconfigure

Gitea 的離線安裝更簡單：下載單一二進位檔 gitea、設定 app.ini、用 systemd 管理即可。

升級策略

GitLab CE 的升級包也要從外部下載帶進來。升級前先備份（gitlab-backup create），升級路徑要按 GitLab 的版本跳級規則——不能任意跳版、某些大版本之間需要中繼版本。在斷網環境裡，每次升級要預先規劃中繼版本、一次帶進所有需要的安裝包。

CI Runner 離線設定

CI pipeline 在斷網環境裡跑的最大差異是 runner 不能即時拉依賴。

Runner 安裝與註冊

1# 下載 runner 二進位檔（外網下載、帶進來）
2# https://docs.gitlab.com/runner/install/linux-manually.html
3
4sudo gitlab-runner register \
5  --url https://gitlab.internal.example.com \
6  --token $RUNNER_TOKEN \
7  --executor docker \
8  --docker-image alpine:3.20

Executor 選擇

斷網環境推薦 shell executor（最少依賴）或 docker executor 搭配預拉好的 image。

Docker executor 的 image 管理

Docker executor 的每個 job 都基於一個 base image。斷網環境裡這些 image 必須預先存在於內網的 private registry：

1# runner 的 /etc/docker/daemon.json 指向內部 registry
2{
3  "insecure-registries": ["registry.internal:5000"],
4  "registry-mirrors": ["https://registry.internal:5000"]
5}

CI pipeline 裡用到的每個 image（build 用的 golang/node/php、lint 用的 tflint/checkov、deploy 用的 awscli）都要事先搬進內部 registry。

依賴快取

沒有 npm registry / PyPI / Maven Central 可以拉，CI job 的依賴安裝必須用本地來源：

1# .gitlab-ci.yml — 使用內部 Nexus 作為套件來源
2variables:
3  NPM_CONFIG_REGISTRY: "https://nexus.internal/repository/npm-proxy/"
4  PIP_INDEX_URL: "https://nexus.internal/repository/pypi-proxy/simple/"

或者把 node_modules / vendor 打包成 CI artifact 快取，避免每次 job 都重新安裝。

Git Bundle 跨邊界傳輸

某些斷網環境不允許直接 git push 到內網 GitLab（例如開發在外網、部署在內網）。Git bundle 是把 commit 歷史打包成單一檔案的機制：

1# 外網開發機：打包最近的 commit
2git bundle create changes.bundle main~5..main
3
4# 帶進斷網環境後
5git bundle verify changes.bundle
6git fetch changes.bundle main:incoming
7git merge incoming

bundle 檔案包含完整的 Git 物件（commit、tree、blob），可以通過任何檔案傳輸方式帶過邊界——USB、光碟、審批後的檔案傳輸閘道。

跨邊界傳輸的安全考量：bundle 的內容應該在傳入前被掃描（至少 git bundle verify），確認不包含預期外的分支或異常大的物件。某些高安全環境要求所有跨邊界檔案經過人工審批。

MR Review 流程

斷網環境的 MR（Merge Request）review 流程跟模組七：infra 走 PR 流程的原則相同——變更走 MR → CI 跑 plan → reviewer 看 diff + plan 輸出 → 合併 → apply。差別在於所有環節都在內網：

 1# .gitlab-ci.yml — Terraform plan 貼回 MR comment
 2plan:
 3  stage: plan
 4  script:
 5    - terraform init -plugin-dir=/opt/terraform/plugins
 6    - terraform plan -no-color -out=plan.tfplan | tee plan.txt
 7    - |
 8      curl --request POST \
 9        --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
10        --data-urlencode "body=$(cat plan.txt)" \
11        "https://gitlab.internal/api/v4/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"
12  only:
13    - merge_requests

GitLab CI 的 merge_requests trigger 跟 GitHub Actions 的 pull_request 等價——MR 開啟或更新時自動跑 pipeline。

reviewer 在 GitLab 的 MR 頁面看 code diff + plan 輸出 comment，approve 後合併，合併觸發 apply pipeline。流程跟有網路時完全相同，只是所有元件（GitLab、runner、Terraform、provider plugin）都在內網。

時程與維護

GitLab CE 的主要維護成本在升級——斷網環境的升級不能一鍵 apt upgrade，要預先下載正確版本的安裝包帶進來。跳版規則讓這個過程比正常環境多一層規劃。

跨分類引用

• → 斷網環境的通用原則：內容搬運、離線套件管理的共通模式
• → 斷網環境的容器與映像管理：CI runner 的 Docker image 管理
• → 模組七：infra 走 PR 流程：MR review 流程的原則與護欄

infra 變更走 code 流程

infra 變更的標準路徑是 PR → plan → review diff → 合併 → apply。這個順序的核心責任是把「執行前先看清楚要改什麼」變成強制步驟，而不是 apply 之後才從事故裡發現改錯了。每個環節各自承擔一段審查責任，少掉任一段，infra 就退回到不可審查的狀態。

terraform plan 是這條鏈裡最關鍵的一環。它把當前 state、雲端實際資源、與目標設定三方比對，產出一份「會新增 / 修改 / 刪除哪些資源」的 diff。這份 diff 是 review 的對象：reviewer 直接看 plan 算出來的實際變更，而非讀 HCL 自行想像結果。一個容易被低估的判讀訊號是 plan 裡的 destroy 與 replace（顯示為 -/+）— 改一個看似無害的欄位（例如某些雲資源的 name、或資料庫的 identifier）可能觸發整個資源重建，對有狀態的服務代表資料遺失或停機。Review 階段抓到這個 -/+，比 apply 到一半才發現便宜太多。

把 plan 結果貼回 PR 是讓 review 真正生效的做法。流程上，PR 觸發 CI 跑 plan，plan 輸出回貼成 PR comment，reviewer 連同程式碼 diff 一起看；approve 後才允許合併，合併才觸發 apply。這裡有個取捨：plan 與 apply 之間若隔了很久，雲端實際狀態可能已經漂移（有人手動改了、或別的 PR 先 apply 了），導致 apply 時的 plan 跟 review 時看到的不一致。多數團隊在 apply 階段會重跑一次 plan 並要求它與 review 時一致，代價是流程多一道、但換到「review 看到的就是實際執行的」這個保證。

風險邊界落在 apply 失敗的回退上。infra apply 不像程式碼部署可以直接 rollback 到上一版 image — 中途失敗時部分資源已經建立、state 可能處於半完成狀態。所以 PR 流程的價值不只在事前審查，也在事後可追溯：每次變更都對應一個 commit 與一個 PR，要回溯時知道是哪次改的、為什麼改、誰 review 的。

fmt 與 validate：最便宜的第一道檢查

fmt 與 validate 是進到任何安全掃描之前的基礎檢查，責任是擋掉格式不一致與語法 / 型別錯誤這類不需要動腦判斷的問題。它們跑得快、沒有誤判空間，適合放在 CI 最前面當作快速 fail 的關卡。

terraform fmt -check 驗證程式碼是否符合標準排版。它本身不影響基礎設施行為，價值在於消除 diff 噪音：當每個人的編輯器縮排習慣不同，PR diff 會混入大量純排版變動，把真正的邏輯變更淹沒，reviewer 更容易看漏。統一格式後，diff 裡剩下的就是語意變更。validate 則檢查設定在語法與內部一致性上是否成立 — reference 到不存在的變數、型別不匹配、必填參數缺漏，這些在 validate 階段就會報錯，不必等到 plan 連線雲端才發現。

判讀上，fmt 與 validate 失敗代表的是「這份 code 還沒準備好被認真 review」，屬於作者自己該先修掉的問題，不該佔用 reviewer 注意力。把它們設成 CI 必過的 gate，作者在本地就會先跑、先修，PR 送出時已經是乾淨的。

 1# .github/workflows/terraform.yml — plan 前的基礎檢查
 2jobs:
 3  validate:
 4    runs-on: ubuntu-latest
 5    steps:
 6      - uses: actions/checkout@v4
 7      - uses: hashicorp/setup-terraform@v3
 8      - run: terraform fmt -check -recursive
 9      - run: terraform init -backend=false
10      - run: terraform validate

tflint / checkov / tfsec：抓壞寫法與安全漏洞

fmt 與 validate 確認 code「語法正確」，但語法正確的設定仍然可能是危險的設定。tflint、checkov、tfsec 這類靜態掃描工具承擔的是「語意正確」這層：在不實際建立資源的前提下，從 HCL 裡比對已知的壞寫法與安全反模式，把問題擋在 plan 之前。它們補的是 reviewer 肉眼容易漏掉的盲區 — 人會看漏一個 0.0.0.0/0，規則不會。

這三者的側重不同，組合起來覆蓋面才完整。tflint 偏向 provider 層的正確性與慣例規範：用了已棄用的參數、instance type 在該 region 不存在、命名不符規範。checkov 與 tfsec 偏向安全與合規：掃的是會造成資料外洩或權限過大的設定。兩個最常被它們攔下、也最常釀成真實事故的模式，值得單獨說明。

第一個是 S3 bucket 對外公開。一個漏設 block_public_access 或 ACL 寫成 public-read 的 bucket，會讓裡面的物件對整個網際網路可讀。這類設定在 HCL 裡只是一兩行，肉眼 review 時很容易因為「看起來像樣板」而放過，但後果是資料外洩。checkov 有專門規則比對 bucket 的 public access 設定，命中就讓 CI fail，逼作者在合併前說明或修正。

第二個是 security group 對全世界開放。一條 ingress 寫成 cidr_blocks = ["0.0.0.0/0"] 加上 port 22 或 3306，等於把 SSH 或資料庫埠暴露給全網掃描器。tfsec 與 checkov 都會標記這種「敏感埠 + 全開 CIDR」的組合。這條規則跟模組三：網路地基講的 security group 收斂原則是同一件事的兩端 — 模組三教怎麼把規則寫對，本章用靜態掃描確保寫錯時擋得下來。

1# 三道掃描串在一起，任一 fail 就中斷
2tflint --recursive
3checkov -d . --quiet --compact
4tfsec . --soft-fail=false

判讀這些工具的命中時，要區分「真漏洞」與「情境合理的例外」。並非每個 0.0.0.0/0 都是錯 — 一個對外的 HTTPS load balancer 在 port 443 開全網是設計本意。所以這些掃描的命中是候選不是判決：多數工具支援用行內註解標記豁免（例如 checkov 的 #checkov:skip），代價是豁免要寫理由、要被 review，避免變成無聲略過。把例外顯式化、留下為什麼豁免的紀錄，比關掉整條規則安全。

Atlantis 與 GitHub Actions：自動化 plan 與 apply

把上述流程自動化，需要一個能監聽 PR 事件、在對的時機跑 plan 與 apply 的執行層。兩種常見做法是直接用 CI 平台（如 GitHub Actions）寫 workflow，或用 Atlantis 這類專為 Terraform PR 流程設計的工具。Atlantis 是一個常駐服務，掛在 git 平台的 webhook 上：PR 開啟時它自動跑 plan 並把結果貼回 PR comment，reviewer approve 後在 PR 留言 atlantis apply，它才執行 apply 並回報結果。它的價值在於把「誰能 apply、apply 前要不要 approve、plan 結果在哪看」這些規則收斂成一致的、可設定的流程，而不是散落在各 repo 各自的 workflow 腳本裡。

選哪一種是機會成本的取捨。GitHub Actions workflow 的優點是不必額外維運一個服務、跟既有 CI 共用同一套權限與 runner；缺點是 apply 的 gating 邏輯（approve 後才能 apply、apply lock 避免兩個 PR 同時改同一份 state）要自己用 workflow 條件拼出來。Atlantis 的優點是這些 gating 與 state lock 是內建語意、跨多 repo 一致；缺點是它本身是一個要部署、要升級、要保護的常駐服務。團隊 repo 少、流程簡單時 Actions 划算；管理大量 Terraform repo、需要統一 apply 治理時 Atlantis 划算。

無論哪種執行層，自動化的 apply 都需要對雲端的寫入權限，而這個權限怎麼來是整條管線的安全根基。這裡正是模組二：身分與憑證地基鋪設的 OIDC 兌現的地方 — 管線不該存放長期的 access key，而是在 runner 執行時用 OIDC 向雲端換取短期 token。模組二講的是怎麼建立這個信任關係，本章是它的回報處：因為有了 OIDC，自動 apply 才能在不持有靜態憑證的前提下安全執行，憑證外洩的攻擊面從「一把長期金鑰」縮到「單次執行的短期 token」。

 1# 合併到主幹後，用 OIDC 換短期憑證再 apply（呼應模組二）
 2jobs:
 3  apply:
 4    if: github.ref == 'refs/heads/main'
 5    runs-on: ubuntu-latest
 6    permissions:
 7      id-token: write   # 允許 runner 取得 OIDC token
 8      contents: read
 9    steps:
10      - uses: actions/checkout@v4
11      - uses: aws-actions/configure-aws-credentials@v4
12        with:
13          role-to-assume: arn:aws:iam::123456789012:role/infra-apply
14          aws-region: ap-northeast-1
15      - uses: hashicorp/setup-terraform@v3
16      - run: terraform init
17      - run: terraform apply -auto-approve

判讀自動 apply 的邊界時，要留意它不適合所有變更。對會觸發資源重建或刪除的高風險 plan，多數團隊會保留人工 apply 的關卡（Atlantis 的手動 atlantis apply、或 workflow 加 environment protection rule 要人按確認），不讓這類變更在合併瞬間無人看管地執行。自動化的目的是消除重複勞動與人為遺漏，不是把判斷也一起省掉。

知識留在 code，而不是留在個人腦中

走完整套 PR 流程後，infra 的真正收穫是知識從個人的記憶移到了 repo 裡。每一次「為什麼這個 security group 開這個埠」「為什麼這台機器選這個 instance type」的決策，都以 code + PR 描述 + review 討論的形式留下，新人讀 repo 就能還原當初的判斷，不必去問那個「只有他懂 infra」的人。這是這個模組從第一章開始累積的目的地：基礎設施可被閱讀，等於它可被交接。

可 revert 是這套機制最直接的兌現。當某次變更引發問題，回退手段是 git revert 那個 commit 再走一次 PR 流程，讓基礎設施回到變更前的設定 — 跟回退一段壞掉的程式碼是同一個動作。對照「只有我懂 infra」的舊狀態：那時候回退靠的是當事人記得自己改了什麼、手動在 console 改回去，記錯或人不在就無從回退。把變更歷史留在 git，回退就從「依賴某人的記憶」變成「依賴版本紀錄」。

這份 revert 能力的邊界要講清楚，跟本章前面講的 apply 半完成 state 是同一個誠實。revert code 救得回的是「設定」，救不回已經被銷毀的狀態與資料：revert 掉一個刪除 stateful 資源的 commit，只是讓設定回到「該資源存在」，但被刪掉的資料庫內容不會跟著回來；rename 或 replace 類的變更 revert 後，可能再觸發一次資源重建。所以 stateful 變更的真正回退仍然靠備份與快照，這正是模組五 stateful 處理與模組八 secret / state 保護要顧的事。把 git revert 當「設定層回退」就誠實，把它當「資料層回退」就會在事故裡踩空。

這條知識共享的路線會在模組九：怎麼把 infra 推動起來展開到組織層。本章解決的是技術機制 — code 留得住知識；模組九解決的是怎麼讓一個習慣手動操作的團隊真的願意走這套流程、把知識交出來。技術上能審查、能回溯、能交接是前提，但讓團隊實際採用它是另一層問題。

判讀一個團隊是否真的把知識留在 code 的訊號很具體：當主要負責 infra 的人請假，其他人能不能只靠讀 repo 就理解現狀並安全地改一個小設定。如果答案是「得等他回來」，那不論工具鏈多完整，知識還在個人腦中，PR 流程只是形式。這個訊號比任何工具設定都更能反映 infra 的成熟度。

章節文章

跨分類引用

• → CI/CD 教學：infra 管線用的就是這套驗證 / 發布 gate，plan / apply 對應 build / deploy 階段
• → 模組二：身分與憑證地基：管線用 OIDC 取得 apply 權限，本章是該章 OIDC 設計的回報兌現處
• → 模組三：網路地基：security group 收斂原則，本章用 tfsec / checkov 在 CI 攔下寫錯的全開規則
• → 模組九：怎麼把 infra 推動起來：本章把知識留在 code 的技術機制，在該章展開成組織層的採用與知識共享
• → backend 模組七：資安與資料保護：S3 公開、敏感埠全開這類掃描攔截的反模式，對應的資料保護原則

服務定位

Conftest 是 OPA 生態中 最輕量的 CI-time tool — 拿一份 Rego policy + 一份 config file、跑 conftest test 就出 violation report。它不需要 cluster、不需要 daemon、不接 admission webhook、只是個 binary。跟 OPA 比、OPA 是 runtime decision engine（HTTP server / library / sidecar 提供 policy decision）、Conftest 只是 CLI 跑 once、結束即關。跟 Gatekeeper 比、Gatekeeper 是 K8s admission controller runtime、會在 kubectl apply 時攔下違規；Conftest 是在 PR 階段就攔下、deploy 前就 fail CI。跟 Kyverno 比、Kyverno 是 K8s-only 的 admission policy（YAML 語法）、Conftest 跨多 config format（不只 K8s）且用 Rego。跟 Trivy Config 比、Trivy Config 是 built-in misconfig rule（開箱即用、預定義常見 anti-pattern）、Conftest 是 自己寫 Rego policy（客製化彈性大但要寫 rule）。

關鍵張力：CI-time static check ↔ runtime admission enforcement 是兩種互補機制、不是替代。CI 抓在 deploy 之前、但 manifest 不一定都走 PR（kubectl apply 直接打 cluster 就漏接）；admission 抓 runtime 寫入、但 deploy 後才 fail 已經慢。production 通常 CI（Conftest / Trivy Config）+ admission（Gatekeeper / Kyverno）雙層覆蓋。

本章目標

讀完本頁、讀者能判斷：

1. Conftest 在 policy-as-code stack 中承擔哪一段（CI gate）、跟 admission runtime 怎麼分工
2. Rego policy directory / conftest test / conftest verify / Bundle / Combine flag 的 ownership 跟工程化做法
3. Conftest vs Trivy Config vs Checkov vs OPA + custom CI wrapper 的取捨
4. 何時用 Conftest、何時走 Trivy Config（不想學 Rego）或 Gatekeeper（runtime enforcement）

最短判讀路徑

判斷 Conftest 導入是否健康、最少看四件事：

• Policy directory 走版控：Rego files（policy/*.rego）跟 application code 同 repo、或抽到中央 policy repo + Bundle 拉取、PR review 才能改 policy
• conftest verify 是否跑：Rego policy 本身有單元測試（*_test.rego）、policy 改動有 test coverage、不是寫完就上 production CI
• CI integration 點：跑在 PR check / merge gate、fail 阻斷 merge、不是只跑 warning 沒人看
• 跟 admission 是否雙層：CI fail 之外、cluster 也裝 Gatekeeper / Kyverno 接 runtime；否則 kubectl apply 繞過 CI 就破口

四件事任一缺失、就是 Supply Chain Integrity 邊界的待補項目。

日常操作與決策形狀

Policy directory（Rego files）：Conftest 預設讀 ./policy/ 目錄下所有 *.rego 檔。Policy 用 deny[msg] / warn[msg] / violation[msg] rule 表達 — deny 失敗整個 test、warn 只 print 不 fail、violation 給結構化輸出（含 metadata 給後續 SOAR 處理）。慣例是一個 policy 檔對一個 anti-pattern（policy/k8s_privileged.rego / policy/terraform_public_s3.rego）、不混寫。

conftest test command：conftest test deployment.yaml / conftest test --policy ./custom-policy terraform.plan.json 是日常入口。支援 --all-namespaces（K8s 多 manifest）、--input（強制 parser 類型）、--combine（跨檔 check）、--output json|tap|table（CI 報表格式）。CI integration 通常 conftest test infra/**/*.yaml --output github 直接 emit GitHub Actions annotation。

Parser（多 format 支援）：Conftest 原生支援 HCL（Terraform）/ YAML / JSON / TOML / INI / Dockerfile / CUE / Jsonnet / EDN / XML / VCL（Fastly）/ Cyclonedx SBOM 等。同一份 Rego 可跑多 format — parser 把不同 format normalize 成 Rego input JSON、policy 寫 input.spec.containers[_].securityContext.privileged == true 不管原本是 YAML 還是 JSON。這是 Conftest 比 Checkov / Trivy Config 客製化彈性更大的關鍵：同一個 policy 引擎處理跨 format misconfig。

Combine flag（跨檔 check）：conftest test --combine *.yaml 把多檔合併成單一 input array、policy 可跨檔 reference。實務場景：K8s deployment 必須有對應 service + configmap + networkpolicy、缺一就 fail；Terraform module 跨檔 reference（VPC + subnet + security group）必須一致。沒有 Combine 就只能單檔檢查、跨檔 invariant 抓不到。

conftest verify（policy unit test）：Policy 本身要有測試 — policy/k8s_privileged_test.rego 寫 test_privileged_denied / test_non_privileged_allowed、conftest verify 跑這些測試。Policy 改動先跑 verify、再 merge policy 到 production CI。沒做 verify 的 policy 是「policy 自己 broken 沒人發現」的常見破口。

Bundle（OPA bundle 拉 policy）：conftest pull 從 OCI registry / HTTP / git / S3 拉 policy bundle、policy 集中在 central repo、各 service repo 不重複維護。Bundle 包含 Rego files + data files + manifest、可簽章驗證（配 Sigstore cosign）。大組織通常 platform team 維護 policy bundle、application team 在 CI 拉最新版本跑。

CI integration：GitHub Actions（open-policy-agent/conftest-action）/ GitLab CI / Jenkins / CircleCI 都有現成 step。跑點通常在 PR check 階段（review 前 fail fast）+ merge gate（防止繞過）。失敗訊息含 file / line / policy name、SOC / SRE 看 annotation 就知道哪行違規。

核心取捨表

選 Conftest 的核心訴求：組織有 custom policy 需求 + 已用 OPA / Rego（admission 走 Gatekeeper、CI 走 Conftest 統一語言） + 跨多 config format 需要同一個 policy 引擎。如果只是要 K8s privileged container / Terraform public S3 這類常見 anti-pattern 攔截、直接 Trivy Config 開箱即用更划算。

進階主題

conftest verify（policy unit test lifecycle）：Policy 是 code、code 要有測試。policy/k8s_privileged_test.rego 寫 test_privileged_denied { count(deny) > 0 with input as {...} }、CI 跑 conftest verify ./policy 把 policy test 當 unit test。Policy change 走 PR → verify pass → 部署到 central bundle → application CI 拉新版本。沒 verify 的 policy 是「沒人知道 policy 自己壞掉、所有 application CI 都 silently pass」的 systemic 風險。

Bundle 從 OCI registry pull + 簽章驗證：conftest pull oci://registry.example.com/policy-bundle:v1.2.3 從 OCI registry 拉 policy bundle、policy distribution 走 container image 同一套 supply chain。配 Sigstore cosign 簽章驗證、policy bundle 也走 7.12 供應鏈完整性 的 release gate 邏輯 — policy 本身就是 artifact、需要 signing + verification。

跟 Trivy Config 混用：實務上 Trivy Config 跑預設 rule（CIS / NSA / OWASP baseline、開箱即用）+ Conftest 跑客製 rule（organization-specific：必須有特定 label、必須走特定 namespace、必須引用特定 ConfigMap）。兩者 CI 階段都跑、報表合併。不是二選一、是 baseline + custom 的分工。

跟 admission 雙層：CI 階段 Conftest fail 之外、cluster 也裝 Gatekeeper 接 admission。Gatekeeper 用 ConstraintTemplate（也是 Rego）、同一份 Rego policy 理論上 CI / runtime 共用 — 但實務上 admission 場景跟 static check 場景的 input shape 不同（admission 拿 AdmissionReview object、static 拿 raw manifest）、policy 通常分兩份維護或寫 abstraction layer 共用。

排錯與失敗快速判讀

• Policy pass 但 production 還是 misconfig：CI 沒卡在 merge gate、或有 kubectl apply 繞過 PR — 加 admission controller（Gatekeeper / Kyverno）做 runtime 雙層
• Rego policy 自己 broken / silently pass：沒寫 *_test.rego + conftest verify — 補 policy unit test、CI 跑 verify 才 promote
• conftest test 跑出 0 violations 但 manifest 有問題：policy directory 沒讀對、或 parser 自動偵測選錯 — 顯式 --policy ./policy --input yaml
• 跨檔 invariant 抓不到（deployment 沒對應 service）：忘記用 --combine flag — 改 conftest test --combine *.yaml
• Bundle 拉到舊版本 / policy drift：沒固定 bundle tag、用 latest 漂移 — bundle reference 用 digest（sha256:...）或 immutable tag
• False positive 多 / team 開始 ignore CI：policy 寫得太寬、沒考慮合理例外 — Rego 加 exception list（data.exceptions）、走 Exception Workflow lifecycle
• Policy 散落各 application repo / 維護不一致：沒走 central bundle — 抽 policy 到中央 repo、各 application 拉 bundle

何時改走其他服務

不在本頁內的主題

• Rego 完整語法 reference、every / walk / built-in function 進階用法
• OPA Bundle 的 server-side 實作（policy publish pipeline）
• Conftest 跟 Open Policy Agent runtime 的內部架構差異
• Sigstore cosign 的 keyless signing flow 細節

案例回寫

Conftest 在 07 案例庫沒有直接 vendor-level 事件、但所有 supply chain case 都是 CI-time policy gate 的對照：

下一步路由

• 上游：7.12 供應鏈完整性與 artifact 信任
• 平行：OPA、Gatekeeper、Kyverno、Trivy
• 跨類：GitHub Advanced Security（CI security check pipeline 共用）
• 官方：Conftest Documentation