knative / knative/pkg

Support Kubernetes v1.36 ShardSelector in informer injection framework

Open
#3,383 1 comment 2 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
276
Forks
343
Avg merge
1d 1h
Merged PRs (30d)
1

Description

## Summary

Kubernetes v1.36 introduced [Server-Side Sharded List and Watch](https://kubernetes.io/blog/2026/05/06/kubernetes-v1-36-server-side-sharded-list-and-watch/) as an alpha feature ([KEP-5866](https://github.com/kubernetes/enhancements/issues/5866)). This adds a `ShardSelector` field to `metav1.ListOptions` that allows informers to request only objects within a specific hash range, so the API server filters watch events at the source.

The knative.dev/pkg injection framework currently has no support for injecting `shardSelector` into informer `ListOptions`. This blocks downstream projects (e.g., Tekton Pipelines) from adopting sharded watches while staying within the injection framework.

## Background

The injection framework already supports filtering via `WithTweakListOptions` — the [filtered informer factory](https://github.com/knative/pkg/blob/main/client/injection/kube/informers/factory/filtered/filtered_factory.go) uses this to inject label selectors. The `ShardSelector` would follow a similar pattern but targets the `ListOptions.ShardSelector` field instead of `LabelSelector`.

The `ShardSelector` field accepts CEL expressions like:
```
shardRange(object.metadata.uid, '0x0000000000000000', '0x8000000000000000')
```

## Proposed Changes

1. **New context decorator** — similar to `filteredinformerfactory.WithSelectors`, add a mechanism to inject a `shardSelector` string into all informer `ListOptions`. For example:
```go
ctx = sharding.WithShardSelector(ctx, "shardRange(object.metadata.uid, '0x0000000000000000', '0x8000000000000000')")
```

2. **Plumb through informer factories** — both the standard and filtered informer factories (and their generated CRD-specific counterparts from injection-gen) should respect the shard selector from context, appending it via `WithTweakListOptions`.

3. **Coordinate with bucket-based leader election** — when shard selectors are active, the informer cache only contains objects in the shard range. The bucket-based leader election partitioning must align with the shard boundaries, or a replica could be elected leader for keys it never receives via its watch. This likely means:
- When sharding is enabled, bucket count should equal the number of shards
- Or shard assignment should derive from the bucket/lease ownership

4. **Graceful fallback** — when the API server doesn't support the feature (pre-v1.36 or feature gate disabled), the controller should fall back to full watches transparently.

## Use Case

Tekton Pipelines controllers processing thousands of concurrent PipelineRuns/TaskRuns. With N replicas today, each replica watches all objects and only reconciles its bucket — CPU, memory, and network scale with replica count rather than shard size. With sharded watches, each replica only receives 1/N of events.

Upstream issue: https://github.com/tektoncd/pipeline/issues/10610

## Kubernetes References

- **KEP-5866**: https://github.com/kubernetes/enhancements/issues/5866
- **Blog post**: https://kubernetes.io/blog/2026/05/06/kubernetes-v1-36-server-side-sharded-list-and-watch/
- **ListOptions.ShardSelector**: added in k8s.io/apimachinery, field `ShardSelector string` in `metav1.ListOptions`
- **Feature gate**: `ShardedListAndWatch` (alpha in v1.36)

Contributor guide

Open the contributing guide

Research direction

Start with client/injection/kube/informers/factory/filtered/filtered_factory.go and filteredinformerfactory.WithSelectors, then trace the standard, filtered, and generated CRD-specific informer factories. Review how bucket-based leader election partitions ownership. Done means shard selectors propagate through informer ListOptions, align with shard ownership, and fall back transparently when unsupported.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, kubernetes
Domain
api, backend, distributed-systems
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.