awoooi/docs/security/K8S-ARGOCD-CHANGE-EVIDENCE-ACCEPTANCE.md

# K8s / ArgoCD GitOps 變更證據驗收只讀帳本

| 項目 | 內容 |
|------|------|
| 日期 | 2026-06-15 |
| 狀態 | `change_evidence_acceptance_ledger_ready_no_runtime_action` |
| 工具 | `scripts/security/k8s-argocd-change-evidence-acceptance.py` |
| Snapshot | `docs/security/k8s-argocd-change-evidence-acceptance.snapshot.json` |
| Source inventory | `docs/security/k8s-argocd-manifest-inventory.snapshot.json` |
| Source acceptance | `docs/security/k8s-argocd-owner-response-acceptance.snapshot.json` |
| runtime gate | `0` |

## 1. 目的

此帳本補在 K8s / ArgoCD manifest inventory、owner request draft 與 owner response acceptance 之後，專門驗收「GitOps 變更證據」是否足夠進入 reviewer acceptance。

它只處理 metadata-only evidence ref，不讀 live cluster、不呼叫 ArgoCD API、不執行 `kubectl`、不做 ArgoCD sync、不做 Helm upgrade、不套用 manifest、不讀 secret value，也不把 CD 成功、deploy marker、AwoooP approval 或 UI 可見狀態當成 runtime 授權。

## 2. 固定範圍

| 指標 | 數值 | 解讀 |
|------|------|------|
| `change_evidence_candidate_count` | `4` | 對應 `awoooi_prod`、`argocd`、`velero`、`monitoring` 四個 scan group |
| `c0_change_evidence_candidate_count` | `3` | production namespace、ArgoCD app、Velero 為 C0 |
| `write_capable_candidate_count` | `4` | 四組都可能影響 workload、NetworkPolicy、RBAC、backup / restore 或 apply-capable script |
| `source_manifest_file_count` | `49` | repo-only manifest / supporting source 數 |
| `source_yaml_manifest_file_count` | `45` | YAML manifest 數 |
| `deployment_object_count` | `5` | Deployment 物件數 |
| `cronjob_object_count` | `5` | CronJob 物件數 |
| `secret_object_count` | `6` | Secret metadata 物件數；不得收 value |
| `network_policy_object_count` | `6` | NetworkPolicy 物件數 |
| `rbac_object_count` | `5` | ServiceAccount / ClusterRole / ClusterRoleBinding 物件數 |
| `argocd_application_count` | `1` | ArgoCD Application 物件數 |
| `prometheus_rule_count` | `4` | PrometheusRule 物件數 |
| `required_evidence_field_count` | `18` | 變更證據必填欄位 |
| `reviewer_check_count` | `18` | reviewer 必檢規則 |
| `outcome_lane_count` | `8` | 收件結果分流 |
| `blocked_action_count` | `28` | 明確禁止動作 |

## 3. 必填變更證據欄位

1. `proposed_commit_ref`
2. `rendered_manifest_diff_ref`
3. `argocd_application_readback_ref`
4. `argocd_sync_revision_ref`
5. `health_before_ref`
6. `health_after_ref`
7. `rollout_status_ref`
8. `service_route_smoke_ref`
9. `metrics_alert_ref`
10. `secret_metadata_parity_ref`
11. `blast_radius`
12. `maintenance_window`
13. `rollback_revision`
14. `postcheck_owner`
15. `affected_scope`
16. `redacted_evidence_refs`
17. `reviewer_outcome`
18. `not_approval`

以上欄位都只能保存脫敏 ref、commit、artifact pointer、ticket 或 hash。不得貼 manifest payload、kubeconfig、Secret value、token、cookie、private key、完整 DSN、partial credential 或可還原的 credential derivative。

## 4. Reviewer checks

