Tekton – Installation

Docs: Local Kubernetes cluster

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

There are several tools to run a local Kubernetes cluster on your computer. The Tekton documentation often includes instructions for either minikube or kind.

See the corresponding minikube and kind documentation to learn how to install and set up a cluster on your computer.

You can find some additional resources on the Tekton repositories:

Instructions to run both tools with a local registry are available on the Pipelines repository.
You can find some convenience scripts to run Tekton components with kind on the plumbing repository.

Docs: Install Tekton Pipelines

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

This page includes content about running Tekton with specific platforms and cloud providers. The accuracy and freshness of this vendor documentation varies by vendor.

If you want to contribute with platform-specific documentation, follow the vendor contributions guidelines.

This guide explains how to install Tekton Pipelines.

Prerequisites

A Kubernetes cluster running version 1.28 or later.
Kubectl.
Grant cluster-admin privileges to the current user. See the Kubernetes role-based access control (RBAC) docs for more information.
(Optional) Install a Metrics Server if you need support for high availability use cases.

See the local installation guide if you want to test Tekton on your computer.

Installation

To install Tekton Pipelines on a Kubernetes cluster:

Run one of the following commands depending on which version of Tekton Pipelines you want to install:
- Latest official release:
```
kubectl apply --filename https://infra.tekton.dev/tekton-releases/pipeline/latest/release.yaml
```
  Note: These instructions are ideal as a quick start installation guide with Tekton Pipelines and not meant for the production use. Please refer to the operator to install, upgrade and manage Tekton projects.
- Nightly release:
```
kubectl apply --filename https://infra.tekton.dev/tekton-releases-nightly/pipeline/latest/release.yaml
```
- Specific release:
```
 kubectl apply --filename https://infra.tekton.dev/tekton-releases/pipeline/previous/<version_number>/release.yaml
```
  Replace <version_number> with the numbered version you want to install. For example, v0.26.0.
- Untagged release:
  
  If your container runtime does not support image-reference:tag@digest:
```
kubectl apply --filename https://infra.tekton.dev/tekton-releases/pipeline/latest/release.notags.yaml
```

Multi-tenant installation is only partially supported today, read the guide for reference.

Monitor the installation:
```
kubectl get pods --namespace tekton-pipelines --watch
```
When all components show 1/1 under the READY column, the installation is complete. Hit Ctrl + C to stop monitoring.

Congratulations! You have successfully installed Tekton Pipelines on your Kubernetes cluster.

Before you proceed, create or select a project on Google Cloud and install the gcloud CLI on your computer.

To install Tekton Pipelines:

Enable the Google Kubernetes Engine (GKE) API:

gcloud services enable container.googleapis.com

Create a cluster with Workload Identity enabled. For example:
```
gcloud container clusters create tekton-cluster \
  --num-nodes=<nodes> \
  --region=<location> \
  --workload-pool=<project-id>.svc.id.goog
```
Where:
- <location> is the cluster location. For example, us-central1. See the documentation about regional and zonal clusters for more information.
- <project-id> is the project ID.
- <nodes> is the number of nodes.
Workload Identity allows your GKE cluster to access Google Cloud services using an Identity Access Management (IAM) service account. For example, the Tekton build and push guide explains how to authenticate to Artifact Registry on a cluster with Workload Identity enabled.

You can also enable Workload Idenitity on an existing cluster.
Follow the regular Kubernetes installation steps.

Private clusters

If you are running a private cluster and experience problems with GKE DNS resolution, allow the port 8443 in your firewall rules.

gcloud compute firewall-rules update <firewall_rule_name> --allow tcp:8443

See the documentation about firewall rules for private clusters for more information.

Autopilot

If you are using Autopilot mode on your GKE cluster and experience some problems, try the following:

Allow port 8443 in your firewall rules.

gcloud compute firewall-rules update <firewall_rule_name> --allow tcp:8443

Disable the affinity assistant.

kubectl patch cm feature-flags -n tekton-pipelines \
  -p '{"data":{"disable-affinity-assistant":"true"}}'

Increase the ephemeral storage.

To install Tekton Pipelines on OpenShift, you must first apply the anyuid security context constraint to the tekton-pipelines-controller service account. This is required to run the webhook Pod. See Security Context Constraints for more information.

Log on as a user with cluster-admin privileges. The following example uses the default system:admin user:
```
oc login -u system:admin
```

Set up the namespace (project) and configure the service account:

oc new-project tekton-pipelines
oc adm policy add-scc-to-user anyuid -z tekton-pipelines-controller
oc adm policy add-scc-to-user anyuid -z tekton-pipelines-webhook

Install Tekton Pipelines:

