Tekton – Tekton resource pruning based on configuration

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Getting Started with Tekton Pruner

This tutorial walks you through installing Tekton Pruner and creating your first configuration.

Prerequisites

Kubernetes cluster with Tekton Pipelines installed

Installation

kubectl apply -f https://raw.githubusercontent.com/tektoncd/pruner/main/release.yaml
kubectl get pods -n tekton-pipelines -l app=tekton-pruner-controller

Understanding Required Labels

CRITICAL: All pruner ConfigMaps MUST have these labels:
labels:
  app.kubernetes.io/part-of: tekton-pruner
  pruner.tekton.dev/config-type: <global|namespace>
These labels enable the pruner webhook to validate ConfigMaps and controllers to process them correctly.

Create Your First Configuration

Create a global configuration that deletes completed resources after 5 minutes and keeps the last 3 runs:

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

Apply and verify:

kubectl apply -f pruner-config.yaml
kubectl get configmap tekton-pruner-default-spec -n tekton-pipelines

Test the Configuration

Create test PipelineRuns to verify pruning:

# Create a simple pipeline
kubectl apply -f - <<EOF
apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: hello-pipeline
spec:
  tasks:
    - name: hello
      taskSpec:
        steps:
          - name: echo
            image: ubuntu
            command: ['echo']
            args: ['hello world']
EOF

# Create multiple runs
for i in {1..5}; do
  kubectl create -f - <<EOF
apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  generateName: hello-pipeline-run-
spec:
  pipelineRef:
    name: hello-pipeline
EOF
done

# Watch pruning in action (after 5 minutes + completion time)
kubectl get pipelineruns -w

Configuration Options

Setting	Description	Example
`ttlSecondsAfterFinished`	Delete after N seconds	`300` (5 min)
`successfulHistoryLimit`	Keep N successful runs	`3`
`failedHistoryLimit`	Keep N failed runs	`3`
`historyLimit`	Keep N runs (both types)	`5`
`enforcedConfigLevel`	Config hierarchy level	`global` or `namespace`

Next Steps

Namespace Configuration - Per-namespace settings and validation boundaries
Resource Groups - Fine-grained control with selectors
Time-based Pruning - TTL strategies for different environments
History-based Pruning - Retention strategies by status

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

History-based Pruning

Retain a fixed number of runs based on their status, regardless of age.

How It Works

History limits work independently from TTL. When a new run completes and the count exceeds the limit, the oldest runs are deleted. Always keeps the N most recent runs of each status.

Configuration Options

Setting	Description
`successfulHistoryLimit`	Keep N most recent successful runs
`failedHistoryLimit`	Keep N most recent failed runs
`historyLimit`	Keep N runs of EACH status (when specific limits not set)

Basic Configuration

Separate limits by status:

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: |
    successfulHistoryLimit: 5    # Keep last 5 successful
    failedHistoryLimit: 10       # Keep last 10 failed (for debugging)

Same limit for both:

data:
  global-config: |
        historyLimit: 5  # Keep last 5 successful AND last 5 failed

Environment-specific Limits

data:
  global-config: |
    enforcedConfigLevel: namespace
    namespaces:
      dev:
        successfulHistoryLimit: 3
        failedHistoryLimit: 5     # More failed runs for debugging
      staging:
        successfulHistoryLimit: 5
        failedHistoryLimit: 5
      prod:
        successfulHistoryLimit: 10
        failedHistoryLimit: 20

Pipeline-specific Limits

Use selectors in namespace ConfigMaps for pipeline-specific limits:

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: |
    successfulHistoryLimit: 3
    pipelineRuns:
      - selector:
        - matchLabels:
            critical: "true"
        successfulHistoryLimit: 20
        failedHistoryLimit: 30
      - selector:
        - matchLabels:
            pipeline-type: test
        successfulHistoryLimit: 3
        failedHistoryLimit: 5

Interaction with TTL

Important: Setting a history limit does NOT prevent TTL from deleting runs.

If you set both TTL and history limit, they run separately. TTL will still delete runs after the time passes, even if you’re under the history limit.

data:
  ns-config: |
    ttlSecondsAfterFinished: 300
    successfulHistoryLimit: 5
    failedHistoryLimit: 10

Example: With the config above, if you only have 3 successful runs and 2 failed runs, and they’re all older than 5 minutes, all 5 will be deleted by TTL.

