服務定位

OPA 的核心抽象是 decoupled decision + enforcement — OPA 只負責 decide（input 進來、allow / deny + decision metadata 出去）、application 負責 enforce（拿到 decision 後實際 reject request / block deploy / mask data）。這個解耦讓同一份 policy 跨 K8s admission（透過 Gatekeeper 或 kube-mgmt sidecar）、Envoy authz filter、API gateway、Terraform pre-plan、SQL row-level filter、Kafka topic ACL 都能重用。

OPA 的查詢語言是 Rego、Datalog-like declarative language、設計上適合表達「給定一組 fact，這個動作合法嗎」。Rego 跟一般 imperative programming（Python / Go / YAML rules）差距大、team 要投入 1-2 週才能寫出 production-grade policy；換回的是 表達力 + 跨情境一致性 — Kyverno 的 YAML policy 易上手、但跨 K8s 邊界後沒辦法用。

關鍵張力：Rego 學習曲線 ↔ unified policy 的長期價值。只跑 K8s 的團隊用 Kyverno YAML 更直覺；只跑 CI policy 的用 Conftest 更輕；要在 K8s + API + Terraform + DB 跨層統一 policy、或要 audit-grade decision log、或預期 policy 會長期累積成資產的、才值得投資 OPA + Rego。

商業模型：核心 OPA 是 Apache 2.0 OSS、免費。Styra DAS（OPA 創辦人公司）是 enterprise SKU、提供 policy library + impact analysis + multi-cluster management + audit dashboard、適合大型團隊。OPAL（Permit.io 維護的 OSS）是 GitOps-style policy distribution layer、補 OSS OPA 缺的 bundle server。

本章目標

讀完本頁、讀者能判斷：

1. OPA 在 policy stack 中承擔哪一段（decision engine） vs enforcement point 各自的 ownership
2. Rego 投資門檻是否值得（K8s-only vs 跨 enforcement point）
3. Policy bundle / Decision log / Partial evaluation 三個 first-class concept 在 production 的設計形狀
4. 何時用 OPA、何時走 Kyverno / Gatekeeper / Conftest 的取捨

最短判讀路徑

判斷 OPA deployment 是否健康、最少看四件事：

• Policy ownership：誰能寫 / 改 Rego policy（platform team / security team / SRE）、policy 是否進 Git、change 是否經 PR review + staging tenant 跑 24-48hr 觀察
• Bundle distribution：policy 是否 build 成 bundle（tar.gz）、是否簽章、OPA agent 是否定期 pull、bundle server 在哪（自管 nginx / S3 / OPAL / Styra DAS）
• Decision log governance：每個 decision 是否進 audit log（input + output + policy version + timestamp）、log 是否進 SIEM（Splunk / Elastic）、retention 多久
• Enforcement coverage：哪些 enforcement point 接 OPA（K8s admission / API / Envoy / Terraform）、policy 是否 share 還是各 point 各寫一份、跨 point 的一致性怎麼驗

四件事任一缺失、就是 Policy as Code Foundations 的待補項目。

日常操作與決策形狀

Rego policy 形狀：Rego 是 Datalog-like declarative language、policy 寫成 allow { ... } rule、所有條件成立才 evaluate 為 true。實務 idiom：底層寫 base policy（如 policies/k8s/required_labels.rego）、上層寫 policy library（共用 helper 如 policies/lib/registry.rego）、application 端傳 input（K8s admission request / API request / Terraform plan JSON）查詢。Rego 鼓勵 small composable rule、不寫長 imperative function。

Policy bundle：OPA 不從 Git 直接讀 policy、而是讀 bundle（tar.gz、含 .rego + data JSON、optional 簽章）。Bundle 從 bundle server pull（自管 nginx / S3 / OPAL / Styra DAS）、OPA agent 定期 polling（預設 60s）。Bundle 的核心價值是 versioned + signed + atomically swap — policy 更新不會 partial apply、簽章確保中間沒被改、版本 metadata 讓 decision log 可追到當時用哪版 policy。

Decision log：每個 OPA query 都可開 decision logging、log entry 含 input + result + policy_version + timestamp + decision_id。意義是 audit-grade reconstruction — 事後可以重跑 opa eval --bundle <version> --input <log_input> 驗證當時 decision 是否正確。Decision log 進 SIEM 後可做 over-permission analysis（哪些 user 拿到 allow 但實際從不該被 allow）跟 policy coverage check（哪些 rule 從沒被觸發過、可能是 dead code）。

Integration pattern：production OPA 主要四種 enforcement integration — K8s admission（走 Gatekeeper 是 OPA 官方 K8s integration、或 kube-mgmt 把 OPA 當 sidecar 跑、admission webhook 把 request 送進 OPA decide）；API authz（application 在 request handler 開頭 query OPA、拿 allow/deny 後 enforce）；Envoy / service mesh（Envoy 的 ext_authz filter 接 OPA、L7 authz decision）；Infrastructure as Code（CI 跑 Conftest 對 Terraform plan / K8s YAML 做 OPA 評估）。

