kubernetesobservabilityPractitioner

Unlocking Efficiency with Kubernetes v1.36: Server-Side Sharded List and Watch

5 min read Kubernetes BlogMay 6, 2026Reviewed for accuracy

Practitioner — Hands-on experience recommended

In a world where Kubernetes clusters can grow massive, the need for efficient resource management becomes critical. The server-side sharded list and watch feature addresses this by allowing the API server to filter events right at the source. This means that each controller replica only receives the slice of the resource collection it owns, reducing unnecessary load and improving overall system performance.

The mechanism behind this feature is straightforward yet powerful. It introduces a shardSelector field in ListOptions, where clients can specify a hash range using the shardRange() function. For instance, you can define your range with shardRange(object.metadata.uid, '0x0000000000000000', '0x8000000000000000'). The API server then computes a deterministic 64-bit FNV-1a hash of the specified field and returns only the objects whose hash falls within the defined range. This filtering applies to both list responses and watch event streams, making it a versatile tool for managing resources effectively.

As with any alpha feature, there are caveats. You must enable the ShardedListAndWatch feature gate on your API server to use this functionality. While it can significantly enhance performance, be mindful of its alpha status and the potential for changes in future releases. Always test thoroughly in your environment before rolling it out to production.

Key takeaways

→Enable the ShardedListAndWatch feature gate on your API server to access this functionality.
→Use the shardSelector field in ListOptions to filter events effectively.
→Implement the shardRange() function to define your hash range for resource filtering.
→Expect improved performance by reducing unnecessary event traffic to controller replicas.
→Be cautious as this feature is in alpha; monitor for changes in future Kubernetes versions.

Why it matters

This feature can drastically reduce the load on your Kubernetes API server, leading to faster response times and improved scalability in large clusters. By ensuring that each controller only processes relevant events, you enhance the efficiency of your resource management.

Code examples

JSON

1{
2"kind": "PodList",
3"apiVersion": "v1",
4"metadata": {
5"resourceVersion": "10245",
6"shardInfo": {
7"selector": "shardRange(object.metadata.uid, '0x0000000000000000', '0x8000000000000000')"
8}
9},
10"items": [
11...
12]
13}