保留策略配置
Tekton Results 保留策略可自动清理数据库记录以及 S3 兼容存储系统中的归档日志。保留智能体会根据可配置的基于时间的策略定期删除过期结果,并尽力删除其关联的日志负载(参见保留值限制)。使用 File 日志后端(logs_type: File)时,仅会删除数据库记录;日志文件会保留在 PVC 上。
配置
通过 TektonConfig 自定义资源配置保留策略,并使用 spec.result.options 字段指定 ConfigMap 覆盖项:
此示例展示了保留策略键以及数据库和日志设置。请勿将其合并到正在运行的安装中:其中的占位值会替换现有的数据库和日志设置。若只需更改保留设置,请按照应用配置中的说明操作。Tekton Results 的安装说明请参见快速入门;该文档会设置 disabled: false。
配置参数
上述默认值是随 Tekton Results 安装的 tekton-results-config-results-retention-policy ConfigMap 中的值。如果从 ConfigMap 中移除 defaultRetention,保留智能体会回退到内置的 30 天值,而不会失败。runAt 没有可用的回退值:请将其设置为有效的五字段 Cron 表达式。其内置值 7 7 * * 7 会被保留智能体使用的 Cron 解析器拒绝,因为该解析器只接受 0 到 6 的星期值;因此,当移除 runAt 或其不是有效的 Cron 表达式时,保留智能体会启动失败。
defaultRetention 接受三种等效格式:普通整数表示天数("30"),带 d 后缀的值也表示天数("30d"),任何其他值都会被解析为 Go duration("720h")。
-
defaultRetention:指定在自动删除前保留结果的时长。此期限结束后,数据库记录会被删除,保留智能体还会尝试删除 S3 存储中的关联日志负载;日志删除是尽力而为,请参见保留值限制。使用logs_type: File时,日志文件会保留在 PVC 上。 -
runAt:定义保留智能体运行时间的 Cron 表达式。runAt使用保留智能体容器的时区(随附镜像中为 UTC+8),而不是 UTC。若要使用其他时区,请在表达式前添加时区前缀,例如runAt: "CRON_TZ=UTC 0 2 * * *"。"0 2 * * *"- 每天 02:00"0 2 * * 0"- 每周日 02:00"0 2 1 * *"- 每月 1 日 02:00
保留值限制
- 无上限或符号检查:
defaultRetention和每个策略的retention值只会检查是否具有可解析的格式;策略的retention值仅在作业运行时检查(参见应用配置)。Tekton Results 不会限制保留期限;请根据自身的审计或合规要求选择期限。以天为单位的值(普通整数或d后缀)会转换为 Gotime.Duration,且不会检查溢出,因此高于 106751 天(约 292 年)的值会回绕为无关的 duration,可能为负值或接近零;下一次运行会按下一项所述删除结果。不要使用非常大的数字表示“永久保留”。超过相同限制的 Go duration 字符串(例如"2562048h")则会解析失败。 "0"和负值会删除其覆盖的所有结果:当结果记录的最后更新时间早于now - retention时,该结果会过期。使用"0"时,截止时间是作业运行的时间;使用负值时,截止时间位于未来。结果适用的保留期限取其第一个匹配策略的期限;若没有策略匹配,则取defaultRetention(参见按命名空间或标签设置保留期限)。因此,策略retention的值为"0"或更小时,下一次运行会删除其第一个匹配策略为该策略的所有结果;而defaultRetention的值为"0"或更小时,会删除所有不匹配任何策略的结果。其日志会尽力删除,详见下一项。- 日志删除是尽力而为:可通过功能门控关闭从外部存储删除日志负载;即使重试后删除仍然失败,也会忽略该失败,以便继续执行数据库清理。因此,结果记录删除后,日志负载仍可能保留在存储中。如果日志过期是要求的一部分,请同时在存储桶上配置生命周期规则,或监控存储桶中是否存在早于保留期限的日志负载。使用
logs_type: File时,保留智能体仅删除数据库记录;日志文件会保留在 PVC 上,且智能体不会报告错误。请自行从 PVC 中删除旧文件,或使用 S3 存储。 - 遗留的
maxRetention会覆盖defaultRetention:仍会读取已弃用的maxRetention键。该键存在时,其值会作为默认保留期限,defaultRetention会被忽略;保留智能体只会记录弃用警告。在依赖defaultRetention之前,请从 ConfigMap 中移除maxRetention;如果要保留其值,请将其移至defaultRetention。
与集群内修剪的关系
上游 Tekton Results 文档建议将保留策略与集群内修剪机制(例如 Tekton Pruner)结合使用,并将 Results 保留期限设置为长于集群内保留期限。这样可以避免在 PipelineRun 或 TaskRun 仍存在于集群中时,被修剪的结果重新在数据库中创建。
按命名空间或标签设置保留期限
使用 policies 键为选定的结果指定独立的保留期限,例如,为保存与审计相关的流水线的命名空间设置更长的期限。policies 是一个 YAML 字符串,其中包含策略列表;每个策略都有 name、selector 和 retention 值(格式与 defaultRetention 相同;使用其他单位的值,例如 "1y" 或 "2w",无法解析,并会使每个保留作业在删除任何内容之前停止,参见应用配置):
- 策略按顺序评估,并应用第一个匹配的策略。不匹配任何策略的结果使用
defaultRetention。 - 一个
selector可以组合matchNamespaces、matchLabels、matchAnnotations和matchStatuses。所有指定字段都必须匹配;在同一个字段中,列出的任意值匹配即可。matchLabels和matchAnnotations将键映射到可接受值列表,并针对所评估 PipelineRun 或 TaskRun 的元数据进行评估。matchStatuses针对其第一个状态条件的reason进行评估。不同 kind 的结束原因不同,例如 PipelineRun 的Succeeded、Completed(成功但存在跳过的任务)、Failed、Cancelled和PipelineRunTimeout,以及 TaskRun 的Succeeded、Failed、TaskRunCancelled和TaskRunTimeout;还存在其他失败原因。若策略要涵盖所有未成功运行,则必须列出该 kind 的失败、超时和取消原因,而不能只列出Failed。 - 仅会评估 PipelineRun 记录和独立的 TaskRun 记录。作为 PipelineRun 一部分运行的 TaskRun 会存储在 PipelineRun 的结果中,并根据匹配 PipelineRun 的策略(或
defaultRetention)随其一起删除。因此,仅存在于 TaskRun 上的标签、注解或状态选择器不会改变其删除时间;对于这些 TaskRun,PipelineRun 的reason会生效。若要让此类 TaskRun 保留更长时间,请根据 PipelineRun 进行选择:使用其命名空间,或使用设置在 PipelineRun 上的标签;Tekton 会将该标签复制到其 TaskRun。
以下示例会以不同期限保留来自一个命名空间的结果,以及带有一个标签的运行结果。示例仅展示 policies 键:按照应用配置中的说明,将其与现有 TektonConfig 的 spec.result.options 合并,并使用 kubectl patch tektonconfig config --type merge --patch-file <file>。合并补丁会保留其他 spec.result 字段,例如配置中所示的数据库和日志设置,以及其他保留键,例如 defaultRetention 和 runAt。它会替换整个 policies 值,因此请先读取当前值,并将要保留的现有策略按原顺序复制到文件中。以下命令以 YAML 格式打印 policies 值;输出为空表示未设置任何策略。本页面中的命令使用命名空间 tekton-pipelines,这是 TektonConfig 中 spec.targetNamespace 的默认值;如果安装使用其他命名空间,请在命令中替换它:
示例:
不匹配任何内容的选择器不会报告错误:原本应由其覆盖的结果会在没有任何消息的情况下回退到 defaultRetention,作业日志只会提供每种记录类型的总数。命名空间拼写错误、仅由子 TaskRun 携带的标签,或未列出的 reason 都会产生这一效果。在依赖新策略之前,请针对已存储的记录检查其选择器。policies 是一个集群范围的键,因此测试值会替换所有现有策略:在集群上测试策略之前,请遵循验证第 3 步中的注意事项以及步骤后的警告。要检查选择器,请启动端口转发;启用身份验证时,按照验证第 2 步中的说明读取令牌。然后列出带有 matchLabels 条目标签的 PipelineRun 记录,例如 team: ci;启用身份验证时,添加 --authtoken "$RESULTS_TOKEN"。本页面中的 tkn results 命令需要使用 tkn CLI 和 tkn-results 二进制文件;请按照 Quick Start 中准备 CLI的说明安装:
<namespace> 是 matchNamespaces 的命名空间,或是一个其运行结果应由该标签选择的命名空间。对于 matchStatuses,请改为根据原因进行筛选,例如 data.status.conditions[0].reason == "Failed"。一次调用会返回一页记录:不带 --limit 时为 50 条,带该参数时最多返回 --limit 值指定的数量(5 到 10000)。如果输出的记录数少于限制,且没有列出策略应保留的运行记录,则该选择器也不匹配这些运行。如果输出记录数达到限制,则可能还有更多匹配记录未显示,因此输出中缺少的运行仍可能匹配;请缩小筛选范围或提高 --limit。
应用配置
仅将保留键保存到文件中,例如 tekton-config-retention-config.yaml:
将该文件合并到现有的 TektonConfig 中。合并补丁只会更改文件中的键,并保留其他 spec.result 字段,例如数据库和日志设置:
示例输出:
不要将 kubectl apply -f 用于只包含部分 TektonConfig 的文件。kubectl apply 会将文件存储在 kubectl.kubernetes.io/last-applied-configuration 注解中,之后对另一个部分文件执行 kubectl apply -f 时,会删除早期文件设置而后续文件未包含的字段,例如这些保留键或整个 spec.result。
保留智能体无需重启即可重新加载 ConfigMap。检查 ConfigMap 是否包含新值:
示例输出:
如果 ConfigMap 仍包含之前的值,则表示 Operator 尚未应用更改。使用检查更改是否已传递到 Chains中的第二条命令读取 TektonConfig 条件:Operator 会先应用 Pipelines、基于事件的 Pruner、Triggers 和 Chains 组件,然后再应用 Tekton Results,并在遇到无法应用的组件时停止。此时,ComponentsReady 条件为 False,其消息以 Components not in ready state: 开头。更正消息中指出的设置,然后再次检查 ConfigMap。
即使智能体无法使用新值,ConfigMap 也会显示这些新值:只有在 defaultRetention(或 maxRetention)和 policies YAML 解析成功时,智能体才会应用新配置,否则会继续使用之前的配置运行。每次更改后,检查智能体日志中是否存在更新错误:
该命令必须不打印任何内容。如果某行的消息为 Error updating results config "tekton-results-config-results-retention-policy": "<error>",则表示智能体保留了之前的策略;请更正该值并再次应用。
此检查不涵盖每个策略的 retention 值,智能体仅在作业运行时解析该值。无法解析的策略 retention 值(例如 "1y")可以通过上述检查。在每个 runAt 时间,作业随后会记录其启动行以及一条消息以 failed to build case statement: 开头的错误,并在删除任何内容之前停止:在更正该值之前,策略和 defaultRetention 都不会删除记录。在更改 policies 后的第一个 runAt 时间之后,检查智能体日志中的此错误,并使用包含该次运行的 --since 时间段:
该命令必须不打印任何内容。
检查保留智能体是否正在运行。无法解析为 cron 计划的 runAt 值可以通过上述 Error updating 检查,但智能体随后会退出,并记录一条以 failed to add function for cronjob 开头的消息,因此更改后未处于 Running 状态的 Pod 表明 runAt 是原因:
示例输出:
重要说明
重要:统一清理功能(删除数据库记录,并在尽力而为的情况下删除其 S3 日志负载;请参阅保留值限制)是一个增强功能(基于补丁),目前在 Community Tekton Results 中不可用。Community 版本只会删除数据库记录,但会将日志负载留在 S3 存储中,这可能导致存储无限增长。使用
logs_type: File时,两个版本都不会从 PVC 中删除日志文件。
检查 TektonConfig 保留配置:
示例输出(缩略):
检查保留智能体日志:
智能体记录启动行后,直到作业运行之前不会记录任何内容,但以下警告除外:例如 maxRetention 弃用警告,以及它无法使用的配置的 Error updating 行(请参阅应用配置)。在每个 runAt 时间,智能体都会记录作业启动信息及生效的策略、按记录类型删除的记录数,以及作业结束信息。当策略的 retention 值无法解析时,启动行后会改为显示 failed to build case statement: 错误;作业结束时不会删除任何内容,也不会记录结束行(请参阅应用配置)。启动行和结束行中的时间是智能体容器时间。
示例输出(一次运行;策略列表已缩短):
验证
要快速验证保留策略是否按预期运行,请执行以下步骤:
-
创建测试结果/日志:在用于测试的命名空间中运行
TaskRun或PipelineRun,例如 Quick Start 中验证功能所使用的helloTaskRun,使用-n <namespace>创建(其中的说明涵盖拒绝内联taskSpec的集群)。等待其完成,以便其结果和日志存储在 Tekton Results 数据库中。 -
验证初始状态:检查数据库和 S3 存储(如果适用)中是否存在这些结果和日志。
该命令不会发送令牌,因此仅在通过
auth_disable: true禁用身份验证时有效,如 Quick Start 中所示。启用身份验证后,在不显示令牌的情况下将 bearer 令牌读入变量,然后使用--authtoken传递该变量。单独运行read -rs行,粘贴令牌并按 Enter。在不支持带括号粘贴的 Shell 中(例如 5.1 之前的 bash),read会将粘贴块的下一行作为令牌。在 bash 或 zsh 中运行这些命令:在 POSIXsh(例如dash)中,read -rs会失败并使变量保持为空:然后运行:
read -rs会使令牌不显示在屏幕上,也不会写入 Shell 历史记录,但该值仍属于tkn命令行的一部分,因此命令运行期间,机器上的其他用户可以在进程列表中看到它。 -
修改保留策略以进行测试:暂时设置一个非常短的保留期限和特定的 cron 计划用于测试(例如,在当前时间 + 10 分钟时执行一次)。根据保留智能体容器的时区计算时间,或者为表达式添加前缀
CRON_TZ=(请参阅上面的runAt)。defaultRetention适用于没有任何策略匹配的每个命名空间,因此只能在专用测试集群中将其设置为"0"。在共享集群中,将defaultRetention从补丁中省略,使其保留原值,并保留现有策略:policies是单个键,因此测试值会替换所有现有策略。首先放置一个按命名空间或标签保留中所示格式的策略,使其仅匹配步骤 1 中运行所在的命名空间,并设置retention: "0";然后复制每个现有策略,保持其内容不变且顺序不变。作业会为每条记录应用第一个匹配的策略,因此测试策略会删除该命名空间中的所有结果,而其他命名空间则保留当前的保留设置。请使用一个允许其结果全部被删除的命名空间。在进行任何更改之前,保存保留 ConfigMap 的当前值,步骤 7 会恢复这些值:将以下合并补丁保存为
retention-test-patch.yaml: -
应用修改后的配置:将补丁合并到现有的
TektonConfig中。合并补丁只会更改文件中的键,并保留其他spec.result字段。保留智能体无需重启即可重新加载 ConfigMap;按照上面的应用配置中的说明,检查 ConfigMap 和智能体日志中的Error updating。 -
监控保留智能体日志:查看保留智能体日志,确认清理操作正在执行。如果作业启动行后出现一条消息以
failed to build case statement:开头的错误,则表示策略的retention值无法解析,作业未删除任何内容;请按照应用配置中的说明更正该值。 -
验证清理已发生:保留计划执行后,验证较旧的结果和日志是否已被删除。更改步骤 4 中的保留键会替换 Results API Pod,从而终止步骤 2 中的端口转发。使用相同的
kubectl port-forward命令重新启动端口转发,然后列出记录。 -
恢复生产设置:验证完成后,将步骤 3 中保存在
retention-orig.json中的值与补丁文件合并,例如retention-revert-patch.yaml。合并补丁会保留文件中省略的键,因此请使用null显式删除测试用的policies键。如果集群在测试前设置了policies,请重新设置该值,而不是设置null:按照应用配置中的说明,检查 ConfigMap 和智能体日志中的
Error updating。如果 ConfigMap 仍保留测试值,请按照其中的说明读取TektonConfig条件。如果智能体未应用恢复操作,测试值会继续生效;使用defaultRetention: "0"时,测试计划的每次运行都会删除所有未被任何策略匹配的结果。然后删除步骤 1 中创建的运行,例如
kubectl delete taskrun hello -n <namespace>。Watcher 会在删除运行时再次将其存储到 Results 中,因此其记录会重新出现,并按照恢复后的保留期限保留。
警告:设置非常短的保留期限时请务必小心,因为这会立即删除结果。保留设置的作用范围是整个集群:请使用专用测试集群进行验证。在共享集群中,保持
defaultRetention不变,并按照步骤 3 所示,在现有策略之前仅放置一个针对测试命名空间的策略;使用defaultRetention: "0"时,没有任何策略匹配的命名空间会丢失其结果。
建议设置
启用时机。当已完成的运行从集群中删除时配置保留策略,例如通过 Tekton Pruner 删除,但这些运行必须继续可用于审计和故障排查。PipelineRun 或 TaskRun 存储到 Results 后,即可删除集群对象,因此 Results 会成为审计查询运行历史时使用的副本。通过 TektonConfig(spec.result.options)中的 defaultRetention 键设置适用于每个未被更具体策略覆盖的结果的保留期限。
建议值。将 defaultRetention 设置为审计或合规策略要求保留运行历史的天数;配置中显示的 "30" 是示例,并非合规值。如果保留 ConfigMap 仍包含已弃用的 maxRetention 键,请将其删除;如果要保留该键的值,请将其移至 defaultRetention:该键存在时,会覆盖 defaultRetention。每天在非高峰时段运行保留智能体,例如 runAt: "0 2 * * *";计划使用保留智能体容器的时区(所提供镜像使用 UTC+8),也可以使用带有 CRON_TZ= 前缀指定的时区。将这些值合并到 TektonConfig 中并进行检查,包括检查智能体日志中的 Error updating;如果设置了 policies,还应在首次作业运行后检查 failed to build case statement,如应用配置中所述。
前提条件。必须使用外部 PostgreSQL 数据库(is_external_db: true)安装 Tekton Results,因为不支持内置 PostgreSQL 数据库(请参阅快速入门);有关外部数据库,请参阅数据库配置。对于归档日志,请按照 S3 存储配置中的说明配置 S3 兼容的对象存储(logs_type: S3),以替代基于 PVC 等效率较低的存储机制。根据适用于结果的最长保留期限(defaultRetention,或者在配置了按命名空间或按标签的策略时所适用的更长期限)为数据库和存储桶规划容量。删除归档日志采用尽力而为方式,因此记录删除后,日志负载可能仍保留在存储桶中;如果日志过期是必需的,还应在存储桶上配置生命周期规则。