Partial evaluation：OPA 進階 feature、把一份 policy 對某個 partial input（如 user="alice"）pre-evaluate、產出 殘餘 query（如 SQL WHERE tenant_id IN (...) 或 regex），下發給 enforcement point 直接用。意義是 把 policy decision 推到 enforcement point 內部、減少每次 query 都要過 OPA 的 latency；常用於 row-level data filter（policy 寫一次、partial eval 出 SQL WHERE clause、application 直接拼進 query）。

OPAL（GitOps for OPA）：OSS、Permit.io 維護、解決「policy 從 Git push 到所有 OPA agent」的 distribution 問題。Git → OPAL Server → OPA Agent 的 push model、policy commit 到 main branch 後幾秒內所有 OPA 更新。對應 OSS-only 的 production setup；Styra DAS 提供同等功能 + 管理 UI。

Styra DAS（商業 management）：Styra 是 OPA 創辦人公司、DAS 是 enterprise SKU。核心價值：policy library（pre-built policy for K8s / Terraform / Kafka）、impact analysis（policy 上 production 前 dry-run 看會 deny 多少現有 resource）、multi-cluster policy distribution、audit dashboard。OSS-only 自己拼 OPAL + decision log + SIEM 也能做、但團隊 > 50 個 cluster / 多 BU 時 DAS 划算。

Constraint Framework：Gatekeeper 在 OPA 之上加的 K8s-specific 抽象、用 ConstraintTemplate（Rego policy 模板）+ Constraint（K8s CRD instance、實際 enforce）。對純 K8s 場景比直接寫 Rego 更 K8s-native；但這個抽象只在 K8s 領域有意義、不會跨到 API / Terraform。

核心取捨表

選 OPA 的核心訴求：跨 enforcement point 的 unified policy + long-term policy 資產化 + audit-grade decision log + 團隊願意投資 Rego。純 K8s + 想快速上手用 Kyverno；K8s + 已決定走 OPA 生態用 Gatekeeper；只跑 CI 不跑 runtime 用 Conftest。

進階主題

Rego idioms（policy library + base policy）：production Rego 走分層結構 — lib/（utility function、registry whitelist、CIDR check）、base/（concrete policy、引用 lib）、tests/（用 opa test 跑 unit test）。Policy 也是 code、走 PR review + CI test + staging tenant、不是 console 直改。

Partial evaluation for SQL row-level filter：把 policy 寫成「user 能看哪些 row」、用 opa eval --partial 把 user="alice" 部分 pre-evaluate、output 殘餘 query 變 SQL WHERE tenant_id IN ('a', 'b', 'c')、application 拼進 query。意義是 policy 不在 query path latency 上、policy 規則仍是 SSoT。對應 RLS（row-level security）的工程化作法。

跟 SPIRE workload identity 整合 authz：service-to-service authz 場景、SPIRE 簽 SVID（SPIFFE ID + mTLS cert）證明 caller 身份、OPA 拿到 SPIFFE ID 後 decide「這個 service 能呼叫這個 API 嗎」。SPIRE 解 who、OPA 解 can they do this、職責清楚分離。

跟 Vault 整合 dynamic credential policy：Vault 簽 dynamic credential（DB password / cloud STS token）的 issue 決定可以走 OPA — Vault 收到 issue request、轉 OPA decide「這個 caller 在這個 context 能不能拿這個 scope 的 token」。對應 Failure: Credential Rotation Without Scope 的 lesson：scope 判斷不分散在應用層、集中到 policy engine。

Decision log 進 SIEM：OPA decision log 設成 push 到 Splunk HEC / Elastic / Datadog、進 SIEM 後可做三件事 — over-permission analysis（哪些 allow 從沒被合法理由觸發）、dead policy detection（哪些 rule 從沒被 evaluate）、anomalous decision pattern（某 service 突然大量 allow 不在 baseline）。

跟 K8s admission 的兩條路：純 K8s admission 場景、走 Gatekeeper（OPA 官方 K8s integration、有 Constraint Framework 抽象、社群活躍）比直接跑 OPA + kube-mgmt sidecar 更 production-ready。kube-mgmt 路線適合 already-running OPA 想加 K8s admission 而不引入 Gatekeeper 抽象。

排錯與失敗快速判讀

