命名空间配置

根据环境特定的保留需求,为每个命名空间配置不同的清理策略。

配置层级

设置流向:全局 → 命名空间 → 资源组

在全局配置中设置 enforcedConfigLevel: namespace,以启用命名空间级覆盖。如果 global-config 的 namespaces.<namespace> 条目设置了适用于某个命名空间的层级,则使用其中的 enforcedConfigLevel;否则使用 global-config 的根级 enforcedConfigLevel。global 是 Operator 的默认值,当 TektonConfig 没有 global-config 时,Operator 会写入该默认值;没有 enforcedConfigLevel 的 global-config 会使 Pruner 回退到 resource。当适用于其命名空间的层级为 namespace 时,命名空间 ConfigMap 才会生效;在其他所有层级,Pruner 都会忽略它,尽管 webhook 会接受它。

验证边界

WARNING

严重 - 系统边界:仅在运行 PipelineRuns/TaskRuns 的用户命名空间中创建命名空间级 ConfigMap。

不要在系统命名空间中创建它们。验证 webhook 会在 tekton-pipelines、tekton-operator 以及名称以 kube- 或 openshift- 开头的所有命名空间中拒绝它们。对于 kube-system、kube-public 和 kube-node-lease,不会调用该 webhook;它也不会检查其他 tekton-* 命名空间,因此请自行确保不要在这些命名空间中创建它们。

所有配置的标签:

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

webhook 仅验证带有这两个标签的 ConfigMap。未加标签的命名空间 ConfigMap 仍会由 Pruner 应用,但不会经过任何验证,因此请始终设置这两个标签。

WARNING

命名空间级 ConfigMap 不属于 TektonConfig 生命周期。如果之后需要备份或恢复 Tekton 配置,请单独保存这些 ConfigMap。

WARNING

启用 Pruner 会立即删除运行记录。 本页中的 TektonConfig 示例作用于整个集群。Pruner controller 启动后会立即将限制应用于除 tekton-pipelines、tekton-operator 以及名称以 kube- 或 openshift- 开头的命名空间之外的每个命名空间中的已完成 PipelineRuns 和 TaskRuns;此后每次全局配置发生更改时,也会再次将限制应用于这些命名空间中的已完成 PipelineRuns 和 TaskRuns;之后完成的运行记录会在每个命名空间中进行检查,包括这些被排除的命名空间。其他团队的运行记录也包括在内。已删除的运行记录及其日志无法恢复;只有 Tekton Results 在删除前存储的副本仍可在 Results 中读取。使用 enforcedConfigLevel: namespace 时,所有现有的 tekton-pruner-namespace-spec ConfigMap 会同时生效,但 namespaces.<namespace> 条目设置了其他 enforcedConfigLevel 的命名空间除外。

应用示例之前,请按照推荐设置中的步骤操作:统计运行记录数量,与各团队达成一致,列出现有的命名空间 ConfigMap,并从宽松的值开始。

请使用 kubectl patch tektonconfig config --type merge --patch-file <file> 将示例合并到现有的 TektonConfig 中,而不要使用 kubectl apply -f:kubectl apply 会将文件存储在 kubectl.kubernetes.io/last-applied-configuration 注解中,而后续对另一个部分文件执行 kubectl apply -f 时,会删除先前文件设置但后续文件未包含的字段。

方法 1:内联命名空间规范(集中式)

在 TektonConfig 中定义所有命名空间配置:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pruner:
    disabled: true  # Must disable job-based pruner
  tektonpruner:
    disabled: false  # Enable event-based pruner
    global-config:
      enforcedConfigLevel: namespace
      ttlSecondsAfterFinished: 604800  # Global default and upper bound for the namespaces below
      namespaces:
        dev:
          ttlSecondsAfterFinished: 300
          successfulHistoryLimit: 3
        staging:
          ttlSecondsAfterFinished: 86400
          successfulHistoryLimit: 5
        prod:
          ttlSecondsAfterFinished: 604800
          successfulHistoryLimit: 10