If you want to keep N runs regardless of age, don’t set a TTL - just use history limits alone.

Verification

# Check retained runs by status
kubectl get pr -l tekton.dev/pipeline=<name> --field-selector status.conditions[0].status=True
kubectl get pr -l tekton.dev/pipeline=<name> --field-selector status.conditions[0].status=False# Monitor pruning
kubectl logs -n tekton-pipelines -l app=tekton-pruner-controller | grep "history"

Best Practices

Keep more failed runs than successful for debugging
Critical pipelines: Higher limits for audit trails
Development: Lower limits (3-5) for rapid iteration
Production: Higher limits (10-20) for analysis
Monitor storage: Adjust limits based on cluster capacity

Time-based Pruning - Age-based deletion
Namespace Configuration - Per-environment limits
Resource Groups - Pipeline-specific limits

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Time-based Pruning (TTL)

Delete completed resources after a specified duration using ttlSecondsAfterFinished.

How It Works

TTL applies to all completed runs (successful and failed). The timer starts when the run finishes.

Basic Configuration

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: |
        ttlSecondsAfterFinished: 3600  # Delete after 1 hour

Common TTL Values

Duration	Seconds	Use Case
5 minutes	`300`	Dev/test rapid iteration
1 hour	`3600`	CI pipelines
1 day	`86400`	General workloads
7 days	`604800`	Staging/release
30 days	`2592000`	Production/audit/compliance

Environment-specific TTLs

data:
  global-config: |
    enforcedConfigLevel: namespace
    ttlSecondsAfterFinished: 3600  # Default
    namespaces:
      dev:
        ttlSecondsAfterFinished: 300      # 5 min
      staging:
        ttlSecondsAfterFinished: 86400    # 1 day
      prod:
        ttlSecondsAfterFinished: 2592000

Pipeline-specific TTLs

Use selectors in namespace ConfigMaps for pipeline-specific TTLs:

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: |
    ttlSecondsAfterFinished: 3600
    pipelineRuns:
      - selector:
        - matchLabels:
            pipeline-type: release
        ttlSecondsAfterFinished: 604800
      - selector:
        - matchLabels:
            pipeline-type: test
        ttlSecondsAfterFinished: 300

Combining TTL with History Limits

Important: Setting a history limit does NOT prevent TTL from deleting runs.

If you set both TTL and history limit, they run separately. TTL will still delete runs after the time passes, even if you’re under the history limit.

data:
  ns-config: |
    ttlSecondsAfterFinished: 300
    successfulHistoryLimit: 5
    failedHistoryLimit: 10

Example: With the config above, if you only have 3 successful runs and 2 failed runs, and they’re all older than 5 minutes, all 5 will be deleted by TTL.

If you want to delete runs purely based on time, don’t set history limits - just use TTL alone.

Verification

# Check run completion times
kubectl get pipelineruns --sort-by=.status.completionTime

# Monitor pruning
kubectl logs -n tekton-pipelines -l app=tekton-pruner-controller | grep "Deleting"

Best Practices

Development: Short TTLs (5-60 min) for rapid iteration
Production: Long TTLs (7-30 days) for audit/compliance
Critical Pipelines: Use selectors for extended retention
Balance: Consider storage costs vs. retention needs

History-based Pruning - Retain N runs regardless of age
Namespace Configuration - Per-environment TTL settings
Resource Groups - Pipeline-specific TTLs via selectors

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Namespace Configuration

Configure different pruning policies per namespace for environment-specific retention needs.

Configuration Hierarchy

Settings flow: Global → Namespace → Resource Group

Set enforcedConfigLevel: namespace in global config to enable namespace-level overrides.

Validation Boundaries

CRITICAL - System Boundaries: Create namespace-level ConfigMaps ONLY in user namespaces where PipelineRuns/TaskRuns run.

FORBIDDEN namespaces (validation will reject):

System: kube-*, openshift-*

Tekton controllers: tekton-pipelines, tekton-*

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

Method 1: Inline Namespace Specs (Centralized)

Define all namespace configs in the global ConfigMap:

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: namespace
    ttlSecondsAfterFinished: 3600  # Global fallback
    namespaces:
      dev:
        ttlSecondsAfterFinished: 300
        successfulHistoryLimit: 3
      staging:
        ttlSecondsAfterFinished: 86400
        successfulHistoryLimit: 5
      prod:
        ttlSecondsAfterFinished: 604800
        successfulHistoryLimit: 10

