ConfigMap 验证
Tekton Pruner 使用 ValidatingWebhook,在 ConfigMap 于集群中创建或更新之前确保其符合要求的规范。本文档介绍验证的工作方式以及必须满足的要求。
目录
概述验证工作原理验证规则1. 必需标签2. 选择器限制3. 命名要求4. 命名空间限制5. 配置内容验证6. 删除保护7. 全局配置强制执行常见验证错误缺少标签错误配置类型错误名称错误超出全局限制错误删除被阻止错误故障排除验证 Webhook 状态测试验证更改 Pruner 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 应用,但不会经过任何验证:
验证检查(它们只能拒绝 webhook 所验证的 ConfigMap 的更新,因为不带这两个标签创建的 ConfigMap 不会发送到 webhook):
- 两个标签都必须存在
app.kubernetes.io/part-of必须等于tekton-prunerpruner.tekton.dev/config-type必须是global或namespace
错误示例:
2. 选择器限制
重要:选择器(matchLabels/matchAnnotations)仅支持用于命名空间级 ConfigMap(tekton-pruner-namespace-spec),不支持用于全局 ConfigMap。
有效示例——命名空间 ConfigMap 中的选择器:
无效示例——全局 ConfigMap 中的选择器:
错误示例:
另请参阅:资源组,了解选择器使用示例
3. 命名要求
全局配置:
- 名称:必须为
tekton-pruner-default-spec(固定值) - 命名空间:必须是由
TektonConfigspec.targetNamespace设置的命名空间(默认为tekton-pipelines) - 标签:
pruner.tekton.dev/config-type: global
命名空间配置:
- 名称:必须为
tekton-pruner-namespace-spec(固定值) - 命名空间:必须是用户命名空间;被 webhook 拒绝的命名空间请参见命名空间限制
- 标签:
pruner.tekton.dev/config-type: namespace
错误示例:
4. 命名空间限制
会拒绝命名空间级配置的命名空间:tekton-pipelines、tekton-operator,以及名称以 kube- 或 openshift- 开头的所有命名空间。对于 kube-system、kube-public 和 kube-node-lease,不会调用 webhook;对于其他 tekton-* 命名空间,webhook 也不会进行检查,因此请自行避免将命名空间级配置放入这些命名空间。
错误示例:
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)。
缺少标签错误
解决方案:为 ConfigMap 添加必需标签:
配置类型错误
解决方案:仅使用 global 或 namespace 作为 config-type 值。
名称错误
解决方案:使用准确的必需名称:
- 全局:
tekton-pruner-default-spec - 命名空间:
tekton-pruner-namespace-spec
超出全局限制错误
解决方案:将命名空间值调低到全局限制以内,或请求管理员提高全局最大值。
删除被阻止错误
当 Tekton Operator 管理 Pruner 时不会出现此错误:operator 拥有全局配置(所有者 kind 为 TektonInstallerSet),webhook 始终允许删除该配置。若要更改全局值,请使用 TektonConfig,而不是删除 ConfigMap(参见更改 Pruner ConfigMap)。
没有该所有者的全局配置在命名空间配置存在时无法删除:
解决方案:先删除消息中列出的命名空间配置。这些配置归相应命名空间所属的团队所有,因此请先与这些团队达成一致:
故障排除
验证 Webhook 状态
这些命令需要读取集群范围 webhook 配置以及 tekton-pipelines 中 Pod 及其日志的权限,通常只有集群管理员具备这些权限。tekton-pipelines 是 TektonConfig spec.targetNamespace 的默认值;如果你的安装使用其他命名空间,请在本页的命令中将其替换为相应值。
测试验证
在新的测试命名空间中,使用 --dry-run=server 将无效的命名空间级 ConfigMap 发送到 API server。该 ConfigMap 带有两个必需标签,因此 webhook 会对其进行验证,并且试运行不会存储任何内容。命名空间名称会获得唯一后缀;其余命令仅在 kubectl create namespace 成功时运行,因此绝不会删除现有命名空间。创建和删除命名空间需要对集群范围的 namespaces 资源具有权限,通常只有集群管理员具备这些权限;命名空间所有者也可以在自己的命名空间中执行相同的试运行(最佳实践下的实践 3):
预期结果:请求会被 pruner validation webhook 拒绝,因为 ttlSecondsAfterFinished 为负值。kubectl 会在其自身的前缀之后输出 webhook 消息:
如果试运行报告 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 标签:
对于未带有这两个标签而创建的命名空间 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。先读取当前值:
例如,设置全局 historyLimit:
然后确认 Operator 已将新值写入 Pruner 的全局 ConfigMap;输出必须包含 historyLimit: 200:
这些步骤需要有权限修补集群范围的 TektonConfig,以及读取 tekton-pipelines 中 ConfigMap 的权限,通常只有集群管理员具备这些权限。
最佳实践
- 从一开始就始终包含必需标签
- 对全局配置和命名空间配置使用精确的命名约定
- 首先使用 server 试运行测试 ConfigMap,如上面的测试验证中所示。试运行报告 ConfigMap 已创建,只能说明没有任何内容拒绝它。要确认 Webhook 会检查命名空间中的 ConfigMap,请以相同方式向该命名空间发送一个副本,将其中
ns-config顶层的ttlSecondsAfterFinished设置为-1,替换任何现有值:它必须像测试验证中一样被拒绝;如果报告为已创建,则表示 Webhook 未检查它。命名空间所有者可以在自己的命名空间中创建 ConfigMap 之前执行此操作。集群管理员还可以查找实践 5 中的日志行 - 一次修复一个错误:Webhook 只报告第一个违规项,因此每次修复后都要重新运行试运行,直到通过
- 部署新配置时检查 Webhook 日志(命令及其所需权限请参阅验证 Webhook 状态):当 Webhook 检查 ConfigMap 的内容时,它会先记录
Validating pruner ConfigMap,然后记录ConfigMap validation successful或ConfigMap validation failed,其中包含 ConfigMap 的名称和命名空间。每个检查过的请求都会写入多行日志,因此请使用带有--tail=-1的日志命令。如果覆盖更改时间的日志输出中缺少某个 ConfigMap 的这些行,则表示其内容未被检查;输出仅涵盖 Webhook 容器启动以来的时间。ConfigMap validation successful行并不能表明每个键都已被识别(请参阅配置内容验证) - 当 Tekton Operator 管理 Pruner 时,通过
TektonConfig更改全局值,而不是删除tekton-pruner-default-spec