内联的 namespaces 条目会按照与每个命名空间 ConfigMap 相同的规则,根据根级别的 global-config 值进行检查,而不受 enforcedConfigLevel 影响。请参阅验证规则。使用 enforcedConfigLevel: global 时,这些条目会被接受但忽略:Pruner 会将根级别的值应用于每个命名空间,但某个命名空间的条目自行设置了其他 enforcedConfigLevel 时除外。

要确认方法 1,请执行方法 2 中的 TektonConfig 读取操作(“检查 ConfigMap 是否生效”):它必须输出 false namespace。然后,使用特定于 Pipeline 的 TTL中的命令,读取 dev 中某个运行记录的 pruner.tekton.dev/ttlSecondsAfterFinished 注解;该运行记录必须是在更改后启动并已完成的:当 dev 没有设置 TTL 的命名空间 ConfigMap 时,它必须显示 300。请在运行记录完成后的 300 秒内读取;随后 Pruner 会删除该运行记录,之后读取将返回 NotFound。

方法 2:每个命名空间的 ConfigMap(自助服务)

推荐用于命名空间隔离和团队自治。

步骤 1:在 TektonConfig 中启用命名空间级配置。此操作需要修补集群范围的 TektonConfig 的权限,通常由集群管理员执行:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pruner:
    disabled: true  # Must disable job-based pruner
  tektonpruner:
    disabled: false  # Enable event-based pruner
    global-config:
      enforcedConfigLevel: namespace
      ttlSecondsAfterFinished: 3600  # Default for namespaces whose ConfigMap does not set a TTL, or that have no ConfigMap; a namespace with an inline namespaces.<namespace> entry uses that entry instead (see Inline Entries Replace Global Values)

步骤 2:命名空间所有者创建特定于命名空间的 ConfigMap(固定名称:tekton-pruner-namespace-spec)。此操作需要在该命名空间中创建 ConfigMap 的权限:

apiVersion: v1
kind: ConfigMap
metadata:
  name: tekton-pruner-namespace-spec  # Fixed name
  namespace: my-app  # User namespace only
  labels:
    app.kubernetes.io/part-of: tekton-pruner
    pruner.tekton.dev/config-type: namespace
data:
  ns-config: |
    ttlSecondsAfterFinished: 300
    successfulHistoryLimit: 5
    failedHistoryLimit: 10

检查 ConfigMap 是否生效。每个经过身份验证的用户都可以读取 TektonConfig,因此命名空间所有者可以检查步骤 1:

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

仅当此命令输出 false namespace 时,Pruner 才会应用命名空间 ConfigMap;使用 Operator 默认值时,它会输出 true global。如果命名空间有 global-config,其中 namespaces.<namespace> 条目内的 enforcedConfigLevel 会替换该命名空间的第二个值。命名空间中的运行记录完成后,其 pruner.tekton.dev/ttlSecondsAfterFinished 注解会显示 Pruner 为其选择的 TTL,此处为 300(命令见特定于 Pipeline 的 TTL)。请在运行记录完成后的 300 秒内读取;此后 Pruner 会删除该运行记录。历史记录限制不会在运行记录上留下此类值(请参阅特定于 Pipeline 的限制)。

优点:

  • 命名空间所有者可自助管理
  • 独立的生命周期管理
  • 优先于全局配置

验证规则

命名空间配置会根据限制进行验证,以防止资源耗尽。

1. 显式全局限制

当全局配置定义了限制时,webhook 会逐字段将命名空间配置的命名空间级值与其进行检查:

  • 将 ttlSecondsAfterFinished 与全局 ttlSecondsAfterFinished 进行比较。
  • 将 successfulHistoryLimit 和 failedHistoryLimit 与同名字段的全局值进行比较;如果全局配置未设置该字段,则与全局 historyLimit 进行比较。
  • 仅将 historyLimit 与全局 historyLimit 进行比较。

当命名空间配置未设置 successfulHistoryLimit / failedHistoryLimit 时,命名空间的 historyLimit 会同时应用于这两种状态。因此,仅设置 historyLimit 的命名空间配置不会受到单独设置的全局 successfulHistoryLimit 或 failedHistoryLimit 的限制;请同时设置全局 historyLimit(请参阅推荐设置)。

