4. 版本漂移检测工具：检测原理与选型对比

存储版本漂移的检测不能依赖人工巡检，必须通过自动化工具在 CI/CD 管线或集群准入阶段拦截。本章深入分析四种主流检测工具的核心原理、适用场景与局限，帮助团队根据自身技术栈选择最合适的检测方案。

4.1 检测工具全景对比

4.2 kubectl convert：API 版本转换的底层逻辑

kubectl convert 是 Kubernetes 内置的版本转换工具，其核心原理是调用 API Server 的 内部版本转换器（Internal Version Converter）。当执行 kubectl convert -f old.yaml --output-version=apps/v1 时，工具将 YAML 发送给 API Server，Server 先反序列化为内部版本（internal version），再序列化为目标版本输出。

# 检测存储类（StorageClass）是否使用了弃用的 API 版本
kubectl convert -f storageclass-old.yaml --output-version=storage.k8s.io/v1

# 对比原始文件与转换后文件的差异
diff <(kubectl convert -f storageclass-old.yaml --output-version=storage.k8s.io/v1 -o yaml) storageclass-old.yaml

4.3 kube-score：静态规则引擎的字段级检测

kube-score 是一个静态 YAML 分析工具，内置 40+ 条检查规则，覆盖 API 版本弃用、字段废弃、安全上下文缺失 等场景。其检测原理是：将 YAML 解析为 Go 结构体，然后逐条匹配规则函数，输出分数与建议。

# 安装
curl -L https://github.com/zegl/kube-score/releases/latest/download/kube-score_linux_amd64 -o kube-score
chmod +x kube-score

# 对存储相关资源进行评分
kube-score score storageclass.yaml pvc.yaml pv.yaml

# 输出示例（版本漂移相关）
[CRITICAL] storageclass.yaml: StorageClass API version "storage.k8s.io/v1beta1" is deprecated
    - Use "storage.k8s.io/v1" instead
[WARNING] pvc.yaml: PersistentVolumeClaim uses "volume.beta.kubernetes.io/storage-class" annotation
    - Use "spec.storageClassName" field instead

kube-score:
  stage: test
  script:
    - kube-score score manifests/*.yaml --exit-one-on-warning
  only:
    - merge_requests

4.4 Polaris：运行时审计与多集群版本一致性

Polaris 提供两种运行模式：Dashboard 模式（持续审计集群）和 CLI 模式（静态分析）。其检测原理是：通过 Kubernetes API 实时获取集群中所有资源的实际版本，与内置的版本弃用时间表进行比对，生成合规报告。

# CLI 模式：分析当前 kubeconfig 指向的集群
polaris audit --audit-path cluster

# 输出 JSON 格式报告
polaris audit --audit-path cluster --format json | jq '.results[] | select(.category=="版本漂移")'

# Dashboard 模式：部署到集群
kubectl apply -f https://raw.githubusercontent.com/FairwindsOps/polaris/master/deploy/dashboard.yaml

Polaris 的版本漂移检测规则示例（内置 version-deprecation 检查器）：

# 自定义规则：检查 StorageClass 是否使用 v1beta1
checks:
  version-deprecation:
    storage.k8s.io/v1beta1:
      severity: error
      message: "StorageClass v1beta1 已弃用，请迁移至 v1"

4.5 自定义准入控制器：生产级强制拦截

自定义准入控制器（Admission Webhook）是 Kubernetes 原生扩展点，在资源持久化到 etcd 之前拦截请求。其检测原理分为三步：

1. 注册 Webhook： 在集群中部署 ValidatingWebhookConfiguration，指定需要拦截的资源类型（如 storage.k8s.io/v1/StorageClass）和操作（CREATE/UPDATE）。
2. 请求转发： API Server 将 AdmissionReview 请求（包含资源对象的原始 YAML）发送到 Webhook 服务。
3. 规则判定： Webhook 服务解析资源版本，与内置的版本兼容性表比对，返回 allowed: true/false 及拒绝原因。

# ValidatingWebhookConfiguration 示例（拦截 StorageClass 创建）
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: storage-version-validator
webhooks:
- name: storage-version.finops.io
  rules:
  - apiGroups:   ["storage.k8s.io"]
    apiVersions: ["v1", "v1beta1"]
    operations:  ["CREATE", "UPDATE"]
    resources:   ["storageclasses"]
  clientConfig:
    service:
      name: version-validator-svc
      namespace: kube-system
      path: /validate
    caBundle: <base64-encoded-ca-cert>
  admissionReviewVersions: ["v1"]
  failurePolicy: Fail

func validateStorageClass(ar admissionv1.AdmissionReview) *admissionv1.AdmissionResponse {
    raw := ar.Request.Object.Raw
    // 解析 API 版本
    gvk, _ := schema.ParseGroupVersion(string(raw))
    // 版本弃用表
    deprecatedVersions := map[string]string{
        "storage.k8s.io/v1beta1": "storage.k8s.io/v1",
    }
    if target, ok := deprecatedVersions[gvk.String()]; ok {
        return &admissionv1.AdmissionResponse{
            Allowed: false,
            Result: &metav1.Status{
                Message: fmt.Sprintf("版本 %s 已弃用，请使用 %s", gvk, target),
            },
        }
    }
    return &admissionv1.AdmissionResponse{Allowed: true}
}

4.6 检测原理对比 SVG：四种工具的检测链路

4.7 多工具协同策略

在实际生产环境中，单一工具无法覆盖所有版本漂移场景。推荐采用 分层检测架构：

• 第一层（开发阶段）： 开发者本地使用 kube-score 进行 pre-commit 检查，拦截明显的版本弃用问题。
• 第二层（CI 阶段）： 流水线中集成 kubectl convert 做 API 版本兼容性验证，确保 YAML 可被目标集群接受。
• 第三层（集群准入）： 部署自定义准入控制器，对所有写入 etcd 的资源进行强制版本校验。
• 第四层（持续审计）： 使用 Polaris 定期扫描集群，发现运行时版本漂移和配置漂移。

# 团队 A（基础设施团队）：维护准入控制器规则
# 团队 B（应用团队）：在 CI 中集成 kube-score
# 团队 C（SRE 团队）：通过 Polaris Dashboard 监控全局版本合规率

# 版本漂移检测流水线示例（GitHub Actions）
name: Version Drift Detection
on: [pull_request]
jobs:
  detect:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: kube-score check
        run: kube-score score manifests/*.yaml --exit-one-on-warning
      - name: kubectl convert check
        run: |
          for f in manifests/*.yaml; do
            kubectl convert -f "$f" --output-version=apps/v1 -o yaml > /dev/null
          done

4.8 工具选型决策矩阵