docs: document horizontal controller scaling via leader election buckets

[vdemeester]

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

[ogulcanaydogan]

Hi! I'd like to document the horizontal controller scaling via leader election buckets.

I'll add a section to the docs covering:

1. How bucket-based leader election works (ConfigMap config-leader-election-controller)
2. How to configure the buckets parameter
3. How to scale the controller deployment
4. Relationship between buckets (M) and replicas (N)

I already have an open PR in this repo (#9655), so I'm familiar with the codebase. Will keep the docs focused and concise.