Because OpenShift uses random user id (and user id range per namespace) for pods, we need to remove the securityContext.runAsUser and securityContext.runAsGroup from any container from the release.yaml. You will need to have yq installed for this to work. Another way would be to download the yaml, search and replace (here replace with nothing) in your favourite editor.
```
curl https://storage.googleapis.com/tekton-releases/pipeline/latest/release.notags.yaml | yq 'del(.spec.template.spec.containers[].securityContext.runAsUser, .spec.template.spec.containers[].securityContext.runAsGroup)' | oc apply -f -
```
See the OpenShift CLI documentation for more information on the oc command.
Monitor the installation using the following command until all components show a Running status:
```
oc get pods --namespace tekton-pipelines --watch
```
Note: Hit CTRL + C to stop monitoring.

Congratulations! You have successfully installed Tekton Pipelines on your OpenShift environment.

To run OpenShift 4.x on your laptop (or desktop), take a look at Red Hat CodeReady Containers.

Additional configuration options

You can enable additional alpha and beta features, customize execution parameters, configure availability, and many more options. See the additional configuration options for more information.

Next steps

To get started with Tekton check the Introductory tutorials, the how-to guides, and the examples folder.

Source for this document available on GitHub.

Docs: Install and set up Tekton Triggers

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

This document shows you how to install and set up Tekton Triggers.

Prerequisites

Kubernetes cluster version 1.18 or later.
Kubectl.
Tekton Pipelines.
Grant cluster-admin privileges to the user that installed Tekton Pipelines. See the kubernetes role-based access control (RBAC) docs.

Installation

Log on to your Kubernetes cluster with the same user account that installed Tekton Pipelines.

Depending on which version of Tekton Triggers you want to install, run one of the following commands:

Latest official release

kubectl apply --filename \
https://storage.googleapis.com/tekton-releases/triggers/latest/release.yaml
kubectl apply --filename \
https://storage.googleapis.com/tekton-releases/triggers/latest/interceptors.yaml

Nightly release

kubectl apply --filename \
https://storage.googleapis.com/tekton-releases-nightly/triggers/latest/release.yaml
kubectl apply --filename \
https://storage.googleapis.com/tekton-releases-nightly/triggers/latest/interceptors.yaml

Specific Release

kubectl apply --filename \
https://storage.googleapis.com/tekton-releases/triggers/previous/VERSION_NUMBER/release.yaml
kubectl apply --filename \
https://storage.googleapis.com/tekton-releases/triggers/previous/VERSION_NUMBER/interceptors.yaml

Replace VERSION_NUMBER with the numbered version you want to install. For example, v0.19.1.

Untagged Release

If your container runtime does not support image-reference:tag@digest (for example, cri-o used in OpenShift 4.x):

kubectl apply --filename \
https://storage.googleapis.com/tekton-releases/triggers/latest/release.notags.yaml
kubectl apply --filename \
https://storage.googleapis.com/tekton-releases/triggers/latest/interceptors.notags.yaml

To monitor the installation, run:
```
kubectl get pods --namespace tekton-pipelines --watch
```
When all components show 1/1 under the READY column, the installation is complete. Hit Ctrl + C to stop monitoring.

Customization options

You can customize the behavior of the Triggers Controller changing some values in the config/feature-flags-triggers.yaml file.

Enable alpha features. Set the value of enable-api-fields: to "alpha", the default value is "stable". This flag only applies to the v1beta1 API version.
Exclude labels. Set the labels-exclusion-pattern: field to a regex pattern. Labels that match this pattern are excluded from getting added to the resources created by the EventListener. By default this field is empty, so all labels added to the EventListener are propagated down.

Docs: Additional Configuration Options

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

This document describes additional options to configure your Tekton Pipelines installation.

Configuring built-in remote Task and Pipeline resolution

Four remote resolvers are currently provided as part of the Tekton Pipelines installation. By default, these remote resolvers are enabled. Each resolver can be disabled by setting the appropriate feature flag in the resolvers-feature-flags ConfigMap in the tekton-pipelines-resolvers namespace:

The bundles resolver, disabled by setting the enable-bundles-resolver feature flag to false.
The git resolver, disabled by setting the enable-git-resolver feature flag to false.
The hub resolver, disabled by setting the enable-hub-resolver feature flag to false.
The cluster resolver, disabled by setting the enable-cluster-resolver feature flag to false.

Configuring CloudEvents notifications

When configured so, Tekton can generate CloudEvents for TaskRun, PipelineRun and CustomRunlifecycle events. The main configuration parameter is the URL of the sink. When not set, no notification is generated.

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-events
  namespace: tekton-pipelines
  labels:
    app.kubernetes.io/instance: default
    app.kubernetes.io/part-of: tekton-pipelines
data:
  formats: tektonv1
  sink: https://my-sink-url

The sink used to be configured in the config-defaults config map. This option is still available, but deprecated, and will be removed.

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-defaults
  namespace: tekton-pipelines
  labels:
    app.kubernetes.io/instance: default
    app.kubernetes.io/part-of: tekton-pipelines
data:
  default-cloud-events-sink: https://my-sink-url

CloudEvents for CustomRuns are enabled by default when a sink is configured in the config-events ConfigMap. The send-cloudevents-for-runs feature flag can be used to disable them for CustomRuns only — for example, to avoid duplicate events when a custom task controller already sends its own CloudEvents.