在 pipelineRuns / taskRuns 条目中,仅会限制选择器条目的历史记录限制之和(请参阅特定于 Pipeline 的限制)。不会检查条目中的 ttlSecondsAfterFinished(请参阅配置内容验证)。

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pruner:
    disabled: true  # Must disable job-based pruner
  tektonpruner:
    disabled: false  # Enable event-based pruner
    global-config:
      ttlSecondsAfterFinished: 3600
      successfulHistoryLimit: 10
      namespaces:
        development:
          ttlSecondsAfterFinished: 7200   # Invalid: exceeds global limit
          successfulHistoryLimit: 5       # Valid: within global limit

2. 系统默认限制

未定义全局限制时,系统会强制执行以下最大值:

配置字段系统最大值
ttlSecondsAfterFinished2,592,000 秒(30 天)
successfulHistoryLimit100
failedHistoryLimit100
historyLimit100

示例:

spec:
  tektonpruner:
    global-config:
      enforcedConfigLevel: namespace
      # No ttlSecondsAfterFinished defined - the system maximum applies to the TTL
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: tekton-pruner-namespace-spec
  namespace: my-app
  labels:
    app.kubernetes.io/part-of: tekton-pruner
    pruner.tekton.dev/config-type: namespace
data:
  ns-config: |
    ttlSecondsAfterFinished: 2592001   # Invalid: exceeds system maximum
    successfulHistoryLimit: 150        # Invalid: exceeds the global historyLimit (Operator default 100)

3. 覆盖默认值

集群管理员可以通过全局配置设置更严格的限制。全局值会替代系统最大值,成为与其进行检查的命名空间级值的上限(请参阅上文的“显式全局限制”),并参与选择器之和的限制(请参阅特定于 Pipeline 的限制)。它不会限制 pipelineRuns / taskRuns 条目中的 ttlSecondsAfterFinished。系统不会根据系统最大值检查全局值本身。

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pruner:
    disabled: true  # Must disable job-based pruner
  tektonpruner:
    disabled: false  # Enable event-based pruner
    global-config:
      ttlSecondsAfterFinished: 86400     # Admin limit: 1 day
      successfulHistoryLimit: 20         # Admin limit for a namespace successfulHistoryLimit
      failedHistoryLimit: 20             # Admin limit for a namespace failedHistoryLimit
      historyLimit: 20                   # Admin limit for a namespace historyLimit (otherwise the default 100 stays)
      namespaces:
        development:
          ttlSecondsAfterFinished: 3600   # Valid: within global limit
        # ttlSecondsAfterFinished: 172800 # Invalid example: exceeds global limit

根级值不仅是限制,运行记录也会使用这些值。在 enforcedConfigLevel: global 下(即 Operator 默认值;此示例未设置级别),每个命名空间最多保留 20 条成功运行记录和 20 条失败运行记录,并且每条运行记录会在完成一天后删除。在 namespace 下,对于没有内联条目且其命名空间 ConfigMap 未设置这些字段的每个命名空间,同样适用上述规则。请同时设置 failedHistoryLimit 和 historyLimit:如果不设置,根级 historyLimit 也会成为这些命名空间的失败运行记录限制。

内联条目替代全局值

内联 namespaces.<namespace> 条目会替代该命名空间的根级 global-config 值。条目中未设置的字段不会从根级继承;如果要为该命名空间保留根级值,请在条目中重复设置:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pruner:
    disabled: true  # Must disable job-based pruner
  tektonpruner:
    disabled: false  # Enable event-based pruner
    global-config:
      enforcedConfigLevel: namespace
      ttlSecondsAfterFinished: 3600     # Global default
      successfulHistoryLimit: 5          # Global default
      namespaces:
        dev:
          ttlSecondsAfterFinished: 300   # Override TTL
          # successfulHistoryLimit is not set here, so the root value 5 does not apply to dev

选择器支持

