基于时间的修剪(TTL)

使用 ttlSecondsAfterFinished 在指定时长后删除已完成的资源。

工作原理

TTL 适用于已完成的 PipelineRuns 和独立的 TaskRuns,包括成功和失败的运行。计时器在运行完成时启动。对于由 PipelineRun 创建的 TaskRuns,Pruner 不会为其设置自己的 TTL,也不会从 taskRuns 条目中获取 TTL;Kubernetes 会随拥有它们的 PipelineRun 一起删除这些 TaskRuns。

基本配置

WARNING

此页面上的 TektonConfig 示例适用于整个集群。Pruner 启动后立即,以及每次全局配置发生更改时,它都会将历史限制和 TTL 应用到其覆盖范围内每个命名空间中的已完成运行,并删除超出限制的运行,包括其他团队的运行。即使示例未设置任何历史限制,历史限制也仍然会生效:在未设置该值的合并补丁之后,Operator 默认值 historyLimit: 100 仍保留在 TektonConfig 中,因此使用 global-config 根值的命名空间最多保留最新的 100 个成功运行和最新的 100 个失败运行,即使在 TTL 范围内也是如此。在 enforcedConfigLevel: namespace 下,具有 namespaces 条目的命名空间使用其命名空间 ConfigMap 和该条目中的值,而不是根值:Environment-specific TTLs 中的命名空间 dev、staging 和 prod 不会有历史限制,除非其命名空间 ConfigMap 设置了限制。已删除的运行及其日志无法恢复。在应用示例之前,请按照命名空间配置中的步骤操作(统计运行数量、与各团队达成一致、列出现有的命名空间 ConfigMap,并从宽松的值开始)。使用 kubectl patch tektonconfig config --type merge --patch-file <file> 将示例合并到现有的 TektonConfig 中,而不要使用 kubectl apply -f。

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  # Delete after 1 hour

要进行确认,请使用特定于 Pipeline 的 TTL中的命令,读取在补丁应用后启动且已完成的运行的 pruner.tekton.dev/ttlSecondsAfterFinished 注解:对于使用 global-config 根值的命名空间,该注解必须显示 3600。

常见 TTL 值

时长秒数使用场景
5 分钟300开发/测试快速迭代
1 小时3600CI Pipeline
1 天86400通用工作负载
7 天604800Staging/发布
30 天2592000Production/审计/合规

如果 Tekton Results 存储这些运行,请将其保留期设置得长于 TTL(请参阅与集群内 Pruning 的关系)。

特定于环境的 TTL

spec:
  tektonpruner:
    global-config:
      enforcedConfigLevel: namespace
      ttlSecondsAfterFinished: 2592000  # Default and upper limit: 30 days
      namespaces:
        dev:
          ttlSecondsAfterFinished: 300      # 5 min
        staging:
          ttlSecondsAfterFinished: 86400    # 1 day
        prod:
          ttlSecondsAfterFinished: 2592000  # 30 days

namespaces.<namespace> 下的值不能超过根 ttlSecondsAfterFinished。例如,当根值为 3600 时,Operator webhook 会拒绝该配置,并显示类似 global-config.namespaces.prod: ttlSecondsAfterFinished (2592000) cannot exceed global limit (3600) 的消息。将根值设置为至少等于最大的命名空间值。除非其命名空间 ConfigMap 设置了 TTL,否则 namespaces 下没有条目的命名空间使用根值。如果没有根值,则会根据系统最大值 2592000 秒(30 天)检查命名空间值。

特定于 Pipeline 的 TTL

使用命名空间 ConfigMap 中的选择器设置特定于 Pipeline 的 TTL。仅当适用于该命名空间的 enforcedConfigLevel 为 namespace 时,命名空间 ConfigMap 才会生效:如果 global-config 的 namespaces.<namespace> 条目设置了值,则使用该值;否则使用 global-config 的根值(请参阅命名空间配置)。上面的基本配置未设置级别。按照该部分警告中的说明将其合并到现有的 TektonConfig 后,它会保留现有的 enforcedConfigLevel:如果该值仍是 Operator 写入的值,则为 global。完全没有 enforcedConfigLevel 的 global-config 会回退到 resource。在除 namespace 之外的所有级别,Pruner 都会忽略命名空间 ConfigMap,尽管 webhook 会接受它们:

WARNING

命名空间级别的 ConfigMap 不属于 TektonConfig 生命周期。如果以后需要备份或恢复 Tekton 配置,请单独保存这些 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: |
    ttlSecondsAfterFinished: 3600
    pipelineRuns:
      - selector:
          - matchLabels:
              pipeline-type: release
        ttlSecondsAfterFinished: 604800
      - selector:
          - matchLabels:
              pipeline-type: test
        ttlSecondsAfterFinished: 300