• Rego policy review 卡 SRE：policy 都得 SRE 寫、security team 看不懂 — 拆 lib/ 給 SRE 維護、base/ 給 security review、用 opa test unit test 保持迭代速度
• Bundle distribution 慢 / policy 不一致：自管 nginx bundle server 沒高可用、agent pull 失敗 fallback 用舊版 — 換 OPAL push model 或 S3 + CloudFront、bundle pull 失敗時 OPA --set status.console=true 直接 alert
• Decision log 沒進 SIEM：OPA 開了 decision log 但只進本地 file、沒人看 — 設 decision log plugin push 到 Splunk HEC / Kafka、不是寫本地 disk
• Policy 改完 production 大量 deny：新 policy 沒在 staging dry-run、上 production 後合法 traffic 被擋 — Styra DAS 的 impact analysis 或自己跑 opa eval --partial 對歷史 decision log replay、看 deny 數量再 promote
• OPA latency 高 / API 卡：每個 request 都 round-trip OPA、policy 複雜 evaluation 慢 — embed OPA as library（Go SDK / WASM）跑 in-process、或用 partial evaluation 把 policy compile 進 SQL / regex
• Rego policy bug 線上才發現：沒 unit test、staging 沒 cover edge case — 強制 PR 要含 opa test case、staging 跑 shadow mode（log only 不 enforce）24hr 再切 enforce
• 跨 cluster policy drift：多 cluster 各自 apply、版本不同步 — OPAL 或 Styra DAS multi-cluster sync、不靠 kubectl apply 人工同步

何時改走其他服務

不在本頁內的主題

• Rego 完整語法 reference（rule / function / built-in / with / some）
• Gatekeeper Constraint Framework 的 ConstraintTemplate / Constraint CRD 設計細節（屬 Gatekeeper 頁）
• Conftest CLI 用法跟 conftest test / conftest verify 流程（屬 Conftest 頁）
• Kyverno YAML policy 語法跟 mutate / generate / verifyImages（屬 Kyverno 頁）
• Styra DAS 商業 license / SKU 對照、Nirmata Enterprise 對照
• WASM-compiled Rego policy 的 edge deployment 細節

案例回寫

下一步路由

• 上游：7 章 policy-as-code foundations、7.12 供應鏈完整性
• 平行（Policy-as-Code 批次）：Conftest（CI static check）、Kyverno（K8s YAML-native）、Gatekeeper（OPA K8s integration）
• 跨類：SPIRE（workload identity → OPA authz）、Vault（dynamic credential policy）、Trivy（scan → OPA gate）、Splunk（decision log → SIEM）
• 跨模組：6 reliability（CI pre-deploy gate 接 Conftest）、8 incident response（policy violation alert → IR routing）
• 官方：Open Policy Agent、Rego Policy Language、Styra DAS、OPAL

服務定位

Kyverno 的定位是 K8s admission controller-shaped policy engine、policy 用 YAML 表達。底層是 dynamic admission webhook + background controller、頂層 CRD 包含 ClusterPolicy（cluster 範圍）/ Policy（namespace 範圍）/ PolicyException（明確例外）/ ClusterCleanupPolicy（過期 resource 清理）/ PolicyReport（CIS / NIST 等審計輸出）。Nirmata 是 Kyverno 商業版、補 policy library / multi-cluster management / audit dashboard / 24x7 support。

跟 OPA 比、Kyverno 走 narrow + opinionated — OPA 是 general-purpose policy engine（K8s / API gateway / Terraform / 自家服務都能用、語言是 Rego）、Kyverno K8s-only + YAML、學習成本對 K8s admin 接近零。跟 Gatekeeper 比、Gatekeeper 也是 K8s admission controller 但底層用 OPA + Rego、ConstraintTemplate / Constraint 兩層 CRD；Kyverno 不用 Rego、policy 就是 YAML rule list。跟 Trivy 的 misconfig scan 比、Trivy 是 scan static manifest、Kyverno 是 admission gate + background scan、定位互補不衝突。

關鍵張力：YAML policy 的表達力上限 ↔ 跨平台統一 policy 的訴求。Kyverno YAML rule 對 90% K8s 場景夠用、但需要跨 K8s / API gateway / Terraform 統一 policy decision 時、Rego 的表達力跟可移植性勝出。要看清楚 policy 邊界是否就在 K8s 內。

本章目標

讀完本頁、讀者能判斷：

1. Kyverno 在 K8s 治理 stack 中承擔哪一段（admission gate / mutation / generation / image verify / cleanup）、跟 Trivy scan / SBOM Tools / Sigstore cosign 怎麼分工
2. ClusterPolicy / Policy 的 ownership 設計（platform team 還是 app team 寫、誰 review、PolicyException 怎麼治理）
3. Validate / Mutate / Generate / Verify Images / Cleanup 五類 rule 的使用邊界跟陷阱
4. 何時用 Kyverno、何時走 OPA / Gatekeeper / K8s native ValidatingAdmissionPolicy 的取捨

最短判讀路徑

