Resource Groups
Apply different pruning policies to different sets of PipelineRuns/TaskRuns using selectors.
IMPORTANT: Selectors only work in namespace-level ConfigMaps (tekton-pruner-namespace-spec). In the global config, a selector under namespaces.<namespace> is rejected; see ConfigMap Validation.
Namespace level required: A namespace ConfigMap, and so every selector group on this page, takes effect only when the enforcedConfigLevel that applies to its namespace is namespace: the value in the spec.tektonpruner.global-config.namespaces.<namespace> entry of TektonConfig if that entry sets one, else spec.tektonpruner.global-config.enforcedConfigLevel (see Namespace Configuration). global is the Operator default (a global-config that has no enforcedConfigLevel falls back to resource): at every level other than namespace, the webhook still accepts a namespace ConfigMap, but the Pruner ignores it.
Namespace-level ConfigMaps are outside the TektonConfig lifecycle. If you need to back up or restore Tekton configuration later, save these ConfigMaps separately.
TOC
How It WorksSelector TypesCommon PatternsOrder MattersBest PracticesAdvanced ConfigurationsMulti-tier ApplicationRelease TypesLabeling Your PipelinesRelatedHow It Works
- Match by labels or annotations on PipelineRuns/TaskRuns
- First match wins: Groups evaluated in order; the first group whose selector matches a run decides that run's values. A
nameentry for the run's Pipeline or Task, if the ConfigMap has one, is checked before the groups - Fallback: Unmatched resources, and the fields that the matching group does not set, use namespace or global defaults
- Shared counts: A group's history limit counts every run that matches the group's selector, including runs that an earlier group matched first. A namespace-wide history limit, applied when a run completes that no group matches or whose group does not set that history limit, counts the runs of all groups and deletes the older ones whatever their group's limit (see History-based Pruning)
- History limits of groups: For each kind (
pipelineRuns,taskRuns), the webhook bounds the sum of the groups'successfulHistoryLimitvalues by the top-levelsuccessfulHistoryLimitof the namespace ConfigMap, else its top-levelhistoryLimit, else the inlinenamespaces.<namespace>entry of the global config, else the global value, else 100;failedHistoryLimitworks the same way (see Pipeline-specific Limits). The top-level values are themselves checked against the global values, but a top-levelhistoryLimitis checked only against the globalhistoryLimit(100 when it is not set). So the globalsuccessfulHistoryLimit(orfailedHistoryLimit) caps the sum only when the globalhistoryLimitis not higher, as in Recommended Settings; otherwise a top-levelhistoryLimitcan raise the bound up to the globalhistoryLimit - Location: Must be in namespace ConfigMap, not global ConfigMap
The samples below that set history limits need sums of up to 55 successful runs (Multi-tier Application: 10 + 15 + 30). The webhook accepts them only when the bound is at least the sum, for example under the Operator default global config (historyLimit: 100, no successfulHistoryLimit). Under the global values of Recommended Settings (successfulHistoryLimit: 5, historyLimit: 5), it rejects each of them with a message that contains sum of selector successfulHistoryLimit (<sum>) cannot exceed upper bound (5). Raise the global values to at least the sums you need, or lower the group values.
Selector Types
Label selectors:
Annotation selectors:
Mixed selectors (both labels and annotations must match):
Common Patterns
By Pipeline Type:
By Environment:
By Criticality:
Order Matters
First match wins - order selectors from most to least specific:
Best Practices
- Use namespace ConfigMaps for selector-based groups
- Order selectors from most to least specific (first match wins)
- Use separate label values for groups that need their own history limit (for example
tier: frontendandtier: backend): a group counts every run that matches its selector, also the runs that an earlier group matched - Test with a sample run before production: once the run has completed, its
pruner.tekton.dev/ttlSecondsAfterFinishedannotation shows the TTL that the Pruner chose for it (command and the causes of an unexpected value in Pipeline-specific TTLs). A group's history limit leaves no such value on the run (see Pipeline-specific Limits)
Advanced Configurations
Multi-tier Application
Release Types
If Tekton Results stores these runs, keep its retention period longer than the longest TTL here (see Relationship with In-Cluster Pruning).
Labeling Your Pipelines
Add labels to PipelineRuns for grouping:
Related
- Namespace Configuration - Set up namespace ConfigMaps
- Time-based Pruning - TTL strategies for groups
- History-based Pruning - Retention strategies for groups