Method 2: Per-Namespace ConfigMaps (Self-Service)

Recommended for namespace isolation and team autonomy.

Step 1: Enable namespace-level config in global ConfigMap:

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: namespace
    ttlSecondsAfterFinished: 3600  # Fallback for namespaces without config

Step 2: Create namespace-specific ConfigMap (fixed name: tekton-pruner-namespace-spec):

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

Benefits:

Self-service for namespace owners
Independent lifecycle management
Takes priority over global config

Validation Rules

Namespace configurations are validated against limits to prevent resource exhaustion.

1. Explicit Global Limits

When the global config defines a limit, namespace configs cannot exceed it.

data:
  global-config: |
    ttlSecondsAfterFinished: 3600
    successfulHistoryLimit: 10
    namespaces:
      development:
        ttlSecondsAfterFinished: 7200   # Invalid: exceeds global limit
        successfulHistoryLimit: 5       # Valid: within global limit

2. System Default Limits

When no global limit is defined, the system enforces these maximums:

Configuration Field	System Maximum
`ttlSecondsAfterFinished`	2,592,000 seconds (30 days)
`successfulHistoryLimit`	100
`failedHistoryLimit`	100
`historyLimit`	100

Example:

data:
  global-config: |
    enforcedConfigLevel: namespace
    # No limits defined - system maximums apply    
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: tekton-pruner-namespace-spec
  namespace: my-app
data:
  ns-config: |
    ttlSecondsAfterFinished: 2592001   # Invalid: exceeds system maximum
    successfulHistoryLimit: 150        # Invalid: exceeds system maximum

3. Override Defaults

Cluster admins can set stricter limits via global config. Global limits override system defaults but cannot exceed system maximums.

data:
  global-config: |
    ttlSecondsAfterFinished: 86400     # Admin limit: 1 day
    successfulHistoryLimit: 20         # Admin limit: 20 runs
    namespaces:
      development:
        ttlSecondsAfterFinished: 3600   # Valid: within global limit
        ttlSecondsAfterFinished: 172800 # Invalid: exceeds global limit

Configuration Inheritance

Unspecified settings inherit from higher levels:

data:
  global-config: |
    enforcedConfigLevel: namespace
    ttlSecondsAfterFinished: 3600     # Global default
    successfulHistoryLimit: 5          # Global default
    namespaces:
      dev:
        ttlSecondsAfterFinished: 300   # Override TTL
        # Inherits successfulHistoryLimit: 5 from global

Selector Support

IMPORTANT: Resource selectors (matchLabels, matchAnnotations) only work in namespace-level ConfigMaps (tekton-pruner-namespace-spec), NOT in global ConfigMap’s inline namespace specs.

This works (namespace ConfigMap):

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:
            critical: "true"
        ttlSecondsAfterFinished: 2592000

This is IGNORED (inline namespace in global ConfigMap):

data:
  global-config: |
    namespaces:
      production:
        pipelineRuns:
          - selector:
            - matchLabels:
                critical: "true"

For selector-based resource groups, use separate namespace ConfigMaps (Method 2).

Common Patterns

Environment-based:

data:
  global-config: |
    enforcedConfigLevel: namespace
    namespaces:
      dev:
        ttlSecondsAfterFinished: 300
        successfulHistoryLimit: 3
      staging:
        ttlSecondsAfterFinished: 86400
        successfulHistoryLimit: 5
      prod:
        ttlSecondsAfterFinished: 604800
        successfulHistoryLimit: 10

Verification

Check namespace config:

# For inline method (global ConfigMap)
kubectl get cm tekton-pruner-default-spec -n tekton-pipelines -o jsonpath='{.data.global-config}'

# For namespace ConfigMap method
kubectl get cm tekton-pruner-namespace-spec -n <namespace> -o yaml

Monitor pruning:

kubectl logs -n tekton-pipelines -l app=tekton-pruner-controller | grep "namespace:"

Validate Configuration Against Limits:

kubectl apply -f namespace-config.yaml

# Error if limits exceeded:
# admission webhook denied: ttlSecondsAfterFinished (3000000) 
# cannot exceed system maximum (2592000 seconds / 30 days)

Best Practices

Use clear namespace naming conventions
Start with permissive limits in development
Implement stricter retention in production
Document namespace configuration decisions
Regularly review and adjust settings
Test configurations before deployment
Use namespace ConfigMaps for selector-based groups