判斷 Kyverno deployment 是否健康、最少看四件事：

• Policy 是否走 GitOps：ClusterPolicy / Policy 是否在 Git 版控、走 ArgoCD / Flux sync、policy change 是否經 PR review、staging cluster 跑過 audit mode 才 promote 到 enforce
• Mode 配置：每條 policy 是 Audit（只記、不擋）還是 Enforce（擋 admission）、新規則是否先 audit 觀察 24-48hr 再 enforce、Background scan 是否開（補 admission 不到的 historical drift）
• Verify Images 啟用度：production cluster 是否要求 image 必須通過 cosign signature verify、SBOM attestation 是否驗、policy 是否包含 keyless verify（Fulcio + Rekor）
• PolicyException 治理：例外是否走 PR 申請 + 到期日 + owner、跟 Detection Coverage and Signal Governance 的 exception governance 對齊

四件事任一缺失、就是 7.12 供應鏈完整性 邊界的待補項目。

日常操作與決策形狀

ClusterPolicy / Policy 結構：Kyverno policy 是 K8s CRD、結構 spec.rules[] 一條條 rule、每條 rule 有 match（套用對象、kind / namespace / label / name）+ exclude（明確排除）+ rule body（validate / mutate / generate / verifyImages / cleanup 五選一）。ClusterPolicy 套整個 cluster、Policy 套單一 namespace、app team 通常只能改自家 namespace 的 Policy、平台 team 控 ClusterPolicy。

Validate rule：admission 階段檢查 manifest 是否符合條件、不符合就拒絕。最常見場景 — 禁止 latest tag、要求所有 pod 有 resource limit、禁止 privileged container、要求 specific label。寫法是 validate.pattern 或 validate.deny（後者支援更複雜的 boolean expression）、output 是 admission webhook reject。Validate 是 K8s policy as code 的入門場景、80% 的 ClusterPolicy 都是 Validate rule。

Mutate rule：admission 階段修改 manifest、把缺的欄位補上或改成符合的值。常見場景 — 自動注入 sidecar（service mesh proxy / log forwarder）、自動加 resource limit default、自動加 label（cost center / owner）、自動把 imagePullPolicy 改成 Always。Mutate 是 OPA / Gatekeeper 做不到的（兩者都偏 Validate-only）、是 Kyverno 的 K8s-specific 強項。陷阱是 mutate 變更後 GitOps diff 會永遠不一致、要在 ArgoCD ignoreDifferences 上對齊。

Generate rule：cluster event（namespace 建立、resource 變動）觸發、自動建立 關聯 resource。最常見場景 — 新 namespace 自動建 default NetworkPolicy（deny-all egress 起手）、自動建 ResourceQuota / LimitRange、自動 copy ConfigMap / Secret 到新 namespace。Generate 是把 security default 從文件層落到 runtime layer、避免 app team 忘記設 NetworkPolicy 就把整個 cluster 暴露。Generate 也是 OPA / Gatekeeper 做不到、Kyverno 獨有。

Verify Images rule：admission 階段驗證 container image 的簽章 / SBOM attestation / in-toto provenance。實作底層 Sigstore cosign — keyless 簽章驗 Fulcio CA + Rekor transparency log、key-based 驗 public key、attestation 驗 SLSA provenance / SBOM。production 場景 — internal registry image 必須 cosign 簽 + 來自 trusted CI runner、external image 必須在 allowlist。對應 SolarWinds 2020 Sunburst 的 supply chain attack 防禦邊界。

Cleanup policy：ClusterCleanupPolicy / CleanupPolicy 是 K8s 1.27+ 引入、Kyverno 1.10+ 支援、按 cron 跑、清掉符合條件的 resource。常見場景 — 過 30 天的 completed Job、過 7 天的 failed Pod、ephemeral namespace（PR preview env）超過 TTL 自動刪。Cleanup 補的是 K8s 沒有 resource lifecycle policy 的洞、TTL controller 只覆蓋 Job / Pod 子集。

Background scan：除了 admission 攔截 新 resource、Kyverno 定期掃描 已存在 resource 是否違反 policy、結果寫入 PolicyReport CRD。意義是補 歷史 drift — policy 是後來加的、已 deploy 的 resource 不會被 admission 攔到、background scan 才會找出來。production 一定要開、不開等於 policy 只防新犯不抓舊案。

ValidatingAdmissionPolicy (VAP) 整合：K8s 1.30+ 內建 CEL-based admission policy、不需要 admission webhook（VAP 由 kube-apiserver 直接 enforce、延遲低、不會因為 Kyverno pod 掛掉就讓 admission 失敗）。Kyverno 1.11+ 可以從 ClusterPolicy 生成 VAP、把簡單 Validate rule 卸載給 K8s native engine、複雜 rule（Mutate / Generate / Verify Images）留在 Kyverno。長期趨勢 — K8s native VAP 會吃掉 Kyverno Validate-only 的場景、Mutate / Generate / Verify Images 仍是 Kyverno 護城河。

