基于历史记录的修剪

根据运行状态保留固定数量的运行记录,不论其已存在多久。

工作原理

历史记录限制和 TTL 可以同时生效。如果某次运行超出历史记录限制,或其 TTL 已过期,则符合删除条件。这意味着以较短的保留期限为准。

配置选项

设置描述
successfulHistoryLimit保留最近成功的 N 次运行
failedHistoryLimit保留最近失败的 N 次运行
historyLimit保留每种状态各 N 次运行(未设置具体限制时)

未成功的已完成运行均计为失败运行,包括已取消或超时的运行。例如,PAC 取消的运行(使用 cancel-in-progress,请参阅正在取消)也会计入 failedHistoryLimit。

N 的计数方式。Pruner 会在某次运行完成时检查历史记录限制;当控制器启动或全局配置发生更改时,还会检查每个已完成的 PipelineRun 和独立 TaskRun,但 tekton-pipelines、tekton-operator 和 kube-* / openshift-* 命名空间除外(其中的运行会在完成时进行检查)。它会统计该命名空间中与完成运行状态相同的已完成运行,保留最近创建的 N 个运行,并删除更早的运行。具体统计哪些运行,取决于完成运行的限制来源:

  • 来自全局配置、内联 namespaces.<namespace> 条目或命名空间 ConfigMap 顶层的限制,会统计该命名空间中处于相应状态的所有已完成 PipelineRun(或 TaskRun),而不是按 Pipeline 分别统计。其中包括与 pipelineRuns / taskRuns 条目匹配的运行:当该命名空间中存在 N 个更新的同状态运行时,此类运行就会被删除,无论其自身条目设置了什么限制。
  • pipelineRuns 或 taskRuns 下条目中的限制,会统计与该条目自身选择器匹配的运行;对于 name 条目,则统计具有相同 Pipeline 或 Task 名称的运行,其中也包括之前已匹配其他条目的运行。“首次匹配优先”规则仅决定完成运行适用哪个条目的限制(请参阅Pipeline 特定限制)。
  • 对于 TaskRun,只有独立 TaskRun 会触发检查,但计数还包括由 PipelineRun 创建的 TaskRun。因此,在命名空间范围限制下完成的独立 TaskRun,可能会删除原本应保留的 PipelineRun 所创建的 TaskRun。

基本配置

WARNING