Next Steps

Learn about Resource Groups - Selector-based configurations
Explore Time-based Pruning - TTL strategies
Review History-based Pruning - Retention limits

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

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). Selectors in global ConfigMaps are ignored by the pruner.

How It Works

Match by labels or annotations on PipelineRuns/TaskRuns
First match wins: Groups evaluated in order
Fallback: Unmatched resources use namespace or global defaults
Location: Must be in namespace ConfigMap, not global ConfigMap

Selector Types

Label selectors:

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
            tier: frontend
        ttlSecondsAfterFinished: 604800
        successfulHistoryLimit: 10

Annotation selectors:

data:
  ns-config: |
    pipelineRuns:
      - selector:
        - matchAnnotations:
            tekton.dev/release: "true"
        ttlSecondsAfterFinished: 2592000

Mixed selectors (both labels and annotations must match):

data:
  ns-config: |
    pipelineRuns:
      - selector:
        - matchLabels:
            app: myapp
          matchAnnotations:
            critical: "true"
        successfulHistoryLimit: 50

Common Patterns

By Pipeline Type:

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: |
    ttlSecondsAfterFinished: 3600
    pipelineRuns:
      - selector:
        - matchLabels:
            pipeline-type: build
        ttlSecondsAfterFinished: 300
      - selector:
        - matchLabels:
            pipeline-type: test
        ttlSecondsAfterFinished: 3600
      - selector:
        - matchLabels:
            pipeline-type: release
        ttlSecondsAfterFinished: 604800
        successfulHistoryLimit: 20

By Environment:

data:
  ns-config: |
    pipelineRuns:
      - selector:
        - matchLabels:
            env: dev
        ttlSecondsAfterFinished: 300
      - selector:
        - matchLabels:
            env: staging
        ttlSecondsAfterFinished: 86400
      - selector:
        - matchLabels:
            env: prod
        ttlSecondsAfterFinished: 604800

By Criticality:

data:
  ns-config: |
    pipelineRuns:
      - selector:
        - matchLabels:
            critical: "true"
        ttlSecondsAfterFinished: 2592000
        successfulHistoryLimit: 50
      - selector:
        - matchLabels:
            critical: "false"
        ttlSecondsAfterFinished: 3600
        successfulHistoryLimit: 3

Order Matters

First match wins - order selectors from most to least specific:

data:
  ns-config: |
    pipelineRuns:
      - selector:
        - matchLabels:
            env: prod
            critical: "true"
        ttlSecondsAfterFinished: 2592000
      - selector:
        - matchLabels:
            env: prod
        ttlSecondsAfterFinished: 604800
      - selector:
        - matchLabels:
            app: myapp
        ttlSecondsAfterFinished: 3600

Best Practices

Use namespace ConfigMaps for selector-based groups
Order selectors from most to least specific (first match wins)
Use consistent labels: app, component, env, tier
Document groups with comments above selectors
Test with sample runs before production

Advanced Configurations

Multi-tier Application

data:
  ns-config: |
    pipelineRuns:
      - selector:
        - matchLabels:
            tier: frontend
        ttlSecondsAfterFinished: 604800
        successfulHistoryLimit: 10
      - selector:
        - matchLabels:
            tier: backend
        ttlSecondsAfterFinished: 1209600
        successfulHistoryLimit: 15
      - selector:
        - matchLabels:
            tier: database
        ttlSecondsAfterFinished: 2592000
        successfulHistoryLimit: 30

Release Types

data:
  ns-config: |
    pipelineRuns:
      - selector:
        - matchLabels:
            release-type: feature
        ttlSecondsAfterFinished: 604800
      - selector:
        - matchLabels:
            release-type: hotfix
        ttlSecondsAfterFinished: 2592000
      - selector:
        - matchLabels:
            release-type: major
        ttlSecondsAfterFinished: 7776000

Labeling Your Pipelines

Add labels to PipelineRuns for grouping:

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  generateName: my-pipeline-
  labels:
    pipeline-type: release
    env: prod
    critical: "true"
spec:
  pipelineRef:
    name: my-pipeline

Verification

# Check labels on runs
kubectl get pr --show-labels

# Monitor which group matched
kubectl logs -n tekton-pipelines -l app=tekton-pruner-controller | grep "selector"