要确认条目的 TTL 是否生效,请读取 Pruner 写入某个已完成运行的 TTL。该运行应与该条目匹配,并且应在你上次更改 Pruner 配置后启动(请参阅下面的第二个原因)。这只需要对该命名空间中的 PipelineRuns 具有读取权限:

kubectl get pipelinerun <name> -n <namespace> -o jsonpath='{.metadata.annotations.pruner\.tekton\.dev/ttlSecondsAfterFinished}'

该命令会输出 Pruner 用于该运行的 TTL(以秒为单位);运行完成后经过该时长,运行就会被删除。对于此示例中的 pipeline-type: release 运行,它必须输出 604800。其他值(例如 ns-config 顶部的 3600)表示该条目不适用,运行会在该时间被删除;如果没有输出值,则表示 Pruner 未为该运行设置 TTL。以下原因均可能导致这种情况,且不会报告任何错误:

  • 基于事件的 Pruner 已禁用,这是 Operator 的默认设置:不会写入 TTL。命名空间配置的方式 2 中读取的 TektonConfig 随后会将 true 输出为第一个值。
  • 适用于该命名空间的 enforcedConfigLevel 不是 namespace;同一个 TektonConfig 读取操作会将根级别输出为第二个值。global 是 Operator 的默认设置;当第二个值为空时,global-config 没有 enforcedConfigLevel,Pruner 会回退到 resource。global-config 的 namespaces.<namespace> 条目中的 enforcedConfigLevel 会替换该命名空间的根值。在 global 和 resource 下,Pruner 会忽略命名空间 ConfigMap:在 global 下,它会为运行使用全局 TTL;在 resource 下,它会使用 namespaces.<namespace> 条目,或者在命名空间没有该条目时使用全局 TTL。当这不会产生 TTL 时,Pruner 不会写入 TTL,但也不会移除先前配置写入的值:已经具有 TTL 的运行会保留该值。对于在更改之前启动的运行,该命令随后会输出旧值,可能是条目设置的 604800,即使该条目已不再适用;运行仍会在该时间被删除。
  • 另一个条目先做出决定。第一个选择器与该运行匹配的条目决定其 TTL,并且会先检查该运行的 Pipeline 对应的 name 条目,然后再检查选择器条目。如果该条目未设置 ttlSecondsAfterFinished,则运行会获得整个命名空间的 TTL(此处为 3600),而不是后续匹配条目的 TTL。该示例没有 name 条目,pipeline-type: release 条目前也没有其他条目;添加条目时可能会出现这种情况。
  • 运行的标签与条目的选择器不匹配:运行会获得另一个与其匹配的条目的 TTL,例如 pipeline-type: test 条目的 300,或者获得整个命名空间的 TTL,即 ns-config 顶部的 3600。
  • 条目的 ttlSecondsAfterFinished 键拼写错误,例如 ttlSecondAfterFinished:webhook 和 Pruner 都不会报告未知键,因此该条目不会设置 TTL,运行会获得整个命名空间的 TTL。

将 TTL 与历史记录限制结合使用

历史记录限制不会保护运行免受 TTL 的影响。Pruner 会独立应用这两项设置。该示例是命名空间 ConfigMap 的 ns-config,因此还需要 enforcedConfigLevel: namespace:

data:
  ns-config: |
    ttlSecondsAfterFinished: 300
    successfulHistoryLimit: 5
    failedHistoryLimit: 10

结果:每次运行完成 5 分钟后都会被删除,即使它是该命名空间最近 5 次成功运行之一,或最近 10 次失败运行之一。

最佳实践

  1. 开发环境和生产环境:开发命名空间应使用比生产命名空间更短的 TTL,如特定环境的 TTL 中所示(dev 为 300 秒,prod 为 2592000 秒)。
  2. 关键 Pipeline:具有更长 ttlSecondsAfterFinished 的条目会让其运行的保留时间长于其他运行的 TTL,但这仅在该条目适用时生效(如特定 Pipeline 的 TTL中所述,检查已完成运行的注解),且不会超过历史记录限制。例如,命名空间级历史记录限制 historyLimit: 100(即 Operator 默认值)仍会统计这些运行,并在某次运行完成时删除较旧的运行,前提是没有条目与该运行匹配,或其条目未设置该历史记录限制;在特定 Pipeline 的 TTL 示例中,其条目仅设置 TTL,因此所有运行都属于这种情况(请参阅特定 Pipeline 的限制)。
  3. 历史记录限制内的 TTL:即使某次运行仍在历史记录限制范围内,TTL 到期后也会被删除(请参阅“将 TTL 与历史记录限制结合使用”),因此不要将 TTL 设置得短于运行必须保留的时间。

相关内容