Alauda DevOps Pipelines Docs
  • 简体中文

    • ConfigMap 校验

    Tekton Pruner 使用 ValidatingWebhook，确保 ConfigMap 在被创建或更新到集群之前满足所需规范。本文档说明校验的工作方式以及必须满足的要求。

    目录

    概述校验工作原理校验规则1. 必需标签2. 选择器限制3. 命名要求3. 命名空间限制4. 配置内容校验5. 删除保护6. 全局配置强制校验常见校验错误缺少标签错误配置类型错误名称错误超出全局限制错误删除被阻止错误故障排除验证 Webhook 状态测试校验绕过校验（不推荐）最佳实践

    概述

    pruner webhook 会对 ConfigMap 执行校验，以：

    • 强制要求必要的标签和命名规范
    • 防止无效配置被应用
    • 防止关键配置被意外删除
    • 确保命名空间级配置遵守全局边界

    校验工作原理

    校验 webhook 会随 pruner 自动安装，并拦截 ConfigMap 的 CREATE、UPDATE 和 DELETE 操作。它只会校验带有标签 app.kubernetes.io/part-of: tekton-pruner 的 ConfigMap，从而确保集群中的普通 ConfigMap 不受影响。

    校验规则

    1. 必需标签

    所有 pruner ConfigMap 都必须具有以下标签：

    metadata:
  labels:
    app.kubernetes.io/part-of: tekton-pruner
    pruner.tekton.dev/config-type: <global|namespace>

    校验检查：

    • 两个标签都必须存在
    • app.kubernetes.io/part-of 必须等于 tekton-pruner
    • pruner.tekton.dev/config-type 必须是 global 或 namespace

    错误示例：

    Invalid pruner ConfigMap labels: ConfigMap must have label app.kubernetes.io/part-of=tekton-pruner

    2. 选择器限制

    重要： 选择器（matchLabels/matchAnnotations）仅支持命名空间级 ConfigMap（tekton-pruner-namespace-spec），全局 ConfigMap 不支持。

    有效 - 命名空间 ConfigMap 中的选择器：

    apiVersion: v1
kind: ConfigMap
metadata:
  name: tekton-pruner-namespace-spec
  namespace: dev
  labels:
    app.kubernetes.io/part-of: tekton-pruner
    pruner.tekton.dev/config-type: namespace
data:
  ns-config: |
    pipelineRuns:
      - selector:                  # OK - This is a namespace ConfigMap
          - matchLabels:
              app: myapp
        ttlSecondsAfterFinished: 1800

    无效 - 全局 ConfigMap 中的选择器：

    apiVersion: v1
kind: ConfigMap
metadata:
  name: tekton-pruner-default-spec
  namespace: tekton-pipelines
  labels:
    app.kubernetes.io/part-of: tekton-pruner
    pruner.tekton.dev/config-type: global
data:
  global-config: |
    namespaces:
      dev:
        pipelineRuns:
          - selector:              # WILL FAIL VALIDATION
              - matchLabels:
                  app: myapp
        ttlSecondsAfterFinished: 1800

    错误示例：

    Invalid pruner configuration: global-config.namespaces.dev.pipelineRuns[0]: 
selectors are NOT supported in global ConfigMap. 
Use namespace-level ConfigMap (tekton-pruner-namespace-spec) instead

    为什么有这个限制？

    • 基于选择器的资源匹配需要在运行时访问资源的 labels/annotations
    • 全局 ConfigMap 设计用于集群范围的默认值，而不是按资源进行匹配
    • 命名空间 ConfigMap 为动态资源选择提供了正确的作用域

    另请参阅： 资源组 了解选择器使用示例

    3. 命名要求

    全局配置：

    • 名称： 必须为 tekton-pruner-default-spec（固定）
    • 命名空间： 必须为 tekton-pipelines（或系统命名空间）
    • 标签： pruner.tekton.dev/config-type: global

    命名空间配置：

    • 名称： 必须为 tekton-pruner-namespace-spec（固定）
    • 命名空间： 必须位于用户命名空间中（不能在系统或 tekton 命名空间中）
    • 标签： pruner.tekton.dev/config-type: namespace

    错误示例：

    Global config must be named 'tekton-pruner-default-spec', got: my-custom-name
    Namespace config must be named 'tekton-pruner-namespace-spec', got: pruner-config

    3. 命名空间限制

    命名空间级配置禁止使用的命名空间：

    • 系统命名空间：kube-*
    • Tekton 命名空间：tekton-pipelines、tekton-*

    尝试在这些位置创建命名空间级配置将被拒绝。

    错误示例：

    Invalid pruner ConfigMap configuration: wrong config-type label or namespace combination

    4. 配置内容校验

    webhook 会校验以下配置数据：

    • 时间值：ttlSecondsAfterFinished 必须为非负数
    • 历史限制：historyLimit、successfulHistoryLimit 和 failedHistoryLimit 必须为非负数；如果启用了全局上限，则不能超过全局上限
    • 选择器（仅命名空间 ConfigMap）：标签和注解选择器必须包含有效的键值对；名称选择器必须是有效的资源名称

    注意： 选择器（pipelineRuns、taskRuns 数组中包含 matchLabels/matchAnnotations 的配置）仅在命名空间级 ConfigMap 中处理；在全局 ConfigMap 中会被忽略。

    5. 删除保护

    如果仍然存在命名空间级配置，webhook 会阻止删除全局配置。你必须先删除所有命名空间配置，然后才能删除全局配置。命名空间配置可以不受限制地删除。

    6. 全局配置强制校验

    在创建或更新命名空间级配置时，webhook 会获取全局配置并校验命名空间值是否未超过全局上限（如果已定义），例如 maxTTLSecondsAfterFinished、maxHistoryLimit。

    常见校验错误

    缺少标签错误

    ConfigMap must have labels

    解决方案： 为你的 ConfigMap 添加所需标签：

    labels:
  app.kubernetes.io/part-of: tekton-pruner
  pruner.tekton.dev/config-type: global  # or namespace

    配置类型错误

    label pruner.tekton.dev/config-type must be 'global' or 'namespace', got: local

    解决方案： 仅使用 global 或 namespace 作为 config-type 值。

    名称错误

    Global config must be named 'tekton-pruner-default-spec', got: tekton-pruner-config

    解决方案： 使用完全正确的名称：

    • 全局：tekton-pruner-default-spec
    • 命名空间：tekton-pruner-namespace-spec

    超出全局限制错误

    Invalid pruner configuration: namespace config ttlSecondsAfterFinished (172800) exceeds global maximum (86400)

    解决方案： 将命名空间值降低到全局限制以内，或请求管理员提高全局上限。

    删除被阻止错误

    Cannot delete global config: 2 namespace config(s) still exist

    解决方案： 先删除所有命名空间配置：

    kubectl delete cm tekton-pruner-namespace-spec -n dev
kubectl delete cm tekton-pruner-namespace-spec -n staging
# Then delete global config
kubectl delete cm tekton-pruner-default-spec -n tekton-pipelines

    故障排除

    验证 Webhook 状态

    # Check webhook configuration
kubectl get validatingwebhookconfigurations tekton-pruner-validating-webhook

# Check webhook pod and service
kubectl get pods,svc -n tekton-pipelines -l app.kubernetes.io/component=webhook

# View webhook logs
kubectl logs -n tekton-pipelines -l app.kubernetes.io/component=webhook

    测试校验

    创建一个无效的 ConfigMap 以验证 webhook 是否正常工作：

    cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
  name: tekton-pruner-default-spec
  namespace: tekton-pipelines
data:
  global-config: |
    ttlSecondsAfterFinished: 300
EOF

    预期错误：admission webhook denied the request: Invalid pruner ConfigMap labels

    绕过校验（不推荐）

    警告： 绕过校验可能导致 pruner 行为配置错误，仅应在紧急情况下使用。

    要临时绕过校验：

    1. 删除标识标签：

      kubectl label cm tekton-pruner-default-spec -n tekton-pipelines \
  app.kubernetes.io/part-of-

    2. 进行必要更改

    3. 重新添加标签：

      kubectl label cm tekton-pruner-default-spec -n tekton-pipelines \
  app.kubernetes.io/part-of=tekton-pruner

    注意： 如果 ConfigMap 没有正确的标签，pruner controller 将不会处理它。

    最佳实践

    1. 从一开始就始终包含所需标签
    2. 为全局和命名空间配置使用完全正确的命名规范
    3. 先在非生产命名空间中测试配置
    4. 仔细检查校验错误——它们会指明需要修复的内容
    5. 在发布新配置时监控 webhook 日志
    6. 在尝试删除全局配置之前先删除命名空间配置