Namespace Configuration - Set up namespace ConfigMaps
Time-based Pruning - TTL strategies for groups
History-based Pruning - Retention strategies for groups

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

ConfigMap Validation

Tekton Pruner uses a ValidatingWebhook to ensure ConfigMaps meet required specifications before they are created or updated in the cluster. This document explains how the validation works and what requirements must be met.

Overview

The pruner webhook validates ConfigMaps to:

Enforce required labels and naming conventions
Prevent invalid configurations from being applied
Protect against accidental deletion of critical configs
Ensure namespace-level configs respect global boundaries

How Validation Works

The validation webhook is automatically installed with pruner and intercepts ConfigMap CREATE, UPDATE, and DELETE operations. It only validates ConfigMaps with the label app.kubernetes.io/part-of: tekton-pruner, ensuring regular ConfigMaps in your cluster are unaffected.

Validation Rules

1. Required Labels

All pruner ConfigMaps MUST have these labels:

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

Validation checks:

Both labels must be present
app.kubernetes.io/part-of must equal tekton-pruner
pruner.tekton.dev/config-type must be either global or namespace

Error example:

Invalid pruner ConfigMap labels: ConfigMap must have label app.kubernetes.io/part-of=tekton-pruner

2. Selector Restrictions

CRITICAL: Selectors (matchLabels/matchAnnotations) are ONLY supported in namespace-level ConfigMaps (tekton-pruner-namespace-spec), NOT in global ConfigMaps.

Valid - Selectors in Namespace ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: tekton-pruner-namespace-spec
  namespace: dev
  labels:
    app.kubernetes.io/part-of: tekton-pruner
    pruner.tekton.dev/config-type: namespace
data:
  ns-config: |
    pipelineRuns:
      - selector:                  # OK - This is a namespace ConfigMap
          - matchLabels:
              app: myapp
        ttlSecondsAfterFinished: 1800

Invalid - Selectors in Global ConfigMap:

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: |
    namespaces:
      dev:
        pipelineRuns:
          - selector:              # WILL FAIL VALIDATION
              - matchLabels:
                  app: myapp
        ttlSecondsAfterFinished: 1800

Error example:

Invalid pruner configuration: global-config.namespaces.dev.pipelineRuns[0]: 
selectors are NOT supported in global ConfigMap. 
Use namespace-level ConfigMap (tekton-pruner-namespace-spec) instead

Why this restriction?

Selector-based resource matching requires access to the resource’s labels/annotations at runtime
Global ConfigMaps are designed for cluster-wide defaults, not resource-specific matching
Namespace ConfigMaps provide the correct scope for dynamic resource selection

See also: Resource Groups Tutorial for selector usage examples

3. Naming Requirements

Global Config:

Name: Must be tekton-pruner-default-spec (fixed)
Namespace: Must be tekton-pipelines (or system namespace)
Label: pruner.tekton.dev/config-type: global

Namespace Config:

Name: Must be tekton-pruner-namespace-spec (fixed)
Namespace: Must be in a user namespace (NOT in system or tekton namespaces)
Label: pruner.tekton.dev/config-type: namespace

Error examples:

Global config must be named 'tekton-pruner-default-spec', got: my-custom-name

Namespace config must be named 'tekton-pruner-namespace-spec', got: pruner-config

4. Namespace Restrictions

Forbidden namespaces for namespace-level configs:

System namespaces: kube-*, openshift-*
Tekton namespaces: tekton-pipelines, tekton-*

Attempting to create a namespace-level config in these locations will be rejected.

Error example:

Invalid pruner ConfigMap configuration: wrong config-type label or namespace combination

5. Configuration Content Validation

The webhook validates configuration data including:

Time values: ttlSecondsAfterFinished must be non-negative
History limits: historyLimit, successfulHistoryLimit, and failedHistoryLimit must be non-negative and cannot exceed global maximums if enforced
Selectors (namespace ConfigMaps only): Label and annotation selectors must have valid key-value pairs; name selectors must be valid resource names

Note: Selectors (pipelineRuns, taskRuns arrays with matchLabels/matchAnnotations) are only processed in namespace-level ConfigMaps. They are ignored in global ConfigMaps.

6. Deletion Protection

The webhook prevents deletion of the global config if namespace-level configs still exist. You must delete all namespace configs before deleting the global config. Namespace configs can be deleted without restrictions.

7. Global Config Enforcement

