From 3b54dd89bcc7e666837715b5ce3bf886030e2548 Mon Sep 17 00:00:00 2001 From: Dhruv Soni Date: Mon, 10 Nov 2025 20:38:43 +0530 Subject: [PATCH] RHDEVDOCS-6943: Content creation for Tekton results retention policy --- _topic_maps/_topic_map.yml | 2 + .../op-fine-grained-retention-policies.adoc | 86 +++++++++++++++++++ ...g-the-tekton-results-retention-policy.adoc | 38 ++++++++ 3 files changed, 126 insertions(+) create mode 100644 modules/op-fine-grained-retention-policies.adoc create mode 100644 records/understanding-the-tekton-results-retention-policy.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 3e6a3a2446f6..fde9d63dee2f 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -81,6 +81,8 @@ Distros: openshift-pipelines Topics: - Name: Using Tekton Results for OpenShift Pipelines observability File: using-tekton-results-for-openshift-pipelines-observability +- Name: Understanding the Tekton Results retention policy + File: understanding-the-tekton-results-retention-policy --- Name: Pipelines as Code Dir: pac diff --git a/modules/op-fine-grained-retention-policies.adoc b/modules/op-fine-grained-retention-policies.adoc new file mode 100644 index 000000000000..d78d842c96eb --- /dev/null +++ b/modules/op-fine-grained-retention-policies.adoc @@ -0,0 +1,86 @@ +// This module is included in the following assembly: +// +// * records/understanding-the-tekton-results-retention-policy.adoc + +:_mod-docs-content-type: CONCEPT +[id="op-fine-grained-retention-policies_{context}"] += Fine-grained retention policies + +You can use the `policies` field to define rules that apply to specific Results. The policies are evaluated in order, and the first matching policy is applied. If no policy matches, the `defaultRetention` value is used. + +Each policy includes the following fields: + +[options="header"] +|=== +|Field |Description + +|`name` +|A descriptive name for the policy. + +|`selector` +|Defines criteria for matching Results. All selector types use AND logic, meaning a Result must satisfy all specified conditions to match. You can omit a selector type to match all Results for that criterion. + +|`matchNamespaces` +|A list of namespaces. The policy matches Results in any of the listed namespaces. + +|`matchLabels` +|A map of label keys and possible values. A Result must have all listed label keys, and each value must match one of the values in the list. + +|`matchAnnotations` +|A map of annotation keys and possible values. Works similarly to `matchLabels`. + +|`matchStatuses` +|A list of final statuses such as `Succeeded`, `Failed`, `Cancelled`, `Running`, or `Pending`. The policy matches if the Result's final status reason is in this list. + +|`retention` +|The retention period for matching Results. The value can be a number (days) or a duration string such as `24h` or `7d`. +|=== + +The following example shows a config map that defines multiple retention policies: + +[source,yaml] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: tekton-results-config-results-retention-policy + namespace: tekton-pipelines +data: + runAt: "0 2 * * *" + defaultRetention: "30d" + policies: | + - name: "retain-critical-failures-long-term" + selector: + matchNamespaces: + - "production" + - "prod-east" + matchLabels: + "criticality": ["high"] + matchStatuses: + - "Failed" + retention: "180d" + - name: "retain-annotated-for-debug" + selector: + matchAnnotations: + "debug/retain": ["true"] + retention: "14d" + - name: "default-production-policy" + selector: + matchNamespaces: + - "production" + - "prod-east" + retention: "60d" + - name: "short-term-ci-retention" + selector: + matchNamespaces: + - "ci" + retention: "7d" +---- + +The following examples describe how the defined retention policies are applied to different Results based on their namespaces, labels, annotations, and statuses. + +* A failed Result in the `production` or `prod-east` namespace with the label `criticality: high` is retained for 180 days. +* Any Result with the annotation `debug/retain: "true"` is retained for 14 days. +* Results in the `production` or `prod-east` namespaces are retained for 60 days. +* Results in the `ci` namespace are retained for 7 days. +* All other Results that do not match any policy are retained for the default 30 days. diff --git a/records/understanding-the-tekton-results-retention-policy.adoc b/records/understanding-the-tekton-results-retention-policy.adoc new file mode 100644 index 000000000000..5f62cc743c06 --- /dev/null +++ b/records/understanding-the-tekton-results-retention-policy.adoc @@ -0,0 +1,38 @@ +:_mod-docs-content-type: ASSEMBLY +include::_attributes/common-attributes.adoc[] +[id="understanding-the-tekton-results-retention-policy"] += Understanding the Tekton Results retention policy +:context: understanding-the-tekton-results-retention-policy + +toc::[] + +[role="_abstract"] + +The {tekton-results} Retention Policy Agent manages how long {tekton-results} and Records are retained in the database before they are pruned. You can configure the retention behavior by using the `tekton-results-config-results-retention-policy` config map in the `tekton-pipelines` namespace. + +The retention policy determines when and how old {tekton-results} and Records are automatically deleted from the database. You can define global defaults as well as fine-grained rules based on namespaces, labels, annotations, or run statuses. + +The following fields in the config map define the retention configuration: + +[options="header"] +|=== +|Field |Description |Default + +|`runAt` +|Specifies when the pruning job runs. The value must use a cron schedule format. +|`"7 7 * * 7"` (every Sunday at 7:07 a.m.) + +|`defaultRetention` +|Specifies the fallback retention period for Results and Records when no specific policy matches. The value can be a number (in days) or a duration string such as `30d` or `24h`. +|`30d` + +|`maxRetention` +|(Deprecated). Used for backward compatibility if `defaultRetention` is not set. This field will be removed in a future release. +|N/A + +|`policies` +|Defines a list of fine-grained retention policies for more specific control. Each policy includes a name, selector, and retention period. +|None +|=== + +include::modules/op-fine-grained-retention-policies.adoc[leveloffset=+1]