Tekton Controller Performance Configuration

Configure ThreadsPerController, QPS and Burst

• Overview
• Performance Configuration
  • Configure Thread, QPS and Burst
• Informer Cache Transform (Memory Optimization)
  • Configuration
  • Important Notes

Overview

This document will show us how to configure tekton-pipeline-controller's performance. In general, there are mainly have three parameters will impact the performance of tekton controller, they are ThreadsPerController, QPS and Burst.

• ThreadsPerController: Threads (goroutines) to create per controller. It's the number of threads to use when processing the controller's work queue.

• QPS: Queries per Second. Maximum QPS to the master from this client.

• Burst: Maximum burst for throttle.

Performance Configuration

Configure Thread, QPS and Burst

Default, the value of ThreadsPerController, QPS and Burst is 2, 5.0 and 10 accordingly.

Sometimes, above default values can't meet performance requirements, then you need to overwrite these values. You can modify them in the tekton controller deployment. You can specify these customized values in the tekton-pipelines-controller container via threads-per-controller, kube-api-qps and kube-api-burst flags accordingly. For example:

spec:
  serviceAccountName: tekton-pipelines-controller
  containers:
    - name: tekton-pipelines-controller
      image: ko://github.com/tektoncd/pipeline/cmd/controller
      args: [
          "-kube-api-qps", "50",
          "-kube-api-burst", "50",
          "-threads-per-controller", "32",
          # other flags defined here...
        ]

Now, the ThreadsPerController, QPS and Burst have been changed to be 32, 50 and 50.

You can also set THREADS_PER_CONTROLLER, KUBE_API_QPS and KUBE_API_BURST environment variables to overwrite default values. If flags and environment variables are set, command line args will take precedence.

Note:

Although in above example, you set QPS and Burst to be 50 and 50. However, the actual values of them are multiplied by 2, so the actual QPS and Burst is 100 and 100.

Informer Cache Transform (Memory Optimization)

The Tekton controller uses informer caches to watch and react to changes in Kubernetes objects. To reduce memory usage, Tekton Pipeline applies cache transform functions that strip large, unnecessary metadata fields from objects before they are stored in the informer cache.

This optimization is enabled by default. It strips managedFields (server-side apply metadata, which can be 25-30% of an object's size) and the kubectl.kubernetes.io/last-applied-configuration annotation from cached PipelineRuns, TaskRuns, CustomRuns, and Pods.

Configuration

The cache transforms are enabled by default. To disable them (e.g., for troubleshooting), set enable-informer-cache-transforms to false in the feature-flags ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: feature-flags
  namespace: tekton-pipelines
data:
  enable-informer-cache-transforms: "false"

Note: Changes to this setting require a controller restart to take effect.

Important Notes

1. Read-only optimization: The transform only affects what is stored in the in-memory cache. The complete objects remain unchanged in etcd.

2. No impact on API access: When you use kubectl get or the Kubernetes API, you always get the complete object from etcd, not the cached version.

3. Controller behavior unchanged: The controller reconciliation logic continues to work correctly because it only needs the preserved fields.

For detailed technical information about which fields are stripped, see the developer documentation.