When creating or updating namespace-level configs, the webhook fetches the global config and validates that namespace values do not exceed global maximums if defined (e.g., maxTTLSecondsAfterFinished, maxHistoryLimit).

Common Validation Errors

Missing Labels Error

ConfigMap must have labels

Solution: Add the required labels to your ConfigMap:

labels:
  app.kubernetes.io/part-of: tekton-pruner
  pruner.tekton.dev/config-type: global  # or namespace

Wrong Config Type Error

label pruner.tekton.dev/config-type must be 'global' or 'namespace', got: local

Solution: Use only global or namespace as config-type values.

Wrong Name Error

Global config must be named 'tekton-pruner-default-spec', got: tekton-pruner-config

Solution: Use the exact required name:

Global: tekton-pruner-default-spec
Namespace: tekton-pruner-namespace-spec

Exceeds Global Limit Error

Invalid pruner configuration: namespace config ttlSecondsAfterFinished (172800) exceeds global maximum (86400)

Solution: Reduce the namespace value to be within global limits, or request admin to increase global maximum.

Deletion Blocked Error

Cannot delete global config: 2 namespace config(s) still exist

Solution: Delete all namespace configs first:

kubectl delete cm tekton-pruner-namespace-spec -n dev
kubectl delete cm tekton-pruner-namespace-spec -n staging
# Then delete global config
kubectl delete cm tekton-pruner-default-spec -n tekton-pipelines

Troubleshooting

Verify Webhook Status

# Check webhook configuration
kubectl get validatingwebhookconfigurations tekton-pruner-validating-webhook

# Check webhook pod and service
kubectl get pods,svc -n tekton-pipelines -l app.kubernetes.io/component=webhook

# View webhook logs
kubectl logs -n tekton-pipelines -l app.kubernetes.io/component=webhook

Test Validation

Create an invalid ConfigMap to verify webhook is functioning:

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
  name: tekton-pruner-default-spec
  namespace: tekton-pipelines
data:
  global-config: |
    ttlSecondsAfterFinished: 300
EOF

Expected error: admission webhook denied the request: Invalid pruner ConfigMap labels

Bypassing Validation (Not Recommended)

Warning: Bypassing validation can lead to misconfigured pruner behavior and should only be done in emergency situations.

To temporarily bypass validation:

Remove the identifying label:

kubectl label cm tekton-pruner-default-spec -n tekton-pipelines \
  app.kubernetes.io/part-of-

Make necessary changes

Re-add the label:

kubectl label cm tekton-pruner-default-spec -n tekton-pipelines \
  app.kubernetes.io/part-of=tekton-pruner

Note: The pruner controller will not process ConfigMaps without proper labels.

Best Practices

Always include required labels from the start
Use exact naming conventions for global and namespace configs
Test configurations in a non-production namespace first
Check validation errors carefully - they indicate what needs to be fixed
Monitor webhook logs when rolling out new configurations
Delete namespace configs before attempting to delete global config

Getting Started - Basic configuration setup
Namespace Configuration - Namespace-level config details
Troubleshooting - General troubleshooting guide

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Tekton Pruner Metrics

This document describes the metrics exposed by the Tekton Pruner controller using OpenTelemetry. Metrics are available on port 9090 at /metrics.

The names below are the Prometheus metric names as they appear in the /metrics endpoint. The OTel SDK automatically appends _total to counters and _seconds to histograms with unit s.

Available Metrics

Counters

Metric	Description	Labels
`tekton_pruner_controller_resources_processed_total`	Total unique resources processed	`namespace`, `resource_type`, `status`
`tekton_pruner_controller_reconciliation_events_total`	Total reconciliation events	`namespace`, `resource_type`, `status`
`tekton_pruner_controller_resources_deleted_total`	Total resources deleted	`namespace`, `resource_type`, `operation`
`tekton_pruner_controller_resources_errors_total`	Total processing errors	`namespace`, `resource_type`, `error_type`, `reason`

Histograms

Metric	Description	Labels
`tekton_pruner_controller_reconciliation_duration_seconds`	Reconciliation time	`namespace`, `resource_type`
`tekton_pruner_controller_ttl_processing_duration_seconds`	TTL processing time	`namespace`, `resource_type`, `operation`
`tekton_pruner_controller_history_processing_duration_seconds`	History processing time	`namespace`, `resource_type`, `operation`
`tekton_pruner_controller_resource_age_at_deletion_seconds`	Resource age when deleted	`namespace`, `resource_type`, `operation`