GitOps 整合：ClusterPolicy / Policy 是普通 K8s CRD、走 ArgoCD / Flux sync 沒任何特殊性。staging cluster 跑 Audit mode 24-48hr 看 PolicyReport 有多少違規 → tune rule 或加 PolicyException → 確認沒誤殺再 promote 到 production cluster 的 Enforce mode。對應 Detection Engineering Lifecycle 的 propose → staging → promote pattern。

Policy Reporter：OSS dashboard（不是 Kyverno 內建、是社群專案）、把 PolicyReport CRD 視覺化、給 platform team / app team 看 cluster 違規概況。Nirmata 商業版有更完整的 multi-cluster dashboard + 歷史 trend + compliance mapping（CIS / NIST / PCI）。

核心取捨表

選 Kyverno 的核心訴求：K8s-only 場景 + 不想學 Rego + 需要 Mutate / Generate / Verify Images 的 K8s-specific 能力。團隊已投資 Rego ecosystem、或 policy 邊界跨 K8s + Terraform + API gateway、走 OPA / Gatekeeper 更合適。CI-time pre-merge 檢查走 Conftest 補位。

進階主題

Verify Images 進階 — cosign keyless + SBOM attestation：production-grade image trust 不只驗 signature、要驗 who signed it from where with what build process。keyless 模式驗 Fulcio CA-issued 短期憑證 + Rekor transparency log entry、確認簽章來自 trusted CI runner 的 OIDC identity（例如 https://github.com/myorg/myrepo/.github/workflows/release.yaml@refs/tags/v*）。SBOM attestation 用 verifyImages.attestations 驗 in-toto envelope、確認 image 帶 SLSA provenance + SBOM（CycloneDX / SPDX）。對應 XZ Backdoor 2024 的 lesson：maintainer takeover 也能簽 image、要靠 build provenance attestation 看出 build process 跟過去不一致。

Mutate policy 跟 GitOps 的張力：Mutate 自動補欄位、ArgoCD / Flux 會永遠看到 live state 跟 Git state diff。處理方式有三 — ignoreDifferences on specific fields（ArgoCD spec.ignoreDifferences、Flux spec.patches）、把 mutate 改成 validate + 在 PR template 補預設（成本高但 GitOps diff 乾淨）、Mutate at create only（用 mutate.mutateExistingOnPolicyUpdate: false、只在 admission 動、不重複 mutate existing resource）。

Generate policy 跟 multi-tenant security default：新 namespace 一建立、Generate rule 自動建 default-deny NetworkPolicy + ResourceQuota + LimitRange + 必要 RoleBinding。意義是 security default 從 README 落到 runtime、app team 開新 namespace 不會忘記設安全邊界。陷阱是 generated resource 的 ownership — 預設 Kyverno owns、app team 修改會被 reconcile 回去；要讓 app team 改、用 synchronize: false。

Nirmata Enterprise：商業版補三件事 — Policy Library（CIS / NIST / PCI / SOC 2 預製 policy pack）、Multi-cluster Management（中央 console 推 policy 到多 cluster + audit dashboard + drift detection）、Policy Reporter Plus（trend + compliance mapping + JIRA / Slack integration）。對大企業多 cluster + 合規驅動的場景值得評估、中小 deployment OSS Kyverno + 社群 Policy Reporter 夠用。

PolicyException 治理：Kyverno 1.9+ 引入 PolicyException CRD、讓特定 resource 明確繞過特定 policy、避免「app team 為了 deploy 直接把 policy 改寬」。Exception 走 PR + 到期日 + owner、跟 Detection Coverage and Signal Governance 的 exception lifecycle 對齊 — 例外不是黑箱、是 暫時性、有 owner、有 review 日期。

排錯與失敗快速判讀

