Skip to content

Commit aa6cb05

Browse files
Dhruv-Soni11Dhruv-Soni11
authored
Merge pull request #99633 from openshift-cherrypick-robot/cherry-pick-99108-to-pipelines-docs-1.20
[pipelines-docs-1.20] [RHDEVDOCS-6630] Enhancements of spec.tektonpruner for 1.20
2 parents ad037f9 + 2bd2329 commit aa6cb05

File tree

4 files changed

+258
-0
lines changed

4 files changed

+258
-0
lines changed

‎install_config/customizing-configurations-in-the-tektonconfig-cr.adoc‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,12 @@ include::modules/op-default-pruner-configuration.adoc[leveloffset=+2]
5757

5858
include::modules/op-annotations-for-automatic-pruning-taskruns-pipelineruns.adoc[leveloffset=+2]
5959

60+
include::modules/op-event-pruner-configuration.adoc[leveloffset=+1]
61+
62+
include::modules/op-event-pruner-reference.adoc[leveloffset=+2]
63+
64+
include::modules/op-event-pruner-observability.adoc[leveloffset=+2]
65+
6066
include::modules/op-additional-options-webhooks.adoc[leveloffset=+1]
6167

6268

‎modules/op-event-pruner-configuration.adoc‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
// This module is included in the following assemblies:
2+
// * install_config/customizing-configurations-in-the-tektonconfig-cr.adoc
3+
4+
:_mod-docs-content-type: PROCEDURE
5+
[id="event-pruner-configuration_{context}"]
6+
= Enabling the event-based pruner
7+
8+
:FeatureName: The event-based pruner
9+
include::snippets/technology-preview.adoc[]
10+
11+
You can use the event-based `tektonpruner` controller to automatically delete completed resources, such as `PipelineRuns` and `TaskRuns`, based on configurable policies. Unlike the default job-based pruner, the event-based pruner listens for resource events and prunes resources in near real time.
12+
13+
[IMPORTANT]
14+
====
15+
You must disable the default pruner in the `TektonConfig` custom resource (CR) before you enable the event-based pruner. If both pruner types are enabled, the deployment readiness status changes to `False` and the following error message is displayed on the output:
16+
17+
[source,terminal]
18+
----
19+
Components not in ready state: Invalid Pruner Configuration!! Both pruners, tektonpruner(event based) and pruner(job based) cannot be enabled simultaneously. Please disable one of them.
20+
----
21+
====
22+
23+
.Procedure
24+
25+
. In your TektonConfig CR, disable the default pruner by setting the `spec.pruner.disabled` field to `true` and enable the event-based pruner by setting the `spec.tektonpruner.disabled` field to `false`. For example:
26+
+
27+
[source,yaml]
28+
----
29+
apiVersion: operator.tekton.dev/v1alpha1
30+
kind: TektonConfig
31+
metadata:
32+
name: config
33+
spec:
34+
# ...
35+
pruner:
36+
disabled: true
37+
# ...
38+
tektonpruner:
39+
disabled: false
40+
options: {}
41+
# ...
42+
----
43+
+
44+
After you apply the updated CR, the Operator deploys the `tekton-pruner-controller` pod in the `openshift-pipelines` namespace.
45+
46+
. Ensure that the following config maps are present in the `openshift-pipelines` namespace:
47+
+
48+
[cols="1,3",options="header"]
49+
|===
50+
|Config map
51+
|Purpose
52+
53+
|`tekton-pruner-default-spec`
54+
|Define default pruning behavior
55+
56+
|`pruner-info`
57+
|Store internal runtime data used by the controller
58+
59+
|`config-logging-tekton-pruner`
60+
|Configure logging settings for the pruner
61+
62+
|`config-observability-tekton-pruner`
63+
|Enable observability features such as metrics and tracing
64+
|===
65+
66+
67+
.Verification
68+
69+
. To verify that the `tekton-pruner-controller` pod is running, run the following command:
70+
+
71+
[source,terminal]
72+
----
73+
$ oc get pods -n openshift-pipelines
74+
----
75+
76+
. Verify that the output includes a `tekton-pruner-controller` pod in the `Running` state. Example output:
77+
+
78+
[source,terminal]
79+
----
80+
$ tekton-pruner-controller-<id> Running
81+
----

