RHDEVDOCS-6943: Content creation for Tekton results retention policy

_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

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.

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]