• Policy 改了沒生效：admission webhook 沒 ready、或 policy 寫在錯的 namespace（Policy CRD 是 namespace-scoped、放錯 namespace 不會作用）— kubectl get clusterpolicies 看 ready 狀態、kubectl describe 看 events
• Admission 卡住 / Pod 起不來：Kyverno webhook 掛掉、failurePolicy 設 Fail 結果整個 cluster 不能 deploy — production 對 critical workload 設 failurePolicy: Ignore + 監控 Kyverno controller availability、不要讓 policy engine 變成 cluster-wide SPOF
• Mutate 後 ArgoCD 永遠 OutOfSync：mutate 改的欄位沒在 ArgoCD ignoreDifferences 排除 — 對應加 spec.ignoreDifferences[*].jsonPointers 或 .jqPathExpressions、不然每次 sync 都跳 diff
• Verify Images 全部失敗：cluster 沒對外網路、Fulcio / Rekor 拉不到、或 image 真的沒簽 — 先 audit mode 跑 + 看 PolicyReport 統計 unsigned image 比例、確認預期路徑（內部 image 簽 / 外部 image allowlist）後才 enforce
• Background scan 跑爆 controller：cluster 太大、scan interval 太短 — 調整 backgroundScan: false for 高頻變動 policy、或拉長 scan interval、或 Nirmata 用分散式 scan
• PolicyException 變成漏洞：例外沒到期日、owner 離職、規則永久繞過 — Exception CRD 補 metadata（owner / expiry / ticket）+ 定期 audit 過期 Exception
• VAP migration 不一致：Kyverno 生成的 VAP 跟原 ClusterPolicy 行為有差（CEL 不支援部分 Kyverno feature）— 對 critical rule 保留 Kyverno 不 migrate、只把簡單 Validate 卸載

何時改走其他服務

不在本頁內的主題

• Kyverno policy 完整 YAML reference、JMESPath 進階用法
• Sigstore cosign CLI 操作、Fulcio / Rekor 部署
• Nirmata Enterprise 詳細功能跟 pricing
• K8s ValidatingAdmissionPolicy CEL 語法 reference
• 跟 service mesh（Istio / Linkerd）整合的 sidecar injection 細節

案例回寫

下一步路由

• 上游：7.12 供應鏈完整性、Detection Coverage and Signal Governance
• 平行：OPA、Gatekeeper
• 下游：Trivy（scan + label）、Snyk（vuln 資訊源）、SBOM Tools（attestation 來源）
• 跨類：Sigstore cosign（CI 簽、Kyverno 驗）、ArgoCD / Flux（GitOps sync policy 本身）
• 跨模組：8 事故處理 vendor 清單（policy violation → IR routing）
• 官方：Kyverno Documentation、Sigstore Documentation

服務定位

Gatekeeper 的核心定位是 Rego policy 在 K8s admission 層的 K8s-native 包裝、不是另一個 policy engine。底層仍是 OPA、Rego 是同一套語言；上層加了兩個 K8s-specific 抽象 — ConstraintTemplate（Rego policy + parameter schema 的 CRD 定義）跟 Constraint（Template 的 instance、指定 match scope 與 parameter）。意義是同一份 Rego policy 寫一次、在不同 cluster / 不同 namespace 給不同 Constraint instance、不用改 Rego 本體。

跟 OPA（純 sidecar）比、Gatekeeper 走 K8s-native + 兩層抽象、犧牲 OPA 純 sidecar 的跨平台彈性（OPA 可同時管 K8s admission + API gateway + Terraform plan）、換來 K8s 內部 CRD + RBAC + GitOps 的一致體驗。跟 Kyverno 比、Gatekeeper 走 Rego DSL、Kyverno 走 YAML pattern matching — team 已投資 OPA / Rego（API gateway / Terraform 已用 Rego）就走 Gatekeeper、純 K8s shop + 沒 Rego 包袱直接用 Kyverno 較省學習成本。跟 Conftest 比、Conftest 是 CI-time static config check、Gatekeeper 是 runtime admission + audit、兩者互補不互斥（CI 用 Conftest 擋 PR、admission 用 Gatekeeper 擋 deploy）。

關鍵張力：Rego 學習曲線 ↔ 跨平台 policy 一致性 是 Gatekeeper 跟 Kyverno 最大的選擇分水嶺。純 K8s 場景 Kyverno YAML 寫起來快、但同樣的 image signature 規則若要在 Terraform plan / CI / admission 三處 enforce、Rego 寫一次跨三處比 YAML / Cue / Sentinel 多種語言混用乾淨。

本章目標

讀完本頁、讀者能判斷：

1. Gatekeeper 在 cluster policy stack 中承擔哪一段（admission validation / audit / mutation）、哪些要外接（OPA 純 sidecar 管非 K8s 對象、Conftest 補 CI-time）
2. ConstraintTemplate 跟 Constraint 兩層怎麼切（Template 由 platform team 維護、Constraint 給 app team 在 namespace 內 instantiate）
3. Audit / Mutation / External Data Provider 何時開、開了之後 cost 與 failure mode
4. 何時用 Gatekeeper、何時改 Kyverno 或退回純 OPA 的取捨

最短判讀路徑

判斷 Gatekeeper deployment 是否健康、最少看四件事：

