ConfigMap 验证

Tekton Pruner 使用 ValidatingWebhook,在 ConfigMap 于集群中创建或更新之前确保其符合要求的规范。本文档介绍验证的工作方式以及必须满足的要求。

概述

pruner webhook 会验证 ConfigMap,以便:

  • 强制要求标签和命名约定
  • 防止应用无效配置
  • 阻止删除仍被命名空间配置依赖的全局配置,除非该配置由 Tekton Operator 管理(参见“删除保护”)
  • 在创建或更新命名空间级配置时,根据全局限制检查这些配置(参见“全局配置强制执行”)

验证工作原理

验证 webhook 会随 pruner 自动安装,并拦截 ConfigMap 的 CREATE、UPDATE 和 DELETE 操作。它只验证同时带有 app.kubernetes.io/part-of: tekton-pruner 和 pruner.tekton.dev/config-type 标签(global 或 namespace)的 ConfigMap,从而确保集群中的普通 ConfigMap 不受影响。

验证规则

1. 必需标签

在每个 pruner ConfigMap 上设置这些标签。 webhook 只验证带有这些标签的 ConfigMap;未带标签的命名空间 ConfigMap 仍会由 Pruner 应用,但不会经过任何验证:

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

验证检查(它们只能拒绝 webhook 所验证的 ConfigMap 的更新,因为不带这两个标签创建的 ConfigMap 不会发送到 webhook):

  • 两个标签都必须存在
  • 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

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

3. 命名要求

全局配置:

  • 名称:必须为 tekton-pruner-default-spec(固定值)
  • 命名空间:必须是由 TektonConfig spec.targetNamespace 设置的命名空间(默认为 tekton-pipelines)
  • 标签:pruner.tekton.dev/config-type: global

命名空间配置:

  • 名称:必须为 tekton-pruner-namespace-spec(固定值)
  • 命名空间:必须是用户命名空间;被 webhook 拒绝的命名空间请参见命名空间限制
  • 标签: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

4. 命名空间限制

会拒绝命名空间级配置的命名空间:tekton-pipelines、tekton-operator,以及名称以 kube- 或 openshift- 开头的所有命名空间。对于 kube-system、kube-public 和 kube-node-lease,不会调用 webhook;对于其他 tekton-* 命名空间,webhook 也不会进行检查,因此请自行避免将命名空间级配置放入这些命名空间。

错误示例:

admission webhook "validation.webhook.pruner.tekton.dev.namespace" denied the request: Invalid namespace for namespace-level config: namespace-level config cannot be created in tekton-operator namespace

5. 配置内容验证

webhook 会验证包括以下内容在内的配置数据:

  • 时间值:命名空间范围的 ttlSecondsAfterFinished 必须为非负值。pipelineRuns / taskRuns 条目中的 ttlSecondsAfterFinished 不会被检查,因此其中的负值也会被接受。
  • 历史记录限制:命名空间范围的 historyLimit、successfulHistoryLimit 和 failedHistoryLimit 必须为非负值,并会根据全局值进行检查(参见全局配置强制执行)。在 pipelineRuns / taskRuns 条目中,每个值都必须为非负值;只有选择器条目值的总和受到限制(参见特定 Pipeline 的限制),而 name 条目的历史记录限制不受限制。
  • 选择器和名称(仅限命名空间 ConfigMap):不会进行验证。webhook 接受任何 matchLabels / matchAnnotations 键,以及 pipelineRuns / taskRuns 条目中的任何 name,因此请自行检查这些内容。
  • 未知键:不会报告。webhook 和 Pruner 会忽略它们不了解的键,因此像 successfulHistoryLimt 这样的拼写错误键会被接受,并记录为 ConfigMap validation successful;它原本要设置的字段会保持未设置,其效果与省略该字段相同。
  • 命名空间 ConfigMap 中的 global-config 键:此时 webhook 只会将该键作为全局配置进行检查,而不会检查 ns-config;Pruner 从命名空间 ConfigMap 中只读取 ns-config。请勿将 global-config 键添加到命名空间 ConfigMap 中。

因此,试运行被接受或出现 ConfigMap validation successful 行,并不表示每个键都已被识别。

注意:选择器(带有 matchLabels / matchAnnotations 的 pipelineRuns / taskRuns 条目)仅适用于命名空间级 ConfigMap。在全局配置中,namespaces.<namespace> 下的选择器会被拒绝:pruner webhook 会拒绝该 ConfigMap,Tekton Operator webhook 也会拒绝 TektonConfig spec.tektonpruner.global-config 中的相同条目。

6. 删除保护

当命名空间级配置仍然存在时,webhook 会阻止删除全局配置,除非该全局配置归 TektonInstallerSet 所有,即由 Tekton Operator 管理:webhook 始终允许删除该 ConfigMap。对于命名空间配置,如果其名称为 tekton-pruner-namespace-spec,且所在命名空间符合命名空间限制中允许使用命名空间配置的条件,则允许删除该配置。