Deprecated: send-cloudevents-for-runs is deprecated and will be removed in a future release. It now defaults to true.

To disable cloudevents for CustomRuns, use the following configuration:

apiVersion: v1
kind: ConfigMap
metadata:
  name: feature-flags
  namespace: tekton-pipelines
  labels:
    app.kubernetes.io/instance: default
    app.kubernetes.io/part-of: tekton-pipelines
data:
  send-cloudevents-for-runs: "false"
  # Other feature-flags (...)

Configuring self-signed cert for private registry

The SSL_CERT_DIR is set to /etc/ssl/certs as the default cert directory. If you are using a self-signed cert for private registry and the cert file is not under the default cert directory, configure your registry cert in the config-registry-cert ConfigMap with the key cert.

Configuring environment variables

Environment variables can be configured in the following ways, mentioned in order of precedence from lowest to highest.

Implicit environment variables
Step/StepTemplate environment variables
Environment variables specified via a default PodTemplate.
Environment variables specified via a PodTemplate.

The environment variables specified by a PodTemplate supercedes all other ways of specifying environment variables. However, there exists a configuration i.e. default-forbidden-env, the environment variable specified in this list cannot be updated via a PodTemplate.

For example:

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-defaults
  namespace: tekton-pipelines
data:
  default-timeout-minutes: "50"
  default-service-account: "tekton"
  default-forbidden-env: "TEST_TEKTON"
---
apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: mytask
  namespace: default
spec:
  steps:
    - name: echo-env
      image: ubuntu
      command: ["bash", "-c"]
      args: ["echo $TEST_TEKTON "]
      env:
          - name: "TEST_TEKTON"
            value: "true"
---
apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: mytaskrun
  namespace: default
spec:
  taskRef:
    name: mytask
  podTemplate:
    env:
        - name: "TEST_TEKTON"
          value: "false"

In the above example the environment variable TEST_TEKTON will not be overriden by value specified in podTemplate, because the config-default option default-forbidden-env is configured with value TEST_TEKTON.

Configuring default resources requirements

Resource requirements of containers created by the controller can be assigned default values. This allows to fully control the resources requirement of TaskRun.

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-defaults
  namespace: tekton-pipelines
data:
  default-container-resource-requirements: |
    place-scripts: # updates resource requirements of a 'place-scripts' container
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "128Mi"
        cpu: "500m"    
  
    prepare: # updates resource requirements of a 'prepare' container
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "256Mi"
        cpu: "500m"
  
    working-dir-initializer: # updates resource requirements of a 'working-dir-initializer' container
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "512Mi"
        cpu: "500m"
  
    prefix-scripts: # updates resource requirements of containers which starts with 'scripts-'
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "128Mi"
        cpu: "500m"
  
    prefix-sidecar-scripts: # updates resource requirements of containers which starts with 'sidecar-scripts-'
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "128Mi"
        cpu: "500m"
  
    default: # updates resource requirements of init-containers and containers which has empty resource requirements
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "256Mi"
        cpu: "500m"

Any resource requirements set at the Task and TaskRun levels will overidde the default one specified in the config-defaults configmap.

Customizing basic execution parameters

You can specify your own values that replace the default service account (ServiceAccount), timeout (Timeout), resolver (Resolver), and Pod template (PodTemplate) values used by Tekton Pipelines in TaskRun and PipelineRun definitions. To do so, modify the ConfigMap config-defaults with your desired values.

The example below customizes the following:

the default service account from default to tekton.
the default timeout from 60 minutes to 20 minutes.
the default app.kubernetes.io/managed-by label is applied to all Pods created to execute TaskRuns.
the default Pod template to include a node selector to select the node where the Pod will be scheduled by default. A list of supported fields is available here. For more information, see PodTemplate in TaskRuns or PodTemplate in PipelineRuns.
the default Workspace configuration can be set for any Workspaces that a Task declares but that a TaskRun does not explicitly provide.
the default maximum combinations of Parameters in a Matrix that can be used to fan out a PipelineTask. For more information, see Matrix.
the default resolver type to git.
the default polling interval for the sidecar log results container via default-sidecar-log-polling-interval.

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-defaults
data:
  default-service-account: "tekton"
  default-timeout-minutes: "20"
  default-pod-template: |
    nodeSelector:
      kops.k8s.io/instancegroup: build-instance-group    
  default-managed-by-label-value: "my-tekton-installation"
  default-task-run-workspace-binding: |
        emptyDir: {}
  default-max-matrix-combinations-count: "1024"
  default-resolver-type: "git"
  default-sidecar-log-polling-interval: "100ms"

`default-sidecar-log-polling-interval`

The default-sidecar-log-polling-interval key in the config-defaults ConfigMap specifies how frequently the Tekton sidecar log results container polls for step completion files written by steps in a TaskRun. Lower values (e.g., 10ms) make the sidecar more responsive but may increase CPU usage; higher values (e.g., 1s) reduce resource usage but may delay result collection. This value is used by the sidecar-tekton-log-results container and can be tuned for performance or test scenarios.