• ConstraintTemplate 的 ownership：誰寫 Rego、誰 review、Template 是否走 Git（PR review + Gator CLI unit test）、是否有共用 library 避免每個 Template 重寫 K8s helper
• Audit coverage：除了 admission 攔截、Audit 是否定期 scan 已存在 resource（pre-Gatekeeper 部署的 legacy resource 違規）、auditFromCache 是否開、audit interval 是否合理（預設 60s、production 通常拉到 5-10min 避 API server 壓力）
• Failure mode 治理：Constraint enforcementAction 是 deny / warn / dryrun、Webhook failurePolicy 是 Fail / Ignore、Fail + Gatekeeper pod down 會擋全 cluster deploy
• 跟 GitOps 的對接：ConstraintTemplate / Constraint 是否走 ArgoCD / Flux 部署、policy change 是否經 staging cluster 驗證、emergency exception 流程是否定義

四件事任一缺失、就是 Detection Coverage and Signal Governance 在 admission 層的待補項目。

日常操作與決策形狀

ConstraintTemplate（CT）— Rego policy + CRD 定義：CT 是 Gatekeeper 的核心抽象、由 Rego policy + parameter schema（OpenAPI v3）兩段組成。Template 寫好 apply 到 cluster 後、Gatekeeper 會生成同名 CRD（例 K8sRequiredLabels）、app team 就能用該 CRD 寫 Constraint。Template 由 platform team 維護、不該每個 app team 自己寫 Rego — 集中維護才能保證 helper / convention / unit test 一致。

Constraint — Template 的 instance + match scope：Constraint 指定三件事 — 該套用哪個 Template（kind）、套用範圍（match：kinds / namespaces / labelSelector / excludedNamespaces）、parameter 值（spec.parameters、對應 Template 的 schema）。同一個 Template 可以有多個 Constraint instance（production / staging 不同 threshold、不同 namespace 不同 required label set）。這層抽象的意義是 policy logic 跟 environment-specific configuration 分開。

Audit — background scan 已存在 resource：除了 admission webhook 在 create / update 時攔、Audit controller 定期（預設 60s）掃整個 cluster 找違規 resource、結果寫到 Constraint status 的 violations 欄位。意義是 legacy resource 在你 install Gatekeeper 之前就在那、admission 不會觸發、Audit 才會抓到。auditFromCache: true 用 Gatekeeper 自己的 informer cache 不打 API server、適合大 cluster。

Mutation — 2024+ stable：早期 Gatekeeper 只有 Validation、Mutation 在 v3.10+ 進 beta、2024 隨 v3.14+ 進 stable。Mutation 走獨立 CRD（Assign / AssignMetadata / ModifySet）、不走 ConstraintTemplate。常見用法：注入 securityContext.runAsNonRoot: true、補 default resource limit、加 organization label。Mutation 跟 Validation 都開的話、Mutation 先跑、Validation 看 mutated 後的結果。

Sync Resources — cross-resource lookup：Rego policy 若要查 別的 resource（例：擋 Service 用了不存在的 Namespace）、要先 declare Config CRD 把該 resource type 加進 Gatekeeper 的 sync list、Gatekeeper 才會在 cache 裡有那個 resource 供 Rego 查。沒 sync 的 resource 不能跨 reference、是常見踩雷點。

External Data Provider — query 外部 API 做 decision：Gatekeeper v3.10+ 引入 External Data Provider、Rego 可以 call 外部 HTTPS endpoint 取 runtime data 做 policy decision。典型用法：query image scan service（例 Trivy server）確認 image 沒 CVE、query SBOM attestation service 確認 supply chain 完整、query custom IAM 確認 namespace owner 有權建立該 resource。要設 timeout + cache、外部 service down 不能擋全 cluster admission。

Gator CLI — policy unit test：Gator 是 Gatekeeper 官方 CLI、本機跑 Template + Constraint 對 mock K8s manifest、不需 cluster。CI pipeline 跑 gator test 對每個 Template 跑 fixture、policy change 出 PR 時自動驗證 — 避免 production deploy 才發現 Template Rego bug 擋全 cluster。

跟 GitOps 整合：ConstraintTemplate / Constraint / Mutation / Config CRD 都是純 YAML、走 ArgoCD / Flux 部署是標準作法。實務 layout：gatekeeper-system namespace 裝 Gatekeeper、gatekeeper-policies repo 放 Template 跟 baseline Constraint（platform team owned）、各 app namespace 的 Constraint instance 可以由 app team 在自己 repo 管理（透過 ArgoCD AppProject 限制 Constraint kind）。

核心取捨表

選 Gatekeeper 的核心訴求：team 已用 Rego（API gateway / Terraform plan / CI 已 OPA）+ 想把 same policy 延伸到 K8s admission + 看重 OPA ecosystem 一致性。純 K8s shop 沒 Rego 包袱、又特別需要 Mutation 場景密集（PSP 廢除後重建、跨 namespace 統一 sidecar 注入）直接走 Kyverno 更省學習成本。

進階主題