Note: All metrics carry an otel_scope_name label (tekton_pruner_controller). This is informational and transparent to most PromQL queries.

Label Values

resource_type: pipelinerun, taskrun
operation: ttl, history
status: success, failed, error
error_type: api_error, timeout, validation, internal, not_found, permission

Useful Queries

Processing Rate

# Resources processed per second
rate(tekton_pruner_controller_resources_processed_total[5m])

# Deletion rate by operation
sum(rate(tekton_pruner_controller_resources_deleted_total[5m])) by (operation)

Performance

# 95th percentile reconciliation time
histogram_quantile(0.95, rate(tekton_pruner_controller_reconciliation_duration_seconds_bucket[5m]))

# Slow reconciliations (>5s)
histogram_quantile(0.95, rate(tekton_pruner_controller_reconciliation_duration_seconds_bucket[5m])) > 5

Errors

# Error rate
rate(tekton_pruner_controller_resources_errors_total[5m])

# Error ratio
rate(tekton_pruner_controller_resources_errors_total[5m]) / rate(tekton_pruner_controller_resources_processed_total[5m])

Resource State

# Current active resources
tekton_pruner_controller_active_resources

# Resources pending deletion  
tekton_pruner_controller_pending_deletions

Basic Alerts

- alert: TektonPrunerHighErrorRate
  expr: rate(tekton_pruner_controller_resources_errors_total[5m]) / rate(tekton_pruner_controller_resources_processed_total[5m]) > 0.1
  for: 5m

- alert: TektonPrunerStalled
  expr: rate(tekton_pruner_controller_resources_processed_total[10m]) == 0 and tekton_pruner_controller_active_resources > 0
  for: 10m

Configuration

Metrics are configured via the config-observability-tekton-pruner ConfigMap in the tekton-pipelines namespace. By default, Prometheus export is enabled on port 9090.

See config-observability.yaml for the full list of configuration options.

Key	Values	Default
`metrics-protocol`	`prometheus`, `grpc`, `http/protobuf`, `none`	`prometheus`
`metrics-endpoint`	OTLP endpoint (for grpc/http)	empty
`tracing-protocol`	`none`, `grpc`, `http/protobuf`, `stdout`	`none`
`tracing-endpoint`	OTLP tracing endpoint	empty

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Tekton Pruner Tutorials

Welcome to the Tekton Pruner tutorials! These guides will help you understand and configure Tekton Pruner effectively for your Kubernetes cluster.

Tutorial Guides

Getting Started
- Basic installation and configuration
- First steps with Tekton Pruner
- Simple example setup
History-based Pruning
- Understanding history limits
- Configuring successful and failed run retention
- Best practices for history-based cleanup
Time-based Pruning
- TTL-based resource cleanup
- Common TTL configurations
- Combining TTL with history limits
Namespace Configuration
- Namespace-specific settings
- Configuration inheritance
- Managing multiple environments
Resource Groups
- Grouping resources by labels and annotations
- Pipeline-specific configurations
- Advanced grouping strategies

Additional Documentation

ConfigMap Validation
- How the validation webhook works
- Required labels and naming conventions
- Common validation errors and solutions
- Deletion protection rules

Recommended Learning Path

Start with the Getting Started tutorial to set up Tekton Pruner
Learn about Time-based Pruning for basic cleanup strategies
Explore History-based Pruning for more sophisticated retention policies
Use Namespace Configuration to manage different environments
Master Resource Groups for fine-grained control

Need Help?

If you run into issues or need clarification:

Check the troubleshooting guide
Open an issue in our GitHub repository
Join our community discussions

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Troubleshooting Guide

This guide helps you diagnose and resolve common issues with Tekton Pruner.

Common Issues

1. Resources Not Being Pruned

Symptoms

PipelineRuns or TaskRuns remain after their expected deletion time
No pruning activities visible in logs

Possible Causes and Solutions

Configuration Not Applied

# Check if config exists
kubectl get configmap tekton-pruner-default-spec -n tekton-pipelines

# Verify configuration content
kubectl get configmap tekton-pruner-default-spec -n tekton-pipelines -o yaml

Controller Not Running

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

# Check controller logs
kubectl logs -n tekton-pipelines -l app=tekton-pruner-controller

Incorrect Resource Labels

# Check resource labels
kubectl get pipelineruns --show-labels