重要:资源选择器(matchLabels、matchAnnotations)仅适用于命名空间级 ConfigMap(tekton-pruner-namespace-spec),不适用于全局 ConfigMap 的内联命名空间规格。

以下配置有效(命名空间 ConfigMap):

apiVersion: v1
kind: ConfigMap
metadata:
  name: tekton-pruner-namespace-spec
  namespace: my-app
  labels:
    app.kubernetes.io/part-of: tekton-pruner
    pruner.tekton.dev/config-type: namespace
data:
  ns-config: |
    pipelineRuns:
      - selector:
          - matchLabels:
              critical: "true"
        ttlSecondsAfterFinished: 2592000

要确认条目是否生效,请读取在创建 ConfigMap 后启动且已完成的 critical: "true" 运行记录的 pruner.tekton.dev/ttlSecondsAfterFinished 注解:其中必须显示 2592000。不会报错的命令以及导致出现其他值的原因,请参阅特定于 Pipeline 的 TTL。

selector 是一个列表:每个项目包含 matchLabels 和/或 matchAnnotations。如果将其写成单个映射,ConfigMap 将被拒绝,并显示 cannot unmarshal object into Go struct field ResourceSpec.pipelineRuns.selector of type []config.SelectorSpec。

以下配置会被拒绝(全局配置中的内联命名空间):Tekton Operator webhook 会拒绝 spec.tektonpruner.global-config.namespaces.<namespace> 下的 selector:

spec:
  tektonpruner:
    global-config:
      namespaces:
        production:
          pipelineRuns:
            - selector:
                - matchLabels:
                    critical: "true"

拒绝消息包含 selectors are NOT supported in global ConfigMap. Use namespace-level ConfigMap (tekton-pruner-namespace-spec) instead。

对于基于选择器的资源组,请使用单独的命名空间 ConfigMap(方法 2)。

常见模式

基于环境:

spec:
  tektonpruner:
    global-config:
      enforcedConfigLevel: namespace
      namespaces:
        dev:
          ttlSecondsAfterFinished: 300
          successfulHistoryLimit: 3
        staging:
          ttlSecondsAfterFinished: 86400
          successfulHistoryLimit: 5
        prod:
          ttlSecondsAfterFinished: 604800
          successfulHistoryLimit: 10

最佳实践

  1. 开发命名空间中的保留时间应短于生产命名空间,正如本页示例所示(例如,dev 为 300 秒和 3 次成功运行,prod 为 604800 秒和 10 次成功运行)。
  2. 降低全局值后,列出命名空间 ConfigMap(命令见推荐设置),并降低当前高于该全局值的值:webhook 不会重新检查现有 ConfigMap,而 Pruner 会按其当前值应用这些配置。
  3. 创建命名空间 ConfigMap 之前,使用 kubectl create --dry-run=server -f <file> 对其进行检查:启用基于事件的 Pruner 且 ConfigMap 带有这两个标签时,webhook 会对其进行验证,而 dry run 不会存储任何内容。dry run 报告 ConfigMap 已创建,只能说明没有组件拒绝它;即使 webhook 未对其进行验证,也会通过。要确认 webhook 会检查命名空间中的 ConfigMap,请以相同方式发送该文件的副本,并将其中 ns-config 的顶级 ttlSecondsAfterFinished 设置为 -1,替换任何现有值:该文件必须被拒绝,并且消息中包含 ttlSecondsAfterFinished cannot be negative, got -1;如果报告为已创建,则表示 webhook 未检查它。webhook 日志行(ConfigMap 验证中的“最佳实践”)也会显示相同信息,但读取这些日志需要访问 tekton-pipelines 中的 Pod 日志,通常只有集群管理员具备此权限。
  4. 对于基于选择器的组,请使用命名空间 ConfigMap。

何时启用。当许多项目共享一个集群,且一个项目已完成的 PipelineRuns 和 TaskRuns 不得不断累积或挤占其他项目的历史记录时,请启用带有命名空间级覆盖的基于事件的 Tekton Pruner。在 TektonConfig 中设置集群范围的默认值及其限制;当某个命名空间需要不同的值时,使用命名空间 ConfigMap 按命名空间覆盖。一般指导原则仍适用于此,请参阅最佳实践。