上述标签、名称和命名空间检查也会在 DELETE 请求上执行,并且先于这些规则执行。因此,在基于事件的 Pruner 启用时,如果某个 ConfigMap 同时带有两个必需标签和 pruner.tekton.dev/config-type: namespace,但名称不同,或位于 tekton-pipelines、tekton-operator 中,或位于名称以 kube- 或 openshift- 开头的命名空间中,webhook 会拒绝删除该 ConfigMap(kube-system、kube-public 和 kube-node-lease 除外,因为不会调用 webhook)。它还会拒绝删除位于 tekton-pipelines 中、同时带有两个必需标签和 pruner.tekton.dev/config-type: global、且名称不是 tekton-pruner-default-spec 的 ConfigMap,并拒绝移除这类 ConfigMap 的标签(参见更改 Pruner ConfigMap)。例如,当基于事件的 Pruner 被禁用时创建这些 ConfigMap,它们可能会继续存在。

7. 全局配置强制执行

创建或更新命名空间级配置时,webhook 会获取全局配置,并将命名空间范围的值与其根值进行比较(内联的 namespaces.<namespace> 条目仅用于限制选择器总和):

  • 将 ttlSecondsAfterFinished 与全局 ttlSecondsAfterFinished 进行比较;如果不存在,则与系统最大值 30 天进行比较。
  • 将 successfulHistoryLimit 与全局 successfulHistoryLimit 进行比较;如果不存在,则与全局 historyLimit 进行比较;如果仍不存在,则与系统最大值 100 进行比较。failedHistoryLimit 也会以相同方式根据失败字段进行检查。
  • 仅将 historyLimit 与全局 historyLimit 进行比较;如果不存在,则与 100 进行比较。全局 successfulHistoryLimit 或 failedHistoryLimit 不会对其进行限制,不过,当命名空间配置未设置特定限制时,命名空间的 historyLimit 会同时应用于两种状态。

这些最大值是内置常量,而不是可配置的键。

常见验证错误

以下两个标签错误仅会在你更改 webhook 要验证的 ConfigMap 的标签时出现。创建时缺少这两个标签,或使用其他 pruner.tekton.dev/config-type 值的 ConfigMap 不会发送到 webhook,而是未经检查直接存储(参见更改 Pruner ConfigMap)。

缺少标签错误

Invalid pruner ConfigMap labels: ConfigMap must have labels

解决方案:为 ConfigMap 添加必需标签:

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

配置类型错误

Invalid pruner ConfigMap labels: 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: ns-config: ttlSecondsAfterFinished (172800) cannot exceed global limit (86400)

解决方案:将命名空间值调低到全局限制以内,或请求管理员提高全局最大值。

删除被阻止错误

当 Tekton Operator 管理 Pruner 时不会出现此错误:operator 拥有全局配置(所有者 kind 为 TektonInstallerSet),webhook 始终允许删除该配置。若要更改全局值,请使用 TektonConfig,而不是删除 ConfigMap(参见更改 Pruner ConfigMap)。

没有该所有者的全局配置在命名空间配置存在时无法删除:

Cannot delete global config: 2 namespace config(s) still exist that depend on it in namespaces: [dev staging]. Delete namespace configs first.

解决方案:先删除消息中列出的命名空间配置。这些配置归相应命名空间所属的团队所有,因此请先与这些团队达成一致:

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 状态

这些命令需要读取集群范围 webhook 配置以及 tekton-pipelines 中 Pod 及其日志的权限,通常只有集群管理员具备这些权限。tekton-pipelines 是 TektonConfig spec.targetNamespace 的默认值;如果你的安装使用其他命名空间,请在本页的命令中将其替换为相应值。

# Check webhook configuration
kubectl get validatingwebhookconfigurations validation.webhook.pruner.tekton.dev

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

# View all webhook log lines (with -l and without --tail, kubectl prints only the last 10 lines)
kubectl logs -n tekton-pipelines -l app.kubernetes.io/part-of=tekton-pruner,app.kubernetes.io/component=webhook --tail=-1

测试验证

在新的测试命名空间中,使用 --dry-run=server 将无效的命名空间级 ConfigMap 发送到 API server。该 ConfigMap 带有两个必需标签,因此 webhook 会对其进行验证,并且试运行不会存储任何内容。命名空间名称会获得唯一后缀;其余命令仅在 kubectl create namespace 成功时运行,因此绝不会删除现有命名空间。创建和删除命名空间需要对集群范围的 namespaces 资源具有权限,通常只有集群管理员具备这些权限;命名空间所有者也可以在自己的命名空间中执行相同的试运行(最佳实践下的实践 3):

NS="pruner-validation-test-$(date +%s)"
if kubectl create namespace "$NS"; then
cat <<EOF | kubectl create --dry-run=server -f -
apiVersion: v1
kind: ConfigMap
metadata:
  name: tekton-pruner-namespace-spec
  namespace: ${NS}
  labels:
    app.kubernetes.io/part-of: tekton-pruner
    pruner.tekton.dev/config-type: namespace
