RHDEVDOCS-3283 Document advanced prunning options

deleted dummy module

full draft

fixed topic map

minor edits

SME review modifications

fixing attribute file paths

Peer review comments

modified based on Preeti's final comments

_topic_maps/_topic_map.yml

@@ -1531,6 +1531,8 @@ Topics:
     File: reducing-pipelines-resource-consumption
   - Name: Setting compute resource quota for OpenShift Pipelines
     File: setting-compute-resource-quota-for-openshift-pipelines
+  - Name: Automatic pruning of task run and pipeline run
+    File: automatic-pruning-taskrun-pipelinerun
   - Name: Using pods in a privileged security context
     File: using-pods-in-a-privileged-security-context
   - Name: Securing webhooks with event listeners

cicd/pipelines/automatic-pruning-taskrun-pipelinerun.adoc

@@ -0,0 +1,22 @@
+:_content-type: ASSEMBLY
+[id="automatic-pruning-taskrun-pipelinerun_{context}"]
+= Automatic pruning of task run and pipeline run 
+include::_attributes/common-attributes.adoc[]
+:context: automatic-pruning-taskrun-pipelinerun
+
+toc::[]
+
+Stale `TaskRun` and `PipelineRun` objects and their executed instances occupy physical resources that can be used for the active runs. To prevent this waste, {pipelines-title} provides annotations that cluster administrators can use to automatically prune the unused objects and their instances in various namespaces. 
+
+[NOTE]
+====
+* Starting with {pipelines-title} 1.6, auto-pruning is enabled by default.
+* Configuring automatic pruning by specifying annotations affects the entire namespace. You cannot selectively auto-prune individual task runs and pipeline runs in a namespace.
+====
+
+include::modules/op-annotations-for-automatic-pruning-taskruns-pipelineruns.adoc[leveloffset=+1 ]
+
+[id="additional-resources_automatic-pruning-taskrun-pipelinerun"]
+== Additional resources
+
+* For information on manual pruning of various objects, see xref:../../applications/pruning-objects.adoc#prunning-objects[Pruning objects to reclaim resources].

modules/op-annotations-for-automatic-pruning-taskruns-pipelineruns.adoc

@@ -0,0 +1,39 @@
+// This module is included in the following assembly:
+//
+// cicd/pipelines/automatic-pruning-taskrun-pipelinerun.adoc
+
+:_content-type: REFERENCE
+[id="annotations-for-automatic-pruning-taskruns-pipelineruns_{context}"]
+= Annotations for automatically pruning task runs and pipeline runs 
+
+To automatically prune task runs and pipeline runs in a namespace, you can set the following annotations:
+
+* `operator.tekton.dev/prune.schedule`: If the value of this annotation is different from the value specified in the `TektonConfig` custom resource definition, a new cron job in that namespace is created.
+
+* `operator.tekton.dev/prune.skip`: When set to `true`, the namespace for which it is configured is not pruned.
+
+* `operator.tekton.dev/prune.resources`: This annotation accepts a comma-separated list of resources. To prune a single resource such as a pipeline run, set this annotation to `"pipelinerun"`. To prune multiple resources, such as task run and pipeline run, set this annotation to `"taskrun, pipelinerun"`.
+
+* `operator.tekton.dev/prune.keep`: Use this annotation to retain a resource without pruning.
+
+* `operator.tekton.dev/prune.keep-since`: Use this annotation to retain resources based on their age. The value for this annotation must be equal to the age of the resource in minutes. For example, to retain resources which were created not more than five days ago, set `keep-since` to `7200`.
++
+[NOTE]
+====
+The `keep` and `keep-since` annotations are mutually exclusive. For any resource, you must configure only one of them.
+====
+
+* `operator.tekton.dev/prune.strategy`: Set the value of this annotation to either `keep` or `keep-since`.
+
+For example, consider the following annotations that retain all task runs and pipeline runs created in the last five days, and deletes the older resources: 
+
+.Example of auto-pruning annotations
+[source,yaml]
+----
+...
+  annotations: 
+    operator.tekton.dev/prune.skip: false
+    operator.tekton.dev/prune.resources: "taskrun, pipelinerun"
+    operator.tekton.dev/prune.keep-since: 7200
+...
+----