Example values:

100ms (default)
500ms
1s
10ms (for fast polling in tests)

Note: The default-sidecar-log-polling-interval setting is only applicable when results are created using the sidecar approach.

Note: The _example key in the provided config-defaults.yaml file lists the keys you can customize along with their default values.

Customizing the Pipelines Controller behavior

To customize the behavior of the Pipelines Controller, modify the ConfigMap feature-flags via kubectl edit configmap feature-flags -n tekton-pipelines.

Note: Changing feature flags may result in undefined behavior for TaskRuns and PipelineRuns that are running while the change occurs.

The flags in this ConfigMap are as follows:

coschedule: set this flag determines how PipelineRun Pods are scheduled with Affinity Assistant. Acceptable values are “workspaces” (default), “pipelineruns”, “isolate-pipelinerun”, or “disabled”. Setting it to “workspaces” will schedule all the taskruns sharing the same PVC-based workspace in a pipelinerun to the same node. Setting it to “pipelineruns” will schedule all the taskruns in a pipelinerun to the same node. Setting it to “isolate-pipelinerun” will schedule all the taskruns in a pipelinerun to the same node, and only allows one pipelinerun to run on a node at a time. Setting it to “disabled” will not apply any coschedule policy.
await-sidecar-readiness: set this flag to "false" to allow the Tekton controller to start a TasksRun’s first step immediately without waiting for sidecar containers to be running first. Using this option should decrease the time it takes for a TaskRun to start running, and will allow TaskRun pods to be scheduled in environments that don’t support Downward API volumes (e.g. some virtual kubelet implementations). However, this may lead to unexpected behaviour with Tasks that use sidecars, or in clusters that use injected sidecars (e.g. Istio). Setting this flag to "false" will mean the running-in-environment-with-injected-sidecars flag has no effect.
running-in-environment-with-injected-sidecars: set this flag to "false" to allow the Tekton controller to start a TasksRun’s first step immediately if it has no Sidecars specified. Using this option should decrease the time it takes for a TaskRun to start running. However, for clusters that use injected sidecars (e.g. Istio) this can lead to unexpected behavior.
require-git-ssh-secret-known-hosts: set this flag to "true" to require that Git SSH Secrets include a known_hosts field. This ensures that a git remote server’s key is validated before data is accepted from it when authenticating over SSH. Secrets that don’t include a known_hosts will result in the TaskRun failing validation and not running.
enable-tekton-oci-bundles: set this flag to "true" to enable the tekton OCI bundle usage (see the tekton bundle contract). Enabling this option allows the use of bundle field in taskRef and pipelineRef for Pipeline, PipelineRun and TaskRun. By default, this option is disabled ("false"), which means it is disallowed to use the bundle field.
disable-creds-init - set this flag to "true" to disable Tekton’s built-in credential initialization and use Workspaces to mount credentials from Secrets instead. The default is false. For more information, see the associated issue.
enable-api-fields: When using v1beta1 APIs, setting this field to “stable” or “beta” enables beta features. When using v1 APIs, setting this field to “stable” allows only stable features, and setting it to “beta” allows only beta features. Set this field to “alpha” to allow alpha features to be used.
enable-kubernetes-sidecar: Set this flag to "true" to enable native kubernetes sidecar support. This will allow Tekton sidecars to run as Kubernetes sidecars. Must be using Kubernetes v1.29 or greater.

For example:

apiVersion: v1
kind: ConfigMap
metadata:
  name: feature-flags
data:
  enable-api-fields: "alpha" # Allow alpha fields to be used in Tasks and Pipelines.

trusted-resources-verification-no-match-policy: Setting this flag to fail will fail the taskrun/pipelinerun if no matching policies found. Setting to warn will skip verification and log a warning if no matching policies are found, but not fail the taskrun/pipelinerun. Setting to ignore will skip verification if no matching policies found. Defaults to “ignore”.
results-from: set this flag to “termination-message” to use the container’s termination message to fetch results from. This is the default method of extracting results. Set it to “sidecar-logs” to enable use of a results sidecar logs to extract results instead of termination message.
enable-provenance-in-status: Set this flag to "true" to enable populating the provenance field in TaskRun and PipelineRun status. The provenance field contains metadata about resources used in the TaskRun/PipelineRun such as the source from where a remote Task/Pipeline definition was fetched. By default, this is set to true. To disable populating this field, set this flag to "false".
set-security-context: Set this flag to true to set a security context for containers injected by Tekton that will allow TaskRun pods to run in namespaces with restricted pod security admission. By default, this is set to false.
set-security-context-read-only-root-filesystem: Set this flag to true to enable readOnlyRootFilesystem in the security context for containers injected by Tekton. This makes the root filesystem of the container read-only, enhancing security. Note that this requires set-security-context to be enabled. By default, this flag is set to false. Note: This feature does not work in windows as it is not supported there, Comparison with linux.