| Check | 用途 |
|------|------|
| `change_ref_present` | 確認有 proposed commit / PR / patch ref |
| `group_scope_matches_inventory` | 確認 affected scope 對回 manifest inventory group |
| `rendered_manifest_diff_ref_only` | 確認只收 rendered manifest diff ref |
| `argocd_readback_ref_shape` | 確認 ArgoCD app / sync revision / health readback 只保存 ref |
| `secret_value_absent` | 確認沒有 secret value 或 credential derivative |
| `network_policy_impact_called_out` | 涉及 NetworkPolicy / Service / Ingress / NodePort 時標出 route / port 影響 |
| `rbac_impact_called_out` | 涉及 RBAC / ServiceAccount 時標出權限影響 |
| `workload_rollout_plan_present` | 涉及 Deployment / CronJob / HPA / image 時有 rollout / rollback / smoke plan |
| `health_before_after_present` | 確認 health before / after evidence ref |
| `route_smoke_or_not_applicable` | 公開 / admin / API route 受影響時有 smoke ref |
| `metric_alert_postcheck_present` | 確認 metric / alert / event / log post-check ref |
| `blast_radius_present` | 標出 namespace、workload、route、port、secret metadata、backup / restore 影響範圍 |
| `maintenance_window_present` | future sync / apply / rollout 必須另有維護窗口 |
| `rollback_revision_present` | 必須有 rollback revision 或明確禁止窗口 |
| `postcheck_owner_present` | post-check owner 必須可追溯 |
| `no_runtime_action_claim` | 不得把 evidence、CD success 或 deploy marker 當 runtime approval |
| `counts_transition_safe` | 只有 reviewer record 可更新 received / accepted / rejected |
| `cross_project_sync_noted` | 影響 AwoooP、代理賞金協議、監控、公開 gateway 或外部產品時需跨專案同步 ref |

## 5. Outcome lanes

| Lane | 說明 |
|------|------|
| `waiting_change_evidence` | 尚未收到 GitOps 變更證據 |
| `quarantine_sensitive_payload` | 收到 manifest payload、kubeconfig、Secret value 或可還原 credential 時隔離 |
| `reject_unredacted_or_runtime_claim` | 出現未脫敏 payload、secret value 或把 evidence 誤當執行批准時拒收 |
| `request_supplement` | 缺 before / after、rollback、blast radius、post-check 或 route smoke 時補件 |
| `ready_for_reviewer_acceptance` | metadata 合格後進 reviewer acceptance |
| `ready_for_runtime_approval_package` | reviewer 接受後只能形成 runtime approval package |
| `waiting_maintenance_window` | future sync / rollout / rollback 仍需獨立維護窗口 |
| `waiting_runtime_gate` | change evidence accepted 後 runtime gate 仍等待獨立人工批准 |

## 6. 禁止動作

此帳本明確禁止 `argocd sync`、`argocd rollback`、`kubectl apply / patch / delete / rollout restart`、`helm upgrade`、`kustomize image set`、讀取 live cluster、寫入 live cluster、手動重啟 Pod、scale workload、改 NetworkPolicy、改 RBAC、改 Service type / NodePort / Ingress route、改 runtime ConfigMap、未經 owner 改 Secret metadata、restore backup、Velero restore、套用 PrometheusRule、開 runtime gate 或新增 action button。

## 7. 完成度與邊界

| 工作 | 完成度 | 邊界 |
|------|--------|------|
| K8s / ArgoCD change evidence acceptance artifact | `100%` | 只讀帳本與 snapshot 已建立 |
| K8s production GitOps 只讀治理成熟度 | `62% -> 64%` | 只代表變更證據驗收規則補齊，不代表 runtime 可執行 |
| change evidence received / accepted | `0%` | 尚未收到或接受任何變更證據 |
| runtime approval package | `0%` | 尚未形成 runtime approval package |
| active runtime gate | `0` | 不開 sync、apply、patch、restart、rollback 或 route smoke |

## 8. 下一步

1. 要求 owner 只提供脫敏 ref：proposed commit、rendered manifest diff、ArgoCD app / sync revision、health before / after、rollout、route smoke、metrics / alert、rollback 與 post-check evidence。
2. reviewer 只檢查 metadata 完整性與 no-secret-value，不保存 raw manifest payload。
3. 若未來要進 runtime approval package，必須另開維護窗口、rollback revision、跨專案同步與 production post-check gate。