Alauda DevOps Pipelines Docs

Namespace Configuration

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

TOC

Configuration HierarchyValidation BoundariesMethod 1: Inline Namespace Specs (Centralized)Method 2: Per-Namespace ConfigMaps (Self-Service)Validation Rules1. Explicit Global Limits2. System Default Limits3. Override DefaultsConfiguration InheritanceSelector SupportCommon PatternsBest PracticesNext Steps

Configuration Hierarchy

Settings flow: Global → Namespace → Resource Group

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

Validation Boundaries

WARNING

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

FORBIDDEN namespaces (validation will reject):

  • System: kube-*
  • 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>
WARNING

Namespace-level ConfigMaps are outside the TektonConfig lifecycle. If you need to back up or restore Tekton configuration later, save these ConfigMaps separately.

Method 1: Inline Namespace Specs (Centralized)

Define all namespace configs in the TektonConfig:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pruner:
    disabled: true  # Must disable job-based pruner
  tektonpruner:
    disabled: false  # Enable event-based pruner
    global-config:
      enforcedConfigLevel: namespace
      ttlSecondsAfterFinished: 604800  # Global default and upper bound for the namespaces below
      namespaces:
        dev:
          ttlSecondsAfterFinished: 300
          successfulHistoryLimit: 3
        staging:
          ttlSecondsAfterFinished: 86400
          successfulHistoryLimit: 5
        prod:
          ttlSecondsAfterFinished: 604800
          successfulHistoryLimit: 10

Inline namespaces entries are validated against the root-level global-config values in the same way as per-namespace ConfigMaps: a namespace value cannot exceed the corresponding global value, regardless of enforcedConfigLevel. See Validation Rules.

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

Recommended for namespace isolation and team autonomy.

Step 1: Enable namespace-level config in TektonConfig:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pruner:
    disabled: true  # Must disable job-based pruner
  tektonpruner:
    disabled: false  # Enable event-based pruner
    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.

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pruner:
    disabled: true  # Must disable job-based pruner
  tektonpruner:
    disabled: false  # Enable event-based pruner
    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 FieldSystem Maximum
ttlSecondsAfterFinished2,592,000 seconds (30 days)
successfulHistoryLimit100
failedHistoryLimit100
historyLimit100

Example:

spec:
  tektonpruner:
    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. When a global value is set, it replaces the system maximum as the upper bound for namespace configs. The global values themselves are not checked against the system maximums.

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pruner:
    disabled: true  # Must disable job-based pruner
  tektonpruner:
    disabled: false  # Enable event-based pruner
    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 example: exceeds global limit

Configuration Inheritance

Unspecified settings inherit from higher levels:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pruner:
    disabled: true  # Must disable job-based pruner
  tektonpruner:
    disabled: false  # Enable event-based pruner
    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):

spec:
  tektonpruner:
    global-config:
      namespaces:
        production:
          pipelineRuns:
            - selector:
                matchLabels:
                  critical: "true"

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

Common Patterns

Environment-based:

spec:
  tektonpruner:
    global-config:
      enforcedConfigLevel: namespace
      namespaces:
        dev:
          ttlSecondsAfterFinished: 300
          successfulHistoryLimit: 3
        staging:
          ttlSecondsAfterFinished: 86400
          successfulHistoryLimit: 5
        prod:

Best Practices

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

Next Steps