Alpha Features

Alpha features in the following table are still in development and their syntax is subject to change.

To enable the features without an individual flag: set the enable-api-fields feature flag to "alpha" in the feature-flags ConfigMap alongside your Tekton Pipelines deployment via kubectl patch cm feature-flags -n tekton-pipelines -p '{"data":{"enable-api-fields":"alpha"}}'.
To enable the features with an individual flag: set the individual flag accordingly in the feature-flag ConfigMap alongside your Tekton Pipelines deployment. Example: kubectl patch cm feature-flags -n tekton-pipelines -p '{"data":{"<FLAG-NAME>":"<FLAG-VALUE>"}}'.

Features currently in “alpha” are:

Feature	Proposal	Release	Individual Flag
Bundles	TEP-0005	v0.18.0	`enable-tekton-oci-bundles`
Hermetic Execution Mode	TEP-0025	v0.25.0
Windows Scripts	TEP-0057	v0.28.0
Debug	TEP-0042	v0.26.0
StdoutConfig and StderrConfig	TEP-0011	v0.38.0
Trusted Resources	TEP-0091	v0.49.0	`trusted-resources-verification-no-match-policy`
Configure Default Resolver	TEP-0133	v0.46.0
Coschedule	TEP-0135	v0.51.0	`coschedule`
keep pod on cancel	N/A	v0.52.0	`keep-pod-on-cancel`
CEL in WhenExpression	TEP-0145	v0.53.0	`enable-cel-in-whenexpression`
Param Enum	TEP-0144	v0.54.0	`enable-param-enum`

Beta Features

Beta features are fields of stable CRDs that follow our “beta” compatibility policy. To enable these features, set the enable-api-fields feature flag to "beta" in the feature-flags ConfigMap alongside your Tekton Pipelines deployment via kubectl patch cm feature-flags -n tekton-pipelines -p '{"data":{"enable-api-fields":"beta"}}'.

Features currently in “beta” are:

Feature	Proposal	Alpha Release	Beta Release	Individual Flag
Remote Tasks and Remote Pipelines	TEP-0060		v0.41.0
`Provenance` field in Status	issue#5550	v0.41.0	v0.48.0	`enable-provenance-in-status`
Isolated `Step` & `Sidecar` `Workspaces`	TEP-0029	v0.24.0	v0.50.0
Matrix	TEP-0090	v0.38.0	v0.53.0
Task-level Resource Requirements	TEP-0104	v0.39.0	v0.53.0
Larger Results via Sidecar Logs	TEP-0127	v0.43.0	v0.61.0	`results-from`
Step and Sidecar Overrides	TEP-0094	v0.34.0		v0.61.0
Ignore Task Failure	TEP-0050	v0.55.0	v0.62.0	N/A

Enabling larger results using sidecar logs

Note: The maximum size of a Task’s results is limited by the container termination message feature of Kubernetes, as results are passed back to the controller via this mechanism. At present, the limit is per task is “4096 bytes”. All results produced by the task share this upper limit.

To exceed this limit of 4096 bytes, you can enable larger results using sidecar logs. By enabling this feature, you will have a configurable limit (with a default of 4096 bytes) per result with no restriction on the number of results. The results are still stored in the taskRun CRD, so they should not exceed the 1.5MB CRD size limit.

Note: to enable this feature, you need to grant get access to all pods/log to the tekton-pipelines-controller. This means that the tekton pipeline controller has the ability to access the pod logs.

Create a cluster role and rolebinding by applying the following spec to provide log access to tekton-pipelines-controller.

kubectl apply -f optional_config/enable-log-access-to-controller/

Set the results-from feature flag to use sidecar logs by setting results-from: sidecar-logs in the configMap.

kubectl patch cm feature-flags -n tekton-pipelines -p '{"data":{"results-from":"sidecar-logs"}}'

If you want the size per result to be something other than 4096 bytes, you can set the max-result-size feature flag in bytes by setting max-result-size: 8192(whatever you need here). Note: The value you can set here cannot exceed the size of the CRD limit of 1.5 MB.

kubectl patch cm feature-flags -n tekton-pipelines -p '{"data":{"max-result-size":"<VALUE-IN-BYTES>"}}'

Configuring High Availability

If you want to run Tekton Pipelines in a way so that webhooks are resiliant against failures and support high concurrency scenarios, you need to run a Metrics Server in your Kubernetes cluster. This is required by the Horizontal Pod Autoscalers to compute replica count.

See HA Support for Tekton Pipeline Controllers for instructions on configuring High Availability in the Tekton Pipelines Controller.

The default configuration is defined in webhook-hpa.yaml which can be customized to better fit specific usecases.

Configuring tekton pipeline controller performance

Out-of-the-box, Tekton Pipelines Controller is configured for relatively small-scale deployments but there have several options for configuring Pipelines’ performance are available. See the Performance Configuration document which describes how to change the default ThreadsPerController, QPS and Burst settings to meet your requirements.