本页面中的 TektonConfig 示例适用于整个集群。Pruner 启动后立即,以及每次全局配置发生更改时,都会删除其覆盖的每个命名空间中超过历史记录限制的已完成运行,包括其他团队的运行;删除的运行及其日志无法恢复。应用示例前,请按照命名空间配置中的步骤操作(统计运行次数、与各团队达成一致、列出现有的命名空间 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:
      successfulHistoryLimit: 5    # Keep the last 5 successful runs of each namespace
      failedHistoryLimit: 10       # Keep the last 10 failed runs of each namespace (for debugging)

两种状态使用相同限制

spec:
  tektonpruner:
    global-config:
      historyLimit: 5  # Keep the last 5 successful AND the last 5 failed runs of each namespace

如需确认,请按照更改 Pruner ConfigMap中的说明读取 Pruner 的全局 ConfigMap:输出必须包含你合并的值,例如 successfulHistoryLimit: 5。

环境特定限制

spec:
  tektonpruner:
    global-config:
      enforcedConfigLevel: namespace
      successfulHistoryLimit: 10    # Default for other namespaces and upper limit for the entries below
      failedHistoryLimit: 20        # Default for other namespaces and upper limit for the entries below
      namespaces:
        dev:
          successfulHistoryLimit: 3
          failedHistoryLimit: 5     # More failed runs for debugging
        staging:
          successfulHistoryLimit: 5
          failedHistoryLimit: 5
        prod:
          successfulHistoryLimit: 10
          failedHistoryLimit: 20

namespaces.<namespace> 下的值不能超过同一字段的根值;如果根级别未设置该字段,则不能超过根级别的 historyLimit。例如,在第一个基本配置示例(根级别为 successfulHistoryLimit: 5)的基础上,如果不包含其中的两个根级别值,则 Operator webhook 会拒绝此示例,并返回包含 global-config.namespaces.prod: successfulHistoryLimit (10) cannot exceed global limit (5) 的消息。请将根级别的值设置为至少不小于最大的命名空间值,就像示例中所做的那样。没有在 namespaces 下设置条目的命名空间会使用根级别的值,除非其命名空间 ConfigMap 对这些值进行了设置。

Pipeline 特定限制

对于 Pipeline 特定的限制,请在命名空间 ConfigMap 中使用选择器。只有在适用于其命名空间的 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: |
    successfulHistoryLimit: 25  # Namespace-wide limit; also the upper bound for the sum of selector successfulHistoryLimit values
    failedHistoryLimit: 35      # Namespace-wide limit; also the upper bound for the sum of selector failedHistoryLimit values
    pipelineRuns:
      - selector:
          - matchLabels:
              critical: "true"
        successfulHistoryLimit: 20
        failedHistoryLimit: 30
      - selector:
          - matchLabels:
              pipeline-type: test
        successfulHistoryLimit: 3
        failedHistoryLimit: 5
WARNING

critical: "true" 条目设置的较高限制无法保护其运行不受命名空间范围限制的影响。当某次运行完成且没有任何条目与其匹配时,Pruner 会保留整个命名空间中最近的 25 次成功运行(或最近的 35 次失败运行),其中包括 critical 和 test 运行,并删除更早的运行。因此,只有当 critical 运行属于该命名空间最近的 25 次成功运行(或 35 次失败运行)时,才会保留它。若要保留某个组的更多运行,请在专用命名空间中运行其 Pipelines,并在那里设置限制。

与 TTL 不同,TTL 的值会在其适用时由 Pruner 写入运行中(请参阅Pipeline 特定 TTL);历史记录限制不会在运行中留下任何值:Pruner 只会在注释 pruner.tekton.dev/historyLimitCheckProcessed 中记录其检查时间。某个条目的限制是否适用,只能通过哪些运行被保留、哪些运行被删除来判断。

对于每种类型(pipelineRuns、taskRuns),webhook 会限制选择器条目的历史记录限制之和:

  • 其 successfulHistoryLimit 值之和不能超过此 ConfigMap 中命名空间级别的 successfulHistoryLimit。如果未设置,则限制依次为命名空间级别的 historyLimit、全局配置的内联 namespaces.<namespace> 条目、全局配置的根级别(每个级别均使用其 successfulHistoryLimit,否则使用其 historyLimit),最后为系统最大值 100。failedHistoryLimit 的处理方式相同。
  • 其 historyLimit 值之和不受命名空间级别 historyLimit 的限制。其限制为内联条目的 historyLimit,否则为全局的 historyLimit,否则为 100。
  • 单个条目的值不会与命名空间或全局值进行比较,name 条目的历史记录限制也不受限制;这些值只需为非负数。

命名空间级别的值本身会按照验证规则中的说明,与全局限制进行检查。

与 TTL 的交互

历史记录限制不会覆盖 TTL。示例是命名空间 ConfigMap 的 ns-config,因此还需要 enforcedConfigLevel: namespace:

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

结果:每次运行都会在完成 5 分钟后删除,即使它属于该命名空间最近的 5 次成功运行或最近的 10 次失败运行。若存在的运行数超过配置的数量,历史记录限制仍可更早删除较旧的运行。

最佳实践

  1. 保留更多失败运行以便调试:将 failedHistoryLimit 设置得高于 successfulHistoryLimit,如基本配置中的第一个示例(5 次成功运行、10 次失败运行)。
  2. 关键 Pipelines:设置了较高限制的条目无法使其运行免受命名空间范围限制的影响(请参阅Pipeline 特定限制中的警告)。如果必须保留关键 Pipelines 的运行,请在专用命名空间中运行它们。
  3. 开发环境和生产环境:开发命名空间中保留的运行数应少于生产命名空间,如环境特定限制中所示(dev 为 3 次成功运行和 5 次失败运行,prod 为 10 次和 20 次)。
  4. 降低限制前先统计数量:先统计每个命名空间中的运行数(命令见命名空间配置;该命令会读取所有命名空间)。对于命名空间限制,命名空间所有者使用 kubectl get pipelineruns,taskruns -n <namespace> --no-headers | wc -l 统计其自身命名空间中的运行数。较低的全局限制会立即删除使用该限制的命名空间中超出限制的运行(在 What N counts 下列出的命名空间除外);较低的命名空间限制则会在该命名空间中下一次使用命名空间限制的相应状态的运行完成时删除这些运行(对于 TaskRuns,则是在下一次独立 TaskRun 完成时)。

相关内容