License

Tekton Pruner manages the lifecycle of Tekton resources by automatically cleaning up completed PipelineRuns and TaskRuns based on configurable time-based (TTL) and history-based policies.

📖 For comprehensive architecture details, design decisions, and data flows, see ARCHITECTURE.md

Tekton Pruner provides event-driven and configuration-based cleanup through four controllers:

• Main Pruner Controller: Processes cleanup based on ConfigMap settings
• Namespace Pruner Config Controller: Watches namespace-level ConfigMaps
• PipelineRun Controller: Handles PipelineRun events
• TaskRun Controller: Handles standalone TaskRun events

Tekton Pruner overview

• Time-based Pruning (TTL): Delete resources after specified duration (in seconds) using ttlSecondsAfterFinished
• History-based Pruning: Retain fixed number of runs using successfulHistoryLimit, failedHistoryLimit, or historyLimit
• Hierarchical Configuration: Allows users to specify cluster-wide or per Namespace or per group of resources within a Namespace
• Flexible Selectors: Group resources by labels, annotations, or names (name refers to the pipeline name) for fine-grained control

Prerequisites:

• Kubernetes cluster with Tekton Pipelines installed

Install:

export VERSION=0.3.3 # Update as needed
kubectl apply -f "https://infra.tekton.dev/tekton-releases/pruner/previous/v$VERSION/release.yaml"

Verify:

kubectl get pods -n tekton-pipelines -l app=tekton-pruner-controller

Version v0.3.2 has been retracted from the Go module registry due to it being an unintended release. Users are recommended not to use v0.3.2

CRITICAL: Starting v0.3.0, all pruner ConfigMaps MUST include these labels for validation and processing:

labels:
 app.kubernetes.io/part-of: tekton-pruner
 pruner.tekton.dev/config-type: <global|namespace>

System Boundaries: Do NOT create namespace-level ConfigMaps in:

• System namespaces (kube-*, openshift-*)
• Tekton controller namespaces (tekton-pipelines, tekton-*)

1. Global Config (cluster-wide defaults in tekton-pipelines namespace)
2. Namespace Config (per-namespace overrides when enforcedConfigLevel: namespace)
3. Resource Groups (fine-grained control via selectors)

apiVersion: v1
kind: ConfigMap
metadata:
 name: tekton-pruner-default-spec
 namespace: tekton-pipelines
 labels:
 app.kubernetes.io/part-of: tekton-pruner
 pruner.tekton.dev/config-type: global
data:
 global-config: |
 enforcedConfigLevel: global
 ttlSecondsAfterFinished: 300
 successfulHistoryLimit: 3
 failedHistoryLimit: 3

Option 1: Inline in Global ConfigMap

data:
 global-config: |
 enforcedConfigLevel: namespace
 namespaces:
 my-namespace:
 ttlSecondsAfterFinished: 60

Option 2: Separate Namespace ConfigMap (Recommended for self-service)

apiVersion: v1
kind: ConfigMap
metadata:
 name: tekton-pruner-namespace-spec
 namespace: my-app-namespace # User namespace only
 labels:
 app.kubernetes.io/part-of: tekton-pruner
 pruner.tekton.dev/config-type: namespace
data:
 ns-config: |
 ttlSecondsAfterFinished: 300
 successfulHistoryLimit: 5

Group resources by labels/annotations for different policies within a namespace.

Note: Selectors only work in namespace-level ConfigMaps, not global ConfigMaps.

apiVersion: v1
kind: ConfigMap
metadata:
 name: tekton-pruner-namespace-spec
 namespace: my-app
 labels:
 app.kubernetes.io/part-of: tekton-pruner
 pruner.tekton.dev/config-type: namespace
data:
 ns-config: |
 pipelineRuns:
 - selector:
 - matchLabels:
 environment: production
 ttlSecondsAfterFinished: 604800
 successfulHistoryLimit: 10
 - selector:
 - matchLabels:
 environment: development
 ttlSecondsAfterFinished: 300
 successfulHistoryLimit: 3

For detailed tutorials, see:

• Getting Started
• Namespace Configuration
• Resource Groups
• ConfigMap Validation - How ConfigMaps are validated by the webhook

• See DEVELOPMENT.md for development setup
• Submit issues and pull requests
• Follow coding standards and test coverage requirements

Apache License 2.0 - See LICENSE for details