‎modules/op-event-pruner-observability.adoc‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
// This module is included in the following assemblies:
2+
// * install_config/customizing-configurations-in-the-tektonconfig-cr.adoc
3+
4+
:_mod-docs-content-type: REFERENCE
5+
[id="event-pruner-observability_{context}"]
6+
= Observability metrics of the event-based pruner
7+
8+
:FeatureName: The event-based pruner
9+
include::snippets/technology-preview.adoc[]
10+
11+
The event-based pruner exposes detailed metrics through the `tekton-pruner-controller` controller `Service` definition on port `9090` in OpenTelemetry format for monitoring, troubleshooting, and capacity planning.
12+
13+
Following are categories of the metrics exposed:
14+
15+
* Resource processing
16+
* Performance timing
17+
* State tracking
18+
* Error monitoring
19+
20+
Most pruner metrics use labels to provide additional context. You can use these labels in PromQL{nbsp}queries or dashboards to filter and group the metrics.
21+
22+
[cols="1,3"options="header"]
23+
|===
24+
| Label | Description
25+
26+
| `namespace`
27+
| The Kubernetes namespace of the `PipelineRun` or `TaskRun`.
28+
29+
| `resource_type`
30+
| The Tekton resource type.
31+
32+
| `status`
33+
| The outcome of processing a resource.
34+
35+
| `operation`
36+
| The pruning method that deleted a resource.
37+
38+
| `reason`
39+
| Specific cause for skipping or error outcomes.
40+
|===
41+
42+
Resource processing metrics::
43+
The following resource processing metrics are exposed by the event-based pruner:
44+
+
45+
[cols="3,1,3,2",options="header"]
46+
|===
47+
| Name | Type | Description | Labels
48+
| `tekton_pruner_controller_resources_processed_total` | Counter | Total resources processed | namespace, resource_type, status
49+
| `tekton_pruner_controller_resources_deleted_total` | Counter | Total resources deleted | namespace, resource_type, operation
50+
|===
51+
52+
53+
Performance timing metrics::
54+
The following performance timing metrics are exposed by the event-based pruner:
55+
+
56+
[cols="3,1,3,2,2",options="header"]
57+
|===
58+
| Name | Type | Description | Labels | Bucket
59+
| `tekton_pruner_controller_reconciliation_duration_seconds` | Histogram | Time spent in reconciliation | namespace, resource_type | 0.1 to 30 seconds
60+
| `tekton_pruner_controller_ttl_processing_duration_seconds` | Histogram | Time spent processing TTL | namespace, resource_type | 0.1 to 30 seconds
61+
| `tekton_pruner_controller_history_processing_duration_seconds` | Histogram | Time spent processing history limits | namespace, resource_type | 0.1 to 30 seconds
62+
|===
63+
64+
State tracking metrics::
65+
The following state tracking metrics are exposed by the event-based pruner:
66+
+
67+
[cols="3,1,3",options="header"]
68+
|===
69+
| Name | Type | Description
70+
| `kn_workqueue_adds_total` | Counter | Total resources queued
71+
| `kn_workqueue_depth` | Gauge | Number of current items in queue
72+
|===
73+
74+
Error monitoring metrics::
75+
The following error monitoring metrics are exposed by the event-based pruner:
76+
+
77+
[cols="3,1,3,2",options="header"]
78+
|===
79+
| Name | Type | Description | Labels
80+
| `tekton_pruner_controller_resources_errors_total` | Counter | Total processing errors | namespace, resource_type, reason
81+
|===

‎modules/op-event-pruner-reference.adoc‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
// This module is included in the following assemblies:
2+
// * install_config/customizing-configurations-in-the-tektonconfig-cr.adoc
3+
4+
:_mod-docs-content-type: REFERENCE
5+
[id="event-pruner-reference_{context}"]
6+
= Configuration of the event-based pruner
7+
8+
:FeatureName: The event-based pruner
9+
include::snippets/technology-preview.adoc[]
10+
11+
You can configure the pruning behavior of the event-based pruner by modifying your `TektonConfig` custom resource (CR).
12+
13+
The following is an example of the `TektonConfig` CR with the default configuration that uses global pruning rules:
14+
15+
[source,yaml]
16+
----
17+
apiVersion: operator.tekton.dev/v1alpha1
18+
kind: TektonConfig
19+
metadata:
20+
name: config
21+
spec:
22+
# ...
23+
tektonpruner:
24+
disabled: false
25+
global-config:
26+
enforcedConfigLevel: global
27+
failedHistoryLimit: null
28+
historyLimit: 10
29+
namespaces: null
30+
successfulHistoryLimit: null
31+
ttlSecondsAfterFinished: null
32+
options: {}
33+
# ...
34+
----
35+
* `failedHistoryLimit`: The amount of retained failed runs.
36+
* `historyLimit`: The amount of runs to retain. Pruner uses this setting if status-specific limits are not defined.
37+
* `namespaces`: Definition of per-namespace pruning policies, when you set `enforcedConfigLevel` to `namespace`.
38+
* `successfulHistoryLimit`: The amount of retained successful runs.
39+
* `ttlSecondsAfterFinished`: Time in seconds after completion, after which the pruner deletes resources.
40+
41+
You can define pruning rules for individual namespaces by setting `enforcedConfigLevel` to `namespace` and configuring policies under the `namespaces` section. In the following example, a 60 second time to live (TTL) is applied to resources in the `dev-project` namespace:
42+
43+
[source,yaml]
44+
----
45+
apiVersion: operator.tekton.dev/v1alpha1
46+
kind: TektonConfig
47+
metadata:
48+
name: config
49+
spec:
50+
# ...
51+
tektonpruner:
52+
disabled: false
53+
global-config:
54+
enforcedConfigLevel: namespace
55+
ttlSecondsAfterFinished: 300
56+
namespaces:
57+
dev-project:
58+
ttlSecondsAfterFinished: 60
59+
# ...
60+
----
61+
62+
You can use the following parameters in your `TektonConfig` CR `tektonpruner`:
63+
64+
[cols="1,3",options="header"]
65+
|===
66+
|Parameter |Description
67+
68+
|`ttlSecondsAfterFinished`
69+
|Delete resources a fixed number of seconds after they complete.
70+
71+
|`successfulHistoryLimit`
72+
|Retain the specified number of the most recent successful runs. Delete older successful runs.
73+
74+
|`failedHistoryLimit`
75+
|Retain the specified number of the most recent failed runs. Delete older failed runs.
76+
77+
|`historyLimit`
78+
|Apply a generic history limit when `failedHistoryLimit` and `successfulHistoryLimit` are not defined.
79+
80+
|`enforcedConfigLevel`
81+
|Specify the level at which pruner applies the configuration. Accepted values: `global` or `namespace`.
82+
83+
|`namespaces`
84+
|Define per-namespace pruning policies.
85+
|===
86+
87+
[NOTE]
88+
====
89+
You can use TTL-based pruning to prune resources exceeding set expiration times. Use history-based pruning to prune resources exceeding the configured `historyLimit`.
90+
====

0 commit comments

Comments
 (0)