推荐值。在同一项更改中设置 spec.pruner.disabled: true 和 spec.tektonpruner.disabled: false:TaskRun 和 PipelineRun 资源的定期清理中介绍的基于旧版作业的清理与基于事件的 Pruner 不能同时启用(请参阅 Pruner 配置)。API server 接受同时启用二者的 TektonConfig,但随后 TektonConfig 会报告 Ready=False,消息中包含 Invalid Pruner Configuration!! Both pruners, tektonpruner(event based) and pruner(job based) cannot be enabled simultaneously. Please disable one of them.。设置 enforcedConfigLevel: namespace。当值为 global 时,命名空间 ConfigMap 会被接受但忽略:webhook 仍会检查它们,但 Pruner 只应用根值;不过,如果某个命名空间的 namespaces.<namespace> 条目设置了另一个 enforcedConfigLevel,则该命名空间例外(请参阅方法 2 下的检查)。将全局 ttlSecondsAfterFinished 和历史记录限制定义为平台默认值。它们也是命名空间配置中命名空间范围值的上限(请参阅验证规则),因此应将其设置为任何命名空间允许请求的最长保留期限。还要将全局 historyLimit 设置为两个历史记录限制中较小的值:命名空间的 historyLimit 只针对全局 historyLimit 进行检查,然后同时应用于两种状态;而在不设置 historyLimit: 100 的 merge patch 之后,Operator 默认值 TektonConfig 仍保留在其中。如果没有此设置,只设置 historyLimit: 100 的命名空间配置即使在全局 successfulHistoryLimit: 5 下仍会保留 100 次成功运行。全局值不会限制 pipelineRuns / taskRuns 条目中的 ttlSecondsAfterFinished,并且仅通过选择器条目值之和限制这些条目的历史记录限制;name 条目不受限制(请参阅配置内容验证)。允许项目团队通过方法 2 中介绍的 tekton-pruner-namespace-spec ConfigMap 在这些限制内进行覆盖。

WARNING

启用 Pruner 会立即删除运行记录,覆盖范围内的每个命名空间都如此,正如方法 1 前的警告所述。本节中的命令会修改集群范围的 TektonConfig,列出所有命名空间中的 PipelineRuns、TaskRuns 和 ConfigMaps(-A),并读取 tekton-pipelines 中的 ConfigMap,因此需要这些权限,通常只有集群管理员具备这些权限。tekton-pipelines 是 TektonConfig spec.targetNamespace 的默认值;如果安装使用其他命名空间,请在命令中替换它。启用 Pruner 之前:

  1. 按命名空间统计运行记录数量:

    kubectl get pipelineruns,taskruns -A --no-headers | awk '{print $1}' | sort | uniq -c
  2. 与负责这些命名空间的团队协商并确定值。

  3. 列出已有的命名空间 ConfigMap 及其值,这些值会在 enforcedConfigLevel: namespace 时生效。基于事件的 Pruner 被禁用期间创建的 ConfigMap 未经过 webhook 检查,因此请将 ns-config 下的值与新的全局限制进行比较:

    kubectl get configmaps -A --field-selector metadata.name=tekton-pruner-namespace-spec -o yaml
  4. 先使用宽松的值,例如较高的 historyLimit,并且不设置 ttlSecondsAfterFinished,然后逐步降低这些值。

下面的示例展示了目标值。对于第一次 patch,请先使用宽松的值,如警告第 4 步所述,然后逐步将其降低到目标值。

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pruner:
    disabled: true  # Must disable job-based pruner
  tektonpruner:
    disabled: false  # Enable event-based pruner
    global-config:
      enforcedConfigLevel: namespace
      ttlSecondsAfterFinished: 3600  # Global default and namespace limit
      successfulHistoryLimit: 5      # Global default and namespace limit
      failedHistoryLimit: 10         # Global default and namespace limit
      historyLimit: 5                # Namespace limit for historyLimit, which applies to both statuses

