tektoncd/pipeline

docs: document horizontal controller scaling via leader election buckets

Open

#9,670 opened on Mar 26, 2026

View on GitHub
 (3 comments) (0 reactions) (1 assignee)Go (1,943 forks)auto 404
good first issuehelp wantedkind/documentation

Repository metrics

Stars
 (9,013 stars)
PR merge metrics
 (PR metrics pending)

Description

Description

Tekton controllers support horizontal scaling via Knative's bucket-based leader election, but this is not documented anywhere in docs/.

The mechanism is configured in config-leader-election-controller ConfigMap:

data:
  buckets: "10"  # partition key space into 10 buckets

Then scale the deployment:

kubectl -n tekton-pipelines scale deployment tekton-pipelines-controller --replicas=5

With M buckets and N replicas, replicas compete for buckets. Each bucket owner reconciles keys in its partition.

Areas to Document

  • How to configure buckets in config-leader-election-controller
  • Recommended bucket/replica ratios
  • Impact on reconciliation latency and throughput
  • Same mechanism available for config-leader-election-webhook and config-leader-election-events
  • Any caveats (e.g., rebalancing behavior when replicas change)

Context

Closes the long-standing request from #3404 (25 comments, opened 2020). The feature has been available for years but users don't know about it.

/kind documentation

Contributor guide