Rego idioms for K8s admission：K8s admission review 物件結構是 input.review.object、Template 的 violation rule 走 violation[{"msg": msg}] { ... } 形式。常見 idiom：match.kinds 跟 match.namespaceSelector 在 Constraint 層處理 scope、Rego 內只寫 policy logic；K8s helper（label 取值、container loop、init container 排除）抽到 shared library Template；錯誤訊息要帶 input.review.object.metadata.name 幫 app team 定位是哪個 resource 被擋。

External Data Provider 的 production 治理：Provider 是獨立 service、Gatekeeper webhook 透過 HTTPS call、cache 在 Gatekeeper 內。要設 timeout（預設 3s、過時 ConstraintTemplate failurePolicy 決定 fail-open / fail-closed）、cache TTL、Provider 自身的 readiness / liveness。Provider down 不該擋全 cluster — 用 failurePolicy: Ignore 對 External Data Provider 例外、但記錄 metric alert。對應 XZ Backdoor 2024 的 SBOM attestation 查詢場景。

Gator CLI 在 CI 的 pipeline 設計：gator test 對 fixture 跑、gator verify 跑 Template 自帶 test suite、gator expand 預覽 Mutation 結果。PR 流程：Template change → gator verify 跑 unit test → kind cluster 起 Gatekeeper apply Template + sample violation manifest → confirm 擋下來才 merge。

跟 Styra DAS / Nirmata 整合：Gatekeeper OSS 本身沒 central management UI、多 cluster deployment 看 violation status 要自己拼。Styra DAS 是 OPA 商業 control plane、可以 push Template / Constraint 到多 cluster Gatekeeper、彙整 audit violation、做 policy impact analysis。Nirmata 走類似路線。OSS-only deployment 通常用 ArgoCD ApplicationSet + Prometheus exporter（gatekeeper-policy-manager / Open Policy Agent metrics）拼。

排錯與失敗快速判讀

• Gatekeeper webhook timeout / 擋全 cluster admission：Rego policy 寫了 expensive operation（大量 cross-resource lookup、External Data Provider call without cache）— webhook timeout 預設 3s、超過就走 failurePolicy；改寫 Rego 用 indexed lookup、External Data Provider 加 cache、failurePolicy: Ignore for non-critical Template
• 新 Template apply 後 admission 整個壞：Rego syntax / logic bug、production 才發現 — PR 必跑 gator verify + staging cluster 24-48hr soak、Constraint 先用 enforcementAction: dryrun 觀察 violation count 才切 deny
• Audit 跑很慢 / API server 壓力大：cluster resource 量大、Audit interval 預設 60s 太頻繁 — 拉長到 5-10min、auditFromCache: true 用 informer 不打 API server、大 cluster 開 auditChunkSize 分批處理
• legacy resource 不擋：admission webhook 只攔 create / update、kubectl apply 沒改動 spec 不觸發 — 用 Audit 抓 violation、配合手動 migration plan、不要期待 admission 自動修
• Mutation 跟 Validation 衝突：Mutation 加了 label、Validation 又擋說 label 不該存在 — Mutation 先跑、Validation 看 mutated 結果；設計 policy 時要對齊兩端、不能各自寫
• Sync 沒 declare、cross-resource policy 看不到對象：Rego data.inventory.namespace["foo"].v1.Pod 回 undefined — Config CRD 加 sync targets、確認 Gatekeeper pod restart 後 cache 載入
• External Data Provider down 擋全 cluster：Provider service 自己掛、failurePolicy: Fail 整個 admission 壞 — Provider 走 failurePolicy: Ignore + metric alert、Provider 自身 HA 部署、cache TTL 拉長

何時改走其他服務

不在本頁內的主題

• Rego 完整語法 reference（unification、comprehension、partial evaluation）
• Gatekeeper helm chart / installation 細節（看官方 docs）
• Open Policy Agent 在 service mesh / API gateway 的 sidecar 部署模式（看 OPA 頁）
• Pod Security Admission（K8s 內建、跟 Gatekeeper 互補但不是 Gatekeeper 一部分）
• Multi-cluster policy bundle 的 OCI registry 分發（屬 7.12 供應鏈完整性 邊界）

案例回寫

Gatekeeper 在 07 案例庫沒有直接 vendor-level 事件、但 supply chain 跟 admission policy 相關 case 都是 Gatekeeper 落實位置的對照：

下一步路由

• 上游：7.12 供應鏈完整性與 Artifact Trust、7.13 偵測覆蓋率與訊號治理
• 平行：OPA、Kyverno、Conftest
• 下游：Trivy（image scan 結果 feed External Data Provider）、SPIRE（workload identity 跟 admission policy 互補）
• 跨類：Splunk（admission violation event 進 SIEM correlation）
• 跨模組：8 事故處理 vendor 清單（policy violation → IR routing）
• 官方：OPA Gatekeeper Documentation

服務定位

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