使用第一次 patch 的宽松值保存示例,文件名为 tektonconfig-pruner.yaml,然后使用 merge patch 将其合并到现有的 TektonConfig 中,而不是使用 kubectl apply -f(请参阅方法 1 前的警告):

kubectl patch tektonconfig config --type merge --patch-file tektonconfig-pruner.yaml

确认。完成 patch 后,执行方法 2 下“检查 ConfigMap 是否生效”中的 TektonConfig 读取命令:它必须输出 false namespace。然后按照更改 Pruner ConfigMap中的说明读取 Pruner 的全局 ConfigMap;输出必须包含你合并的值,例如 enforcedConfigLevel: namespace,以及使用示例值时的 historyLimit: 5。此 ConfigMap 仅在启用基于事件的 Pruner 期间存在。

前提条件。只有在名为 config 的 TektonConfig 资源中禁用基于作业的 pruner 并启用基于事件的 pruner 后,才会部署 Tekton Pruner 组件(请参阅 Tekton Pruner 未部署)。如果 Tekton Chains 在处理运行记录后被禁用,Pruner 对这些运行记录的删除将无法完成;请参阅Chains 配置中的 disabled。为每个命名空间 ConfigMap 添加验证边界中列出的标签:只有带标签的 ConfigMap 才会针对全局限制进行检查,而未带标签的 ConfigMap 仍会被应用且不会经过任何检查。仅在其所管理的运行记录所在的用户命名空间中创建这些 ConfigMap。webhook 会在 tekton-pipelines、tekton-operator 以及名称以 kube- 或 openshift- 开头的每个命名空间中拒绝它们。对于 kube-system、kube-public 和 kube-node-lease,不会调用 webhook,也不会检查其他 tekton-* 命名空间。本节中命令所需的权限已列在上面的警告中。

撤销。要关闭基于事件的 Pruner,请将以下 patch 与 kubectl patch tektonconfig config --type merge --patch-file <file> 合并。在同一文件中保留 spec.pruner.disabled: false 以恢复基于作业的清理;之后它会使用仍在 spec.pruner 中的值运行(请参阅TaskRun 和 PipelineRun 资源的定期清理);省略 pruner 以保持其关闭状态。不要在更早的 patch 中启用它:启用两个 pruner 时,TektonConfig 会报告 Ready=False。

spec:
  pruner:
    disabled: false  # Brings back the job-based cleanup; leave pruner out to keep it off
  tektonpruner:
    disabled: true  # Turns the event-based Pruner off

随后,operator 会移除 Pruner controller、其 webhook 和 tekton-pruner-default-spec。方法 2 下的 TektonConfig 读取命令会将 true 作为第一个值输出,而 kubectl get configmap tekton-pruner-default-spec -n tekton-pipelines 会报告 Error from server (NotFound): configmaps "tekton-pruner-default-spec" not found。如果安装使用其他 spec.targetNamespace,请先在此命令中将 tekton-pipelines 替换为相应值:在 Pruner 所在命名空间之外的命名空间中读取时,即使 Pruner 仍已安装,该命令也会报告 NotFound。

若要保留基于事件的 Pruner 但停止命名空间覆盖,请改为以相同方式合并以下 patch。随后,命名空间 ConfigMap 会被接受但忽略,方法“推荐值”中所述的例外除外,并且 TektonConfig 读取命令会输出 false global。此 patch 会更改全局配置,因此根值会立即应用于 Pruner 覆盖范围内每个命名空间中的已完成运行记录,如方法 1 前的警告所述:

spec:
  tektonpruner:
    global-config:
      enforcedConfigLevel: global

移除 TTL 不会影响已经具有 TTL 的运行记录。Pruner 会将运行记录的 TTL 写入其 pruner.tekton.dev/ttlSecondsAfterFinished 注解,之后只会使用另一个 TTL 替换该值,绝不会将其移除。因此,当新配置不再为某个运行记录提供 TTL 时,例如切换到 global 后根值不设置 ttlSecondsAfterFinished 的情况,该运行记录会保留旧值,并且在基于事件的 Pruner 启用期间,仍会在该时间被删除。

后续步骤