2. Unexpected Resource Deletion

Symptoms

Resources being deleted earlier than expected
Too many resources being pruned

Possible Causes and Solutions

Check TTL Configuration

# Verify TTL settings in config
kubectl get configmap tekton-pruner-default-spec -n tekton-pipelines -o jsonpath='{.data.global-config}'

Check History Limits

Ensure history limits are set appropriately
Verify resource completion status is being detected correctly

3. Permission Issues

Symptoms

Error messages about RBAC in controller logs
Unable to delete resources

Solutions

Verify RBAC Configuration

# Check ClusterRole
kubectl get clusterrole tekton-pruner-controller

# Check ClusterRoleBinding
kubectl get clusterrolebinding tekton-pruner-controller

# Check ServiceAccount
kubectl get serviceaccount tekton-pruner-controller -n tekton-pipelines

Apply Missing RBAC Rules

kubectl apply -f config/200-clusterrole.yaml
kubectl apply -f config/201-clusterrolebinding.yaml

Collecting Debug Information

1. Controller Logs

# Get recent logs
kubectl logs -n tekton-pipelines -l app=tekton-pruner-controller --tail=100

# Get logs with timestamps
kubectl logs -n tekton-pipelines -l app=tekton-pruner-controller --timestamps=true

# Follow logs in real-time
kubectl logs -n tekton-pipelines -l app=tekton-pruner-controller -f

2. Resource Status

# List PipelineRuns with details
kubectl get pipelineruns -o wide

# Get specific PipelineRun details
kubectl describe pipelinerun <pipelinerun-name>

3. Configuration Validation

# Export current config
kubectl get configmap tekton-pruner-default-spec -n tekton-pipelines -o yaml > current-config.yaml

# Compare with default config
diff current-config.yaml config/600-tekton-pruner-default-spec.yaml

Note: For detailed information about ConfigMap validation, including webhook validation rules, required labels, and common validation errors, see the ConfigMap Validation guide.

Best Practices for Troubleshooting

Start with Controller Logs
- Check for error messages
- Look for pruning activity
- Verify configuration is being read
Verify Resource State
- Check resource status
- Verify labels and annotations
- Confirm completion timestamps
Test with Simple Configuration
- Start with basic global settings
- Add complexity gradually
- Test one feature at a time
Monitor Resource Changes
- Watch resources in real-time
- Track deletion patterns
- Verify pruning behavior

Getting Help

If you’re still experiencing issues:

Search existing GitHub issues
Collect relevant logs and configuration
Open a new issue with:
- Clear description of the problem
- Steps to reproduce
- Expected vs actual behavior
- Relevant logs and configuration
- Kubernetes and Tekton versions

Tekton – Tekton resource pruning based on configuration

Docs:

Getting Started with Tekton Pruner

Prerequisites

Installation

Understanding Required Labels

Create Your First Configuration

Test the Configuration

Configuration Options

Next Steps

Docs:

History-based Pruning

How It Works

Configuration Options

Basic Configuration

Environment-specific Limits

Pipeline-specific Limits

Interaction with TTL

Verification

Best Practices

Related

Docs:

Time-based Pruning (TTL)

How It Works

Basic Configuration

Common TTL Values

Environment-specific TTLs

Pipeline-specific TTLs

Combining TTL with History Limits

Verification

Best Practices

Related

Docs:

Namespace Configuration

Configuration Hierarchy

Validation Boundaries

Method 1: Inline Namespace Specs (Centralized)

Method 2: Per-Namespace ConfigMaps (Self-Service)

Validation Rules

1. Explicit Global Limits

2. System Default Limits

3. Override Defaults

Configuration Inheritance

Selector Support

Common Patterns

Verification

Best Practices

Next Steps

Docs:

Resource Groups

How It Works

Selector Types

Common Patterns

Order Matters

Best Practices

Advanced Configurations

Multi-tier Application

Release Types

Labeling Your Pipelines

Verification

Related

Docs:

ConfigMap Validation

Overview

How Validation Works

Validation Rules

1. Required Labels

2. Selector Restrictions

3. Naming Requirements

4. Namespace Restrictions

5. Configuration Content Validation

6. Deletion Protection

7. Global Config Enforcement

Common Validation Errors

Missing Labels Error

Wrong Config Type Error

Wrong Name Error

Exceeds Global Limit Error

Deletion Blocked Error

Troubleshooting