📚 课程目录第2章运维清单设计原则

2. 运维清单设计原则：标准化、可追溯性、自动化校验与版本控制

运维清单（Operations Checklist）是连接发布决策与平台执行之间的契约。在K8s平台中，一份设计不良的清单会导致误操作、漏检或审批流阻塞。本章围绕四个核心原则展开：标准化、可追溯性、自动化校验与版本控制，确保清单本身具备与基础设施代码同等的严谨性。

2.1 标准化：消除环境与团队间的认知偏差

标准化的目标是让同一份清单在开发、测试、预发、生产环境产生一致的解读与执行结果。标准化包含三个层次：

层次	定义	K8s平台落地示例
术语标准化	统一命名空间、标签、注解的命名规则	`app.kubernetes.io/name`、`app.kubernetes.io/version` 强制使用
结构标准化	清单模板字段顺序、必填项、可选范围固定	Helm values 中 `image.repository` 必须位于 `image.tag` 之前
流程标准化	检查步骤的触发条件、执行顺序、失败处理一致	镜像扫描 → 资源配额校验 → 网络策略检查 → 审批

实践建议：在 Helm Chart 的 values.schema.json 中定义字段类型、枚举值与正则约束，从源头强制标准化。例如 environment 字段只允许 ["dev", "staging", "prod"]。

2.2 可追溯性：从检查项到决策证据链

可追溯性要求每个检查项的执行结果、执行人、执行时间、输入参数与输出日志都能被完整记录和回溯。在K8s发布流水线中，可追溯性通过以下机制实现：

审计日志绑定：每个检查步骤生成结构化日志，包含 check_id、pipeline_run_id、resource_version。
不可变快照：在审批前对 Helm Release 的当前 values 与 manifest 做 SHA256 快照，存储至对象存储或 etcd。
决策记录：审批人的操作（通过/拒绝/跳过）与理由必须写入不可篡改的审计数据库。

  关键指标：可追溯性覆盖率 = (已记录审计日志的检查项 / 总检查项) × 100%。目标值 ≥ 99.9%。

2.3 自动化校验：将人工判断转化为可编程断言

自动化校验是运维清单从“文档”进化为“可执行代码”的关键。每个检查项应映射为一个或多个可编程断言（Assertion），在流水线中自动执行并产生通过/失败结果。

2.3.1 校验类型与工具映射

校验类型	检查内容	推荐工具/方法
Schema 校验	values 结构、类型、枚举值	`helm lint` + `values.schema.json`
安全策略校验	容器特权模式、hostPath、网络策略	Kyverno / OPA Gatekeeper
资源配额校验	CPU/Memory request/limit 是否在范围内	kube-score / 自定义 admission webhook
镜像来源校验	镜像仓库白名单、签名验证	Cosign + Notary
依赖版本校验	Chart 依赖的版本约束是否满足	`helm dependency update` + 版本比较脚本

常见陷阱：自动化校验不应只做“存在性检查”。例如检查 securityContext 是否存在是不够的，必须断言 runAsNonRoot: true 且 capabilities.drop: ["ALL"]。

2.3.2 校验流水线示例（伪代码）

# pipeline/checklist-automation.sh
#!/bin/bash
set -euo pipefail

CHART_PATH="./charts/my-app"
VALUES_FILE="./values/prod.yaml"

echo "=== 1. Schema 校验 ==="
helm lint ${CHART_PATH} -f ${VALUES_FILE}

echo "=== 2. 安全策略校验 ==="
kyverno apply ${CHART_PATH}/templates/ --policy ./policies/ --values ${VALUES_FILE}

echo "=== 3. 资源配额校验 ==="
kube-score score ${CHART_PATH}/templates/*.yaml --output-format ci

echo "=== 4. 镜像签名校验 ==="
cosign verify --key k8s://my-ns/cosign-public-key \
  $(yq eval '.image.repository' ${VALUES_FILE}):$(yq eval '.image.tag' ${VALUES_FILE})

echo "=== 所有校验通过 ==="

2.4 版本控制策略：清单即代码

运维清单必须与 Helm Chart 代码库同源、同版本、同生命周期。版本控制策略包含以下要点：

同库存储：清单文件（如 checklist.yaml）与 Chart 代码放在同一个 Git 仓库的同一分支。
版本对齐：Chart 版本号 version: 1.2.3 对应清单版本 checklist-1.2.3，通过 Git Tag 关联。
变更审批：对清单文件的修改必须走 PR 流程，且需要安全审计员 + 平台管理员双重审批。
不可变发布：已发布的清单版本不允许修改，只能通过新版本覆盖。

  版本控制检查清单：
  清单文件是否与 Chart 在同一个 Git 仓库？
每次 Chart 版本更新是否强制更新清单版本？
清单的 Git Tag 是否与 Helm Release 版本一一对应？
是否有 CI 流水线检查清单版本与 Chart 版本的一致性？

2.5 四原则关系总结

四个原则并非独立存在，而是形成闭环：标准化为自动化校验提供可预测的输入结构；自动化校验产生可追溯的审计证据；可追溯性依赖版本控制来定位历史快照；版本控制反过来强制标准化变更流程。缺少任何一个环节，清单都会退化为静态文档。

原则	核心产出	失败后果
标准化	统一的清单模板与 schema	环境间检查结果不一致，误报漏报
可追溯性	审计日志 + 不可变快照	无法定位故障根因，合规审计失败
自动化校验	可编程断言 + CI 集成	人工漏检，发布风险不可控
版本控制	Git Tag + 同库存储	清单与 Chart 版本失配，回滚困难