Running TaskRuns and PipelineRuns with restricted pod security standards

To allow TaskRuns and PipelineRuns to run in namespaces with restricted pod security standards, set the “set-security-context” feature flag to “true” in the feature-flags configMap. This configuration option applies a SecurityContext to any containers injected into TaskRuns by the Pipelines controller. If the Affinity Assistants feature is enabled, the SecurityContext is also applied to those containers. This SecurityContext may not be supported in all Kubernetes implementations (for example, OpenShift).

Note: running TaskRuns and PipelineRuns in the “tekton-pipelines” namespace is discouraged.

Platform Support

The Tekton project provides support for running on x86 Linux Kubernetes nodes.

The project produces images capable of running on other architectures and operating systems, but may not be able to help debug issues specific to those platforms as readily as those that affect Linux on x86.

The controller and webhook components are currently built for:

linux/amd64
linux/arm64
linux/ppc64le (PowerPC)
linux/s390x (IBM Z)

The entrypoint component is also built for Windows, which enables TaskRun workloads to execute on Windows nodes. See Windows documentation for more information.

Creating a custom release of Tekton Pipelines

You can create a custom release of Tekton Pipelines by following and customizing the steps in Creating an official release. For example, you might want to customize the container images built and used by Tekton Pipelines.

Verify Tekton Pipelines Release

We will refine this process over time to be more streamlined. For now, please follow the steps listed in this section to verify Tekton pipeline release.

Tekton Pipeline’s images are being signed by Tekton Chains since 0.27.1. You can verify the images with cosign using the Tekton’s public key.

Verify signatures using `cosign`

With Go 1.16+, you can install cosign by running:

go install github.com/sigstore/cosign/cmd/cosign@latest

You can verify Tekton Pipelines official images using the Tekton public key:

cosign verify -key https://raw.githubusercontent.com/tektoncd/chains/main/tekton.pub gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/controller:v0.28.1

which results in:

Verification for gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/controller:v0.28.1 --
The following checks were performed on each of these signatures:
  - The cosign claims were validated
  - The signatures were verified against the specified public key
  - Any certificates were verified against the Fulcio roots.
{
  "Critical": {
    "Identity": {
      "docker-reference": "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/controller"
    },
    "Image": {
      "Docker-manifest-digest": "sha256:0c320bc09e91e22ce7f01e47c9f3cb3449749a5f72d5eaecb96e710d999c28e8"
    },
    "Type": "Tekton container signature"
  },
  "Optional": {}
}

The verification shows a list of checks performed and returns the digest in Critical.Image.Docker-manifest-digest which can be used to retrieve the provenance from the transparency logs for that image using rekor-cli.

Verify the transparency logs using `rekor-cli`

Install the rekor-cli by running:

go install -v github.com/sigstore/rekor/cmd/rekor-cli@latest

Now, use the digest collected from the previous section in Critical.Image.Docker-manifest-digest, for example, sha256:0c320bc09e91e22ce7f01e47c9f3cb3449749a5f72d5eaecb96e710d999c28e8.

Search the transparency log with the digest just collected:

rekor-cli search --sha sha256:0c320bc09e91e22ce7f01e47c9f3cb3449749a5f72d5eaecb96e710d999c28e8

which results in:

Found matching entries (listed by UUID):
68a53d0e75463d805dc9437dda5815171502475dd704459a5ce3078edba96226

Tekton Chains generates provenance based on the custom format in which the subject holds the list of artifacts which were built as part of the release. For the Pipeline release, subject includes a list of images including pipeline controller, pipeline webhook, etc. Use the UUID to get the provenance:

rekor-cli get --uuid 68a53d0e75463d805dc9437dda5815171502475dd704459a5ce3078edba96226 --format json | jq -r .Attestation | base64 --decode | jq

which results in:

{
  "_type": "https://in-toto.io/Statement/v0.1",
  "predicateType": "https://tekton.dev/chains/provenance",
  "subject": [
    {
      "name": "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/controller",
      "digest": {
        "sha256": "0c320bc09e91e22ce7f01e47c9f3cb3449749a5f72d5eaecb96e710d999c28e8"
      }
    },
    {
      "name": "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/entrypoint",
      "digest": {
        "sha256": "2fa7f7c3408f52ff21b2d8c4271374dac4f5b113b1c4dbc7d5189131e71ce721"
      }
    },
    {
      "name": "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/git-init",
      "digest": {
        "sha256": "83d5ec6addece4aac79898c9631ee669f5fee5a710a2ed1f98a6d40c19fb88f7"
      }
    },
    {
      "name": "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/imagedigestexporter",
      "digest": {
        "sha256": "e4d77b5b8902270f37812f85feb70d57d6d0e1fed2f3b46f86baf534f19cd9c0"
      }
    },
    {
      "name": "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/nop",
      "digest": {
        "sha256": "59b5304bcfdd9834150a2701720cf66e3ebe6d6e4d361ae1612d9430089591f8"
      }
    },
    {
      "name": "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/pullrequest-init",
      "digest": {
        "sha256": "4992491b2714a73c0a84553030e6056e6495b3d9d5cc6b20cf7bc8c51be779bb"
      }
    },
    {
      "name": "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/webhook",
      "digest": {
        "sha256": "bf0ef565b301a1981cb2e0d11eb6961c694f6d2401928dccebe7d1e9d8c914de"
      }
    }
  ],
  ...

Now, verify the digest in the release.yaml by matching it with the provenance, for example, the digest for the release v0.28.1:

curl -s https://infra.tekton.dev/tekton-releases/pipeline/previous/v0.28.1/release.yaml | grep github.com/tektoncd/pipeline/cmd/controller:v0.28.1 | awk -F"github.com/tektoncd/pipeline/cmd/controller:v0.28.1@" '{print $2}'

which results in:

sha256:0c320bc09e91e22ce7f01e47c9f3cb3449749a5f72d5eaecb96e710d999c28e8

Now, you can verify the deployment specifications in the release.yaml to match each of these images and their digest. The tekton-pipelines-controller deployment specification has a container named tekton-pipeline-controller and a list of image references with their digest as part of the args:

      containers:
        - name: tekton-pipelines-controller
          image: gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/controller:v0.28.1@sha256:0c320bc09e91e22ce7f01e47c9f3cb3449749a5f72d5eaecb96e710d999c28e8
          args: [
            # These images are built on-demand by `ko resolve` and are replaced
            # by image references by digest.
              "-git-image",
              "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/git-init:v0.28.1@sha256:83d5ec6addece4aac79898c9631ee669f5fee5a710a2ed1f98a6d40c19fb88f7",
              "-entrypoint-image",
              "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/entrypoint:v0.28.1@sha256:2fa7f7c3408f52ff21b2d8c4271374dac4f5b113b1c4dbc7d5189131e71ce721",
              "-nop-image",
              "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/nop:v0.28.1@sha256:59b5304bcfdd9834150a2701720cf66e3ebe6d6e4d361ae1612d9430089591f8",
              "-imagedigest-exporter-image",
              "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/imagedigestexporter:v0.28.1@sha256:e4d77b5b8902270f37812f85feb70d57d6d0e1fed2f3b46f86baf534f19cd9c0",
              "-pr-image",
              "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/pullrequest-init:v0.28.1@sha256:4992491b2714a73c0a84553030e6056e6495b3d9d5cc6b20cf7bc8c51be779bb",

Similarly, you can verify the rest of the images which were published as part of the Tekton Pipelines release:

gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/git-init
gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/entrypoint
gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/nop
gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/imagedigestexporter
gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/pullrequest-init
gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/webhook

Verify Tekton Resources

Trusted Resources is a feature to verify Tekton Tasks and Pipelines. The current version of feature supports v1beta1 Task and Pipeline. For more details please take a look at Trusted Resources.

Pipelineruns with Affinity Assistant

The cluster operators can review the guidelines to cordon a node in the cluster with the tekton controller and the affinity assistant is enabled.

TaskRuns with `imagePullBackOff` Timeout

Tekton pipelines has adopted a fail fast strategy with a taskRun failing with TaskRunImagePullFailed in case of an imagePullBackOff. This can be limited in some cases, and it generally depends on the infrastructure. To allow the cluster operators to decide whether to wait in case of an imagePullBackOff, a setting is available to configure the wait time such that the controller will wait for the specified duration before declaring a failure. For example, with the following config-defaults, the controller does not mark the taskRun as failure for 5 minutes since the pod is scheduled in case the image pull fails with imagePullBackOff. The default-imagepullbackoff-timeout is of type time.Duration and can be set to a duration such as “1m”, “5m”, “10s”, “1h”, etc. See issue https://github.com/tektoncd/pipeline/issues/5987 for more details.

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-defaults
  namespace: tekton-pipelines
data:
  default-imagepullbackoff-timeout: "5m"

Disabling Inline Spec in Pipeline, TaskRun and PipelineRun

Tekton users may embed the specification of a Task (via taskSpec) or a Pipeline (via pipelineSpec) as an alternative to referring to an external resource via taskRef and pipelineRef respectively. This behaviour can be selectively disabled for three Tekton resources: TaskRun, PipelineRun and Pipeline.

In certain clusters and scenarios, an admin might want to disable the customisation of Tasks and Pipelines and only allow users to run pre-defined resources. To achieve that the admin should disable embedded specification via the disable-inline-spec flag, and remote resolvers too.

To disable inline specification, set the disable-inline-spec flag to "pipeline,pipelinerun,taskrun" in the feature-flags configmap.

apiVersion: v1
kind: ConfigMap
metadata:
  name: feature-flags
  namespace: tekton-pipelines
  labels:
    app.kubernetes.io/instance: default
    app.kubernetes.io/part-of: tekton-pipelines
data:
  disable-inline-spec: "pipeline,pipelinerun,taskrun"

Inline specifications can be disabled for specific resources only. To achieve that, set the disable-inline-spec flag to a comma-separated list of the desired resources. Valid values are pipeline, pipelinerun and taskrun.

The default value of disable-inline-spec is “”, which means inline specification is enabled in all cases.

Exponential Backoff for TaskRun and CustomRun Creation

By default, when Tekton Pipelines attempts to create a TaskRun or CustomRun resource and encounters an error, the controller will requeue the PipelineRun for another reconciliation attempt after a short delay. However, this may not be sufficient in a heavily loaded or busy cluster, where transient errors such as webhook timeouts or network issues are more likely to occur.

To improve robustness in environments where webhook timeouts or network errors are possible, you can enable an exponential backoff retry strategy for TaskRun and CustomRun creation by setting the enable-wait-exponential-backoff feature flag to "true" in the feature-flags ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: feature-flags
  namespace: tekton-pipelines
data:
  enable-wait-exponential-backoff: "true"

When this flag is enabled, the controller will retry TaskRun and CustomRun creation using an exponential backoff strategy if it encounters admission webhook timeouts (e.g., "timeout").

This helps mitigate failures due to temporary unavailability of webhooks or network disruptions.

Backoff Configuration

You can further customize the backoff parameters (such as initial duration, factor, steps, and cap) using the wait-exponential-backoff ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: wait-exponential-backoff
  namespace: tekton-pipelines
data:
  duration: "1s"
  factor: "2.0"
  jitter: "0.0"
  steps: "10"
  cap: "30s"

duration: Initial wait time before the first retry.
factor: Multiplier for each subsequent retry interval.
steps: Maximum number of retry attempts.
cap: Maximum wait time between retries.

Default Behavior

If enable-wait-exponential-backoff is not set or is set to "false", the controller will rely on its standard reconcilation loop to retry TaskRun or CustomRun creation after a short delay when failures occur due to webhook or network errors.

Note: This feature is especially useful in clusters where webhook services (such as Kyverno, OPA, or custom admission controllers) may be temporarily unavailable or slow to respond.

Limiting Step reference concurrency resolution

You can control the maximum number of concurrent goroutines that the Tekton controller uses to resolve steps referencing a StepAction via the step.ref field.

When a TaskRun is processed, any step that uses a ref to a remote StepAction (e.g., one stored in a git repository or an OCI registry) triggers a fetch request. If a Task contains many such steps, the controller will attempt to resolve them all in parallel. This can lead to a “thundering herd” problem, potentially overwhelming remote servers, hitting API rate limits, saturating network resources, or placing excessive load on the Kubernetes API server and the Tekton controller itself.

To mitigate this, Tekton Pipelines includes a configurable concurrency limit. By default, a sensible limit is already in place to ensure stability.

Default Behavior

If the default-step-ref-concurrency-limit key is not set in the config-defaults ConfigMap, Tekton Pipelines defaults to a concurrency limit of 5. This provides a safe, built-in throttle without requiring any initial configuration.

Overriding the Default

You can override this default to better suit your environment’s capacity (e.g., a high-capacity, self-hosted git server might allow for a higher limit). To change the limit, set the default-step-ref-concurrency-limit key in your config-defaults ConfigMap.

Example: To increase the concurrency limit to 20:

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-defaults
  namespace: tekton-pipelines
data:
  default-step-ref-concurrency-limit: "20"

Next steps

To get started with Tekton check the Introductory tutorials, the how-to guides, and the examples folder.

Source for this document available on GitHub.

Tekton – Installation

Docs: Local Kubernetes cluster

Further reading

Docs: Install Tekton Pipelines

Prerequisites

Installation

Additional configuration options

Next steps

Docs: Install and set up Tekton Triggers

Prerequisites

Installation

Customization options

Further reading

Docs: Additional Configuration Options

Table of Contents

Configuring built-in remote Task and Pipeline resolution

Configuring CloudEvents notifications

Configuring self-signed cert for private registry

Configuring environment variables

Configuring default resources requirements

Customizing basic execution parameters

default-sidecar-log-polling-interval

Customizing the Pipelines Controller behavior

Alpha Features

Beta Features

Enabling larger results using sidecar logs

Configuring High Availability

Configuring tekton pipeline controller performance

Running TaskRuns and PipelineRuns with restricted pod security standards

Platform Support

Creating a custom release of Tekton Pipelines

Verify Tekton Pipelines Release

Verify signatures using cosign

Verify the transparency logs using rekor-cli

Verify Tekton Resources

Pipelineruns with Affinity Assistant

TaskRuns with imagePullBackOff Timeout

Disabling Inline Spec in Pipeline, TaskRun and PipelineRun

Exponential Backoff for TaskRun and CustomRun Creation

Backoff Configuration

Default Behavior

Limiting Step reference concurrency resolution

Default Behavior

Overriding the Default

Next steps

`default-sidecar-log-polling-interval`

Verify signatures using `cosign`

Verify the transparency logs using `rekor-cli`

TaskRuns with `imagePullBackOff` Timeout