data:
  ns-config: |
    ttlSecondsAfterFinished: -1
EOF
kubectl delete namespace "$NS"
fi

预期结果:请求会被 pruner validation webhook 拒绝,因为 ttlSecondsAfterFinished 为负值。kubectl 会在其自身的前缀之后输出 webhook 消息:

The request is invalid: error when creating "STDIN": admission webhook "validation.webhook.pruner.tekton.dev.namespace" denied the request: Invalid pruner configuration: ns-config: ttlSecondsAfterFinished cannot be negative, got -1

如果试运行报告 ConfigMap 已创建,则表示 webhook 未执行验证。最可能的原因是基于事件的 Pruner 已被禁用,这是 Operator 的默认设置(spec.tektonpruner.disabled: true 位于 TektonConfig 中):webhook 配置仅在 Pruner 启用期间存在,因此验证 Webhook 状态中的第一条命令会报告 NotFound。启用 Pruner 会立即删除 runs:在启用之前,请阅读命名空间配置中推荐设置的警告,并按照其中的步骤操作。启用 Pruner 的步骤位于Tekton Pruner 未部署。

更改 Pruner ConfigMap

Webhook 也会验证更新操作,因此会拒绝从其验证的 ConfigMap 中移除 app.kubernetes.io/part-of 标签:

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

对于未带有这两个标签而创建的命名空间 ConfigMap,Webhook 不会对其进行检查,即使它替换的是已删除且曾由 Webhook 验证过的 ConfigMap。Pruner 仍会应用此类 ConfigMap(请参阅必需标签)。

当 Tekton Operator 管理 Pruner 时,请在 spec.tektonpruner.global-config 下的 TektonConfig 中更改全局值。Operator 会更新 tekton-pruner-default-spec,Webhook 会根据新值检查之后创建或更新的命名空间配置。它不会重新检查现有的命名空间配置:如果某个命名空间配置的值高于已降低的全局值,则会保留该值,Pruner 会按原样应用它。使用 kubectl get configmaps -A --field-selector metadata.name=tekton-pruner-namespace-spec -o yaml 列出命名空间配置及其 ns-config 值,并自行降低这些值。新的全局值会立即应用于所有使用这些值的已完成 runs,但 tekton-pipelines、tekton-operator 以及名称以 kube- 或 openshift- 开头的命名空间除外;降低限制会立即删除 runs。先读取当前值:

kubectl get tektonconfig config -o jsonpath='{.spec.tektonpruner.global-config}'

例如,设置全局 historyLimit:

kubectl patch tektonconfig config --type merge \
  -p '{"spec":{"tektonpruner":{"global-config":{"historyLimit":200}}}}'

然后确认 Operator 已将新值写入 Pruner 的全局 ConfigMap;输出必须包含 historyLimit: 200:

kubectl get configmap tekton-pruner-default-spec -n tekton-pipelines -o jsonpath='{.data.global-config}'

这些步骤需要有权限修补集群范围的 TektonConfig,以及读取 tekton-pipelines 中 ConfigMap 的权限,通常只有集群管理员具备这些权限。

最佳实践

  1. 从一开始就始终包含必需标签
  2. 对全局配置和命名空间配置使用精确的命名约定
  3. 首先使用 server 试运行测试 ConfigMap,如上面的测试验证中所示。试运行报告 ConfigMap 已创建,只能说明没有任何内容拒绝它。要确认 Webhook 会检查命名空间中的 ConfigMap,请以相同方式向该命名空间发送一个副本,将其中 ns-config 顶层的 ttlSecondsAfterFinished 设置为 -1,替换任何现有值:它必须像测试验证中一样被拒绝;如果报告为已创建,则表示 Webhook 未检查它。命名空间所有者可以在自己的命名空间中创建 ConfigMap 之前执行此操作。集群管理员还可以查找实践 5 中的日志行
  4. 一次修复一个错误:Webhook 只报告第一个违规项,因此每次修复后都要重新运行试运行,直到通过
  5. 部署新配置时检查 Webhook 日志(命令及其所需权限请参阅验证 Webhook 状态):当 Webhook 检查 ConfigMap 的内容时,它会先记录 Validating pruner ConfigMap,然后记录 ConfigMap validation successful 或 ConfigMap validation failed,其中包含 ConfigMap 的名称和命名空间。每个检查过的请求都会写入多行日志,因此请使用带有 --tail=-1 的日志命令。如果覆盖更改时间的日志输出中缺少某个 ConfigMap 的这些行,则表示其内容未被检查;输出仅涵盖 Webhook 容器启动以来的时间。ConfigMap validation successful 行并不能表明每个键都已被识别(请参阅配置内容验证)
  6. 当 Tekton Operator 管理 Pruner 时,通过 TektonConfig 更改全局值,而不是删除 tekton-pruner-default-spec