Constrain Tekton Pipeline Execution with Kyverno
Use Kyverno to answer questions such as: "May teams run their own Tasks?", "Which template must they use?", and "Which tool images may execute?" A Task defines steps; a Pipeline connects Tasks; TaskRuns and PipelineRuns execute those definitions. Kyverno checks their Kubernetes API requests against rules written by a platform administrator.
It can check the object submitted to the Kubernetes API, the Pod created for a TaskRun, and selected fields written to a completed run. It does not replace Tekton's execution semantics or prove what an arbitrary shell command will do.
This guide is a capability map with generic examples. The values in angle brackets are intentional placeholders. Replace them with values owned by your platform team before applying a policy. For a concrete CI scenario, see Constrain Catalog Pipeline Usage with Kyverno. That companion page uses a Pipeline delivered by ArtifactHub Shim and shows how to turn these generic controls into practical restrictions on user configuration, parameters, and scan results. The design rationale is in Pipeline Policy Constraints with Tekton and Kyverno.
TOC
What can be constrainedPrerequisitesRead and install a policy1. Close inline and direct-run bypasses2. Require a reviewed resolver reference3. Limit the images that can execute4. Audit what a completed run reportsRoll out and make exceptions safelySelf-validationTroubleshootingRecommended SettingsRelated documentationWhat can be constrained
Kyverno sees different objects at different points in a Tekton execution. Choose the object that contains the fact you want to govern.
The timing matters. A resolver reference is available when a PipelineRun is admitted,
but the fetched Pipeline and its labels are not guaranteed to be available yet. A user
can also submit a label that looks like a platform label. Use resolver parameters for an
admission decision and labels or results for post-execution audit.
The lifecycle is: run admission, remote resolution, child TaskRun admission, Pod admission,
then status updates. A remotely fetched Task or Pipeline is not stored as a Kubernetes
object, but Tekton validates a fetched Pipeline with a server-side dry-run in the run's
namespace, so Pipeline policies there also see the fetched YAML, and a denial fails the
run. A child TaskRun's reference is visible at its admission, but a remote Task's body may
still be unresolved. Pod admission sees the resolved container configuration.
Kyverno is one layer in the control; combine it with these steps:
- Use RBAC to decide who may create or update Tekton objects.
- Use the operator's inline-spec feature flag for a cluster-wide baseline only when every
namespace follows the same rule. The flag rejects inline specs in every namespace,
including the runs that PAC creates from a
.tekton/file with an inlinepipelineSpecand, with the default PAC settingremote-tasks: "true", the runs into which PAC embeds a resolved Pipeline or Task. With that default, only PAC runs that reference their Pipeline throughpipelineRef.resolverare not rejected for an embeddedpipelineSpec; see the warning in section 1. - Keep catalog and Pipeline sources under review.
- Keep image registries available in an air-gapped cluster.
No single policy provides template integrity by itself.
Prerequisites
- Tekton Pipelines and its validating webhook are installed and configured to fail closed for invalid Tekton resources.
- Kyverno admission, background, and reports controllers are Ready. The examples were
verified with Kyverno engine 1.15.9 and Tekton
v1resources. This guide uses thekyverno.io/v1ClusterPolicyAPI and thekyverno.io/v2PolicyExceptionAPI. - You can create policies and, if your exception process permits it, narrowly scoped
PolicyExceptionobjects. - The governed namespace, resolver catalog, and internal image registries are known.
- In an air-gapped cluster, install Kyverno, resolver configuration, policy YAML, and all referenced images from an approved offline repository.
Start with Audit and match one disposable namespace. The namespace match limits where the
policy is evaluated, not where Kyverno's webhook is called: each ClusterPolicy registers
its resource kinds in Kyverno's shared validating webhook (validate.kyverno.svc-fail) for
the whole cluster, also in Audit mode. While the Kyverno admission controller is
unavailable, the API server rejects the requests for those kinds in every namespace that
Kyverno's global settings do not exclude, including the Pods and Tekton runs of other teams.
Move a policy to Enforce only after its
match scope and legitimate exceptions are understood. background: false is used below
because these examples are intended to evaluate admission or status updates rather than
rewrite history. The examples are opt-in policies, not installed product defaults.
Read and install a policy
The policy-level spec.validationFailureAction is deprecated and will be removed in a
future Kyverno release. Use spec.rules[].validate.failureAction as shown below; see
Kyverno validation rules.
When migrating an older policy, move its action into every validation rule and remove
the policy-level field.
Put each complete policy below in its own YAML file, replace its placeholders, and first
set validate.failureAction: Audit on every rule. For example, save the first policy as
tekton-no-inline-execution-specs.yaml and, after changing all four of its rules, run:
Use the same apply/wait procedure for the other policies. A Ready policy alone is not
proof that it matches a run: execute the positive and negative checks below.
1. Close inline and direct-run bypasses
Use case: require work to enter through a reviewed Pipeline and prevent a user from
embedding a taskSpec or pipelineSpec in a run or definition.
Enforcement point: admission on TaskRun create requests and PipelineRun or
Pipeline create/update requests. A denied request never reaches a Tekton controller.
The PipelineRun and Pipeline rules list CREATE and UPDATE under operations in
match. Without this list, Kyverno also evaluates these deny rules when an object is
deleted, against the object that is being deleted. An object that passes the rule can still
be deleted, but the deletion of an object that violates the rule is denied, for example a
PipelineRun that was admitted while the rule was in Audit or before the policy existed.
The Pruner deletes runs through the same API request, so its deletion of such a run is
denied in the same way.
The standalone TaskRun rule lists only CREATE under operations in match and checks
only CREATE. Without this list, Kyverno registers the UPDATE and DELETE operations on
TaskRuns in its shared webhook as well, for the whole cluster. The Tekton controller
ServiceAccount is excluded because it creates child TaskRuns for an accepted PipelineRun. Change the
ServiceAccount and namespace when the cluster uses a customized Tekton installation. This
is an authenticated request identity, not spec.serviceAccountName or an owner label that
a user can supply. RBAC must prevent users from impersonating this identity or running
their own Pods under it. Do not extend this rule to UPDATE: the tekton-results-watcher
and tekton-chains-controller components update TaskRun metadata and finalizers on the
main resource, so denying those updates can stop result storage, signing, and finalizer
removal.
An EventListener and the ScheduledTrigger controller create the resources of their
TriggerTemplate, and their requests do not come from the Tekton controller ServiceAccount.
This rule therefore also rejects a TaskRun that such a template holds. A template that
holds a PipelineRun is not affected, because the Tekton controller creates its child
TaskRuns. The EventListener still answers the event with HTTP 202, and the denial is in
the log of the EventListener Pod; a ScheduledTrigger records it in a FailedCreate warning
event. If another trusted component must create TaskRuns, add its ServiceAccount to the
narrow exclusion as well.
Tekton also has an operator-managed baseline, the disable-inline-spec setting. On a
default installation, TektonConfig owns the TektonPipeline resource named pipeline and
copies its own spec.pipeline into it, so set the value in
spec.pipeline.disable-inline-spec of TektonConfig with the merge patch below.
disable-inline-spec is a cluster-wide setting. With the value below, the Tekton webhook
rejects, in every namespace:
- every
PipelineRunwith an embeddedpipelineSpec. This includes the runs that PAC creates from a.tekton/file with an inlinepipelineSpecand, with the default PAC settingremote-tasks: "true", the runs into which PAC embeds a resolved Pipeline or Task (PAC embeds them for apipelineRefortaskRefwithoutresolver; see PAC Resolver). With that default, only PAC runs that reference their Pipeline throughpipelineRef.resolverare not affected by this check; - every
TaskRunwith an embeddedtaskSpec, including the TaskRuns that the PipelineRun controller creates for a Pipeline task that defines its Task inline withtaskSpec; - every
Pipelinewhose tasks definetaskSpecorpipelineSpecinline.
A PipelineRun that is already running is affected too. With pipeline in the value, as
below, the controller checks the run's Pipeline again at its next reconcile: if a task
defines taskSpec or pipelineSpec inline, the run fails with the reason
PipelineValidationFailed and the message
[User error] Pipeline <namespace>/<name> can't be Run; it has an invalid spec: .... With
taskrun in the value but not pipeline, the run fails with the reason CreateRunFailed when it
reaches a task with an inline taskSpec, because its TaskRun cannot be created.
Read the current value first
(kubectl get tektonconfig config -o jsonpath='{.spec.pipeline.disable-inline-spec}').
To undo the change, remove the field; an empty value allows inline specs again:
If the field had a value before your change, set that value again instead. For a
TektonPipeline that TektonConfig does not own, remove disable-inline-spec from its
spec in the same way.
Set the value with a merge patch. It needs permission to patch TektonConfig, which is
cluster-scoped, usually a cluster administrator:
For a TektonPipeline that TektonConfig does not own, set the field in its spec
instead. The following is a configuration fragment for that existing TektonPipeline, not
a new installation:
To confirm that the value is in effect, read it from the feature-flags ConfigMap in
tekton-pipelines, which the Operator writes and the Tekton webhook reads.
tekton-pipelines is the default of TektonConfig spec.targetNamespace; replace it in the
commands if your installation uses another namespace. Reading the ConfigMap needs
read access to ConfigMaps in tekton-pipelines, usually a cluster administrator:
The output must be the value that you set, such as taskrun,pipelinerun,pipeline. An empty
output means that inline specs are still allowed.
The feature flag is useful when every namespace follows the same rule. Kyverno is useful
when rollout scope, denial messages, PolicyReports, or exceptions matter. The flag does
not create a policy report and neither option replaces RBAC.
The flag prohibits inline specs, but it does not prohibit a standalone TaskRun using
taskRef. A Kyverno PolicyException cannot bypass the Tekton feature flag.
2. Require a reviewed resolver reference
Use case: require every governed PipelineRun to identify a remote Pipeline through
the hub resolver. The first rule checks only the reference shape; a second policy limits
the reference to reviewed name@version pairs.
Enforcement point: PipelineRun admission. This rule does not inspect the remote
Pipeline body. Both rules of this section list CREATE and UPDATE under operations,
for the reason given in section 1.
Add a second policy that allows only reviewed name@version pairs. Catalog-specific pairs
can live in the Catalog guide, but that guide does not include such a list today. A minimal
rule:
List every reviewed pair under value. A reference whose name@version is not listed is
denied with the policy message, while a listed pair is admitted.
3. Limit the images that can execute
Use case: prevent a resolved Task from starting with an image outside approved registries. This is the first point at which every resolved step image is visible.
Enforcement point: Pod admission, before the Task starts. The list must include
Tekton helper images and any platform-injected init image as well as the main tool images.
Replace both registry hosts in both expressions with your actual approved hosts. Escape
literal dots and retain the trailing / so look-alike registry names cannot match.
The selector keeps unrelated application Pods out of the policy evaluation, but not out of
Kyverno's webhook: Kyverno registers Pod requests for the whole cluster, so while its
admission controller is unavailable, the API server rejects Pod creation in every namespace
that Kyverno's global settings do not exclude (see Prerequisites). A
dedicated pipeline namespace is often simpler. Inspect a server-side dry run before switching to Enforce
because an admission webhook can inject an internal helper image after the submitted Pod
template is rendered.
This policy checks executable images, not build output destinations, images pulled inside
a build step, image signatures, or arbitrary network traffic. Use parameter policies,
registry permissions, and network controls for those concerns. Restrict direct Pod
creation with RBAC; users who can create unlabelled Pods can avoid this selector.
4. Audit what a completed run reports
Use case: detect a missing or unexpected template label after a resolver has finished, without treating a user-controlled label as an admission identity.
Enforcement point: PipelineRun/status updates. The rule is Audit; it never blocks
the initial PipelineRun request. Kyverno cannot use background scans for a status
subresource, so this records new status changes rather than historical runs.
Kyverno makes the audited PipelineRun the owner of its PolicyReport, so the report is
deleted together with the run, whether kubectl delete or the Pruner removes the run. Save
the reports while the runs exist (for example with
kubectl get policyreport -n <governed-namespace> -o yaml), or keep the runs for as long as
the audit needs them.
A passing label check is a consistency signal, not proof of provenance: a manually supplied
label remains forgeable even after completion. Never use Enforce on a result rule to try
to stop work that has already happened; rejecting controller status writes can leave runs
stuck without undoing their effects.
For status rules, check reports-controller permissions explicitly:
If policy installation reports missing permissions, an administrator can grant the
following read-only access in the governed namespace. It also covers the companion
Catalog TaskRun audit. Replace every placeholder first; both the Role and RoleBinding
must keep metadata.namespace: <governed-namespace> so that the binding references the
Role in the same namespace. Apply the Role and RoleBinding before the status policies:
Replace <template-label-key> and <approved-template-label-value> with a label key and
value that your approved Pipelines set in metadata.labels. When Tekton resolves the Pipeline
of a run, it copies the Pipeline's labels to the PipelineRun; a label key that the
PipelineRun already sets keeps the run's own value, except tekton.dev/pipeline, which
Tekton sets to the name of the resolved Pipeline.
Use a similar TaskRun/status policy for task results. Result names and value formats are
Task-specific; do not invent a common result contract. The Catalog guide demonstrates the
real sonarqube-scanner and trivy-scanner contracts for one Pipeline version.
Roll out and make exceptions safely
-
Set every rule's
validate.failureActiontoAudit, install the policy in a disposable namespace, and inspectPolicyReport. -
Create both a valid object and an intentional violation. A missing report can mean the rule did not match, so check the namespace, GVK, and preconditions.
-
For each admission policy, change every rule's
validate.failureActiontoEnforce, starting with the narrowest namespace. Keep status audit rules inAudit. -
Keep an exception that names one policy, one rule, one namespace, and one resource.
-
Give the exception an owner and expiry. Existing objects are not retroactively rejected, but updates and newly created child objects can be.
Do not grant a cluster-wide wildcard exception. Kyverno must be configured to allow
PolicyException resources. Configure the Kyverno admission controller (or the equivalent
chart values) with both --enablePolicyException=true and
--exceptionNamespace=<exception-namespace>. In Kyverno 1.15, enabling the feature without
an allowed namespace, or creating the object in a different namespace, produces an
admission warning but still stores the PolicyException; the exception selector does not
use it, so it has no effect. Configure the allowed namespace first and create the object
there, then treat any admission warning as a failed exception setup. RBAC must also
restrict who can create exceptions. The allowed exception namespace can differ from the
matched run namespace. Expiry is a review/deletion process unless your platform separately
automates it; the resource above has no automatic TTL. An exception skips only its named
rules, not other policies matching the same run.
By default, Kyverno allows updates that preserve a pre-existing violation. Set
validate.allowExistingViolations: false on a rule if those updates must also be denied,
after assessing the effect on running workloads. Keep status audit policies in Audit.
Self-validation
Run these checks in a disposable namespace after replacing the placeholders. Set every
rule's validate.failureAction in the policies of sections 1 to 3 to Enforce, leaving the
label audit rule in Audit. Test this generic set before installing the name@version
allowlist policy of section 2 or the Catalog-specific policies; otherwise those additional
rules must also allow each positive request. Server dry runs exercise admission without starting
builds or pulling images. They do not create persistent PolicyReports.
Additional checks for the same policies:
For a real status audit, submit a deliberately nonexistent template to the configured local catalog. This does not execute a Task or need an external image. It should be admitted, then fail remote resolution and generate a missing-label audit:
Allow the reports controller time to reconcile. Find a fail result for
completed-run-has-template-label on this run. Tekton's resolution failure is separate
from the audit; Kyverno did not deny the request. For the passing case, run an approved
template that propagates the configured label and check for pass instead. A result in
error, or no matching result, does not prove compliance.
After testing, delete only the example runs, policies, exception, Role and RoleBinding you created. Delete the namespace only if it is disposable. Do not remove shared policies.
Troubleshooting
- A child TaskRun create is rejected for the controller. Add the actual Tekton controller
ServiceAccount to the rule exclusion; do not exempt the whole namespace. Metadata updates
from
tekton-results-watcherortekton-chains-controllerare intentionally outside this create-only rule. - An EventListener or a ScheduledTrigger does not create its TaskRun. The standalone
TaskRunrule rejects aTaskRunthat a TriggerTemplate holds. The EventListener still answers with HTTP202and logs the denial in its Pod; a ScheduledTrigger shows aFailedCreatewarning event. Change the template so that it creates aPipelineRun. - A resolver-shaped run is rejected. Resolver parameters must be separate entries with
the exact names
catalog,type,kind,name, andversion. Runtime Pipeline parameters belong underspec.params. - A Pod is rejected after the PipelineRun passed. Pod admission sees the final resolved image list. Add every approved helper registry or create a narrow exception.
- An Audit rule has no report. Check the status subresource match, terminal-condition precondition, reports-controller permissions, and the resource's namespace.
- An existing violation remains. Admission does not rewrite history. Use reports or update the object through the approved path.
Recommended Settings
When to enable. Enable the standalone TaskRun rule to reject TaskRun create
requests from any identity other than the Tekton Pipelines controller, so that users cannot
create a TaskRun directly. The rule checks who sends the request, not whether a
PipelineRun owns the TaskRun. This rule alone
does not constrain what a run executes: a user who can create a PipelineRun can still
embed a pipelineSpec or reference any Pipeline through a resolver. To restrict which
Pipelines a run may use, also enable the inline-spec rules in section 1 and the resolver
rules in section 2 (the reference-shape rule plus the name@version allowlist). The
resolver rules check the reference, not the remote Pipeline body: the steps that run are
those of the named versions in whichever Hub the reference resolves to. Tekton validates a
fetched Pipeline with a server-side dry-run in the run's namespace, so the section-1
Pipeline rules also apply to it: a fetched Pipeline with an inline taskSpec fails the
run with PipelineValidationFailed. The reference-shape rule
only requires a non-empty catalog and does not reject a request-level url parameter,
which the hub resolver uses in place of its configured Hub. To tie the steps to the
platform catalog, also pin catalog to the platform catalog name and reject a
request-level url, as the policy in the Catalog guide
Constrain Catalog Pipeline Usage with Kyverno does; then review the
content of the allowed catalog versions and limit the images that execute (section 3).
RBAC grants who may create runs;
Kyverno can still reject a create request that RBAC allows.
Recommended values. Deny TaskRun create requests that do not come from the Tekton
controller ServiceAccount (the deny-standalone-taskrun rule in section 1). The rule also
rejects a TaskRun that an EventListener or a ScheduledTrigger creates from its
TriggerTemplate, so let such templates create a PipelineRun. If another
trusted component must create TaskRuns, add its ServiceAccount to the narrow exclusion; the
request.userInfo pattern is shown in
Pipeline Policy Constraints with Tekton and Kyverno.
Start every rule with failureAction: Audit, review the PolicyReport results, and
switch to Enforce as described in
Roll out and make exceptions safely.
The inline-spec rules in section 1 are optional. The
deny-pipelinerun-inline-pipelinespec rule rejects every PipelineRun that carries a
pipelineSpec. This includes the runs that PAC creates from a .tekton/ file with an
inline pipelineSpec (see
Define the Pipeline Inline with pipelineSpec)
and, with the default PAC setting remote-tasks: "true", the runs into which PAC embeds
a resolved Pipeline or Task (see
PAC Resolver). Enable the
inline-spec rules only in namespaces whose runs reference their Pipeline through
pipelineRef.resolver.
To confirm that the policies work, run the checks in Self-validation.
To undo a policy, set every rule's validate.failureAction in its file back to Audit and
apply the file again; the rules then allow violations and only record them. A policy in
Audit still registers its resource kinds in Kyverno's webhook (see
Prerequisites). To remove it completely, delete the ClusterPolicy, for
example kubectl delete clusterpolicy tekton-no-inline-execution-specs. Changing or
deleting a ClusterPolicy needs permission on this cluster-scoped object, usually a
cluster administrator.
Prerequisites. The items in Prerequisites are met, and the identities that legitimately create runs are known.
Related documentation
- Constrain Catalog Pipeline Usage with Kyverno — a concrete CI example for limiting user configuration on the delivered Java Pipeline, including Catalog-specific parameters and result fields.
- Pipeline Policy Constraints with Tekton and Kyverno — design rationale and control boundaries.
- Tekton Hub resolver concepts — resolver behavior and reference syntax.
- Comply with Pod Security Restricted Standard — Pod security context requirements.
- Tekton Chains verification guides — signing, SBOM, and vulnerability verification, which are separate from the execution policies here.