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.
TOC
OverviewHow Validation WorksValidation Rules1. Required Labels2. Selector Restrictions3. Naming Requirements4. Namespace Restrictions5. Configuration Content Validation6. Deletion Protection7. Global Config EnforcementCommon Validation ErrorsMissing Labels ErrorWrong Config Type ErrorWrong Name ErrorExceeds Global Limit ErrorDeletion Blocked ErrorTroubleshootingVerify Webhook StatusTest ValidationChanging a Pruner ConfigMapBest PracticesOverview
The pruner webhook validates ConfigMaps to:
- Enforce required labels and naming conventions
- Prevent invalid configurations from being applied
- Block deleting a global config that namespace configs depend on, unless the Tekton Operator manages it (see Deletion Protection)
- Check namespace-level configs against the global limits when they are created or updated (see Global Config Enforcement)
How Validation Works
The validation webhook is automatically installed with pruner and intercepts ConfigMap CREATE, UPDATE, and DELETE operations. It only validates ConfigMaps that carry both labels app.kubernetes.io/part-of: tekton-pruner and pruner.tekton.dev/config-type (global or namespace), ensuring regular ConfigMaps in your cluster are unaffected.
Validation Rules
1. Required Labels
Set these labels on every pruner ConfigMap. The webhook validates only ConfigMaps that carry them; an unlabeled namespace ConfigMap is still applied by the Pruner, but without any validation:
Validation checks (they can deny only an update of a ConfigMap that the webhook validates, because a ConfigMap created without both labels is not sent to the webhook):
- Both labels must be present
app.kubernetes.io/part-ofmust equaltekton-prunerpruner.tekton.dev/config-typemust be eitherglobalornamespace
Error example:
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:
Invalid - Selectors in Global ConfigMap:
Error example:
See also: Resource Groups for selector usage examples
3. Naming Requirements
Global Config:
- Name: Must be
tekton-pruner-default-spec(fixed) - Namespace: Must be the namespace set by
TektonConfigspec.targetNamespace(tekton-pipelinesby default) - Label:
pruner.tekton.dev/config-type: global
Namespace Config:
- Name: Must be
tekton-pruner-namespace-spec(fixed) - Namespace: Must be a user namespace; see Namespace Restrictions for the namespaces that the webhook rejects
- Label:
pruner.tekton.dev/config-type: namespace
Error examples:
4. Namespace Restrictions
Namespaces where namespace-level configs are rejected: tekton-pipelines, tekton-operator and every namespace whose name starts with kube- or openshift-. The webhook is not called for kube-system, kube-public and kube-node-lease, and it does not check other tekton-* namespaces, so keep namespace-level configs out of those yourself.
Error example:
5. Configuration Content Validation
The webhook validates configuration data including:
- Time values: the namespace-wide
ttlSecondsAfterFinishedmust be non-negative. AttlSecondsAfterFinishedinside apipelineRuns/taskRunsentry is not checked, so a negative value there is accepted. - History limits: the namespace-wide
historyLimit,successfulHistoryLimitandfailedHistoryLimitmust be non-negative and are checked against the global values (see Global Config Enforcement). InsidepipelineRuns/taskRunsentries each value must be non-negative; only the sums of the selector entries' values are bounded (see Pipeline-specific Limits), and the history limits of anameentry are not bounded. - Selectors and names (namespace ConfigMaps only): not validated. The webhook accepts any
matchLabels/matchAnnotationskey and anynamein apipelineRuns/taskRunsentry, so check them yourself. - Unknown keys: not reported. The webhook and the Pruner ignore keys they do not know, so a misspelled key such as
successfulHistoryLimtis accepted and logged asConfigMap validation successful, and the field it was meant to set stays unset, with the same effect as leaving it out. - A
global-configkey in a namespace ConfigMap: the webhook then checks only that key, as a global config, and notns-config, while the Pruner reads onlyns-configfrom a namespace ConfigMap. Do not add aglobal-configkey to a namespace ConfigMap.
So an accepted dry run or a ConfigMap validation successful line does not show that every key was recognized.
Note: Selectors (pipelineRuns / taskRuns entries with matchLabels / matchAnnotations) work only in namespace-level ConfigMaps. In the global config, a selector under namespaces.<namespace> is rejected: the pruner webhook denies the ConfigMap, and the Tekton Operator webhook denies the same entry in TektonConfig spec.tektonpruner.global-config.
6. Deletion Protection
The webhook prevents deletion of the global config while namespace-level configs still exist, unless the global config is owned by a TektonInstallerSet, that is, managed by the Tekton Operator: the webhook always allows deleting that ConfigMap. It allows deleting a namespace config named tekton-pruner-namespace-spec in a namespace where Namespace Restrictions allows namespace configs.
The label, name and namespace checks above also run on a DELETE request, before these rules. So, while the event-based Pruner is enabled, the webhook denies deleting a ConfigMap that carries both required labels with pruner.tekton.dev/config-type: namespace when it has another name or is in tekton-pipelines, tekton-operator or a namespace whose name starts with kube- or openshift- (other than kube-system, kube-public and kube-node-lease, for which the webhook is not called). It also denies deleting a ConfigMap in tekton-pipelines that carries both required labels with pruner.tekton.dev/config-type: global and another name than tekton-pruner-default-spec, and removing the labels of such ConfigMaps (see Changing a Pruner ConfigMap). Such ConfigMaps can exist, for example when they were created while the event-based Pruner was disabled.
7. Global Config Enforcement
When a namespace-level config is created or updated, the webhook fetches the global config and checks the namespace-wide values against its root values (the inline namespaces.<namespace> entry is used only for the bounds of the selector sums):
ttlSecondsAfterFinishedagainst the globalttlSecondsAfterFinished, else against the system maximum of 30 days.successfulHistoryLimitagainst the globalsuccessfulHistoryLimit, else the globalhistoryLimit, else the system maximum of 100.failedHistoryLimitis checked the same way with the failed fields.historyLimitonly against the globalhistoryLimit, else 100. A globalsuccessfulHistoryLimitorfailedHistoryLimitdoes not bound it, although a namespacehistoryLimitapplies to both statuses when the namespace config does not set the specific limits.
These maximums are built-in constants, not configurable keys.
Common Validation Errors
The two label errors below appear only when you change the labels of a ConfigMap that the webhook validates. A ConfigMap created without both labels, or with another pruner.tekton.dev/config-type value, is not sent to the webhook and is stored without a check (see Changing a Pruner ConfigMap).
Missing Labels Error
Solution: Add the required labels to your ConfigMap:
Wrong Config Type Error
Solution: Use only global or namespace as config-type values.
Wrong Name Error
Solution: Use the exact required name:
- Global:
tekton-pruner-default-spec - Namespace:
tekton-pruner-namespace-spec
Exceeds Global Limit Error
Solution: Reduce the namespace value to be within global limits, or request admin to increase global maximum.
Deletion Blocked Error
This error does not occur when the Tekton Operator manages the Pruner: the operator owns the global config (owner kind TektonInstallerSet), and the webhook always allows deleting it. To change the global values, use TektonConfig instead of deleting the ConfigMap (see Changing a Pruner ConfigMap).
A global config without that owner cannot be deleted while namespace configs exist:
Solution: Delete the namespace configs listed in the message first. They belong to the teams of those namespaces, so agree with those teams first:
Troubleshooting
Verify Webhook Status
These commands need read access to cluster-scoped webhook configurations and to Pods and their logs in tekton-pipelines, usually a cluster administrator. tekton-pipelines is the default of TektonConfig spec.targetNamespace; replace it in the commands on this page if your installation uses another namespace.
Test Validation
Send an invalid namespace-level ConfigMap to the API server with --dry-run=server, in a new test namespace. The ConfigMap carries both required labels, so the webhook validates it, and the dry run stores nothing. The namespace name gets a unique suffix, and the remaining commands run only if kubectl create namespace succeeds, so an existing namespace is never deleted. Creating and deleting a namespace needs permission on the cluster-scoped namespaces resource, usually a cluster administrator; a namespace owner can run the same dry run in their own namespace instead (practice 3 under Best Practices):
Expected result: the request is denied by the pruner validation webhook because ttlSecondsAfterFinished is negative. kubectl prints the webhook message after its own prefix:
If the dry run reports the ConfigMap as created, the webhook is not validating. The most likely cause is that the event-based Pruner is disabled, which is the Operator default (spec.tektonpruner.disabled: true in TektonConfig): the webhook configuration exists only while it is enabled, so the first command of Verify Webhook Status reports NotFound. Enabling the Pruner deletes runs at once: before you enable it, read the warning in Recommended Settings of Namespace Configuration and follow the steps there. The steps that enable the Pruner are in Tekton Pruner Is Not Deployed.
Changing a Pruner ConfigMap
The webhook also validates updates, so it denies removing the app.kubernetes.io/part-of label from a ConfigMap that it validates:
It does not check a namespace ConfigMap that is created without the two labels, even one that replaces a deleted ConfigMap that it validated. The Pruner still applies such a ConfigMap (see Required Labels).
When the Tekton Operator manages the Pruner, change the global values in TektonConfig under spec.tektonpruner.global-config. The operator updates tekton-pruner-default-spec, and the webhook checks the namespace configs that are created or updated afterwards against the new values. It does not re-check existing namespace configs: a namespace config with a value above a lowered global value keeps that value, and the Pruner applies it as it is. List the namespace configs and their ns-config values with kubectl get configmaps -A --field-selector metadata.name=tekton-pruner-namespace-spec -o yaml and lower such values yourself. The new global values apply at once to the completed runs that use them, in every namespace except tekton-pipelines, tekton-operator and those whose names start with kube- or openshift-, and a lower limit deletes runs right away. Read the current values first:
For example, to set the global historyLimit:
Then confirm that the operator wrote the new value into the Pruner's global ConfigMap; the output must contain historyLimit: 200:
These steps need permission to patch the cluster-scoped TektonConfig and to read ConfigMaps in tekton-pipelines, usually a cluster administrator.
Best Practices
- Always include required labels from the start
- Use exact naming conventions for global and namespace configs
- Test a ConfigMap with a server dry run first, as in Test Validation above. A dry run that reports the ConfigMap as created shows only that nothing denied it. To see that the webhook checks ConfigMaps in a namespace, send a copy in which the top-level
ttlSecondsAfterFinishedofns-configis set to-1, replacing any existing value, to that namespace the same way: it must be denied as in Test Validation; if it is reported as created, the webhook did not check it. A namespace owner can do this in their own namespace before creating the ConfigMap there. A cluster administrator can also look for the log lines of practice 5 - Fix one error at a time: the webhook reports only the first violation, so run the dry run again after each fix until it passes
- Check the webhook log when rolling out new configurations (commands and the permissions they need in Verify Webhook Status): when the webhook checks the content of a ConfigMap, it logs
Validating pruner ConfigMap, thenConfigMap validation successfulorConfigMap validation failed, with the name and namespace of the ConfigMap. Each checked request writes several lines, so use the log command with--tail=-1. If these lines are missing for a ConfigMap in log output that covers the time of the change, its content was not checked; the output covers only the time since the webhook container started. AConfigMap validation successfulline does not show that every key was recognized (see Configuration Content Validation) - Change global values through
TektonConfigwhen the Tekton Operator manages the Pruner, instead of deletingtekton-pruner-default-spec