Add documentation for CRIListStreaming feature gate

bitoku · bitoku · commit c609d9f1c254 · 2026-04-08T11:41:59.000Z
Signed-off-by: Ayato Tokubi &lt;atokubi@redhat.com&gt;
diff --git a/content/en/docs/concepts/containers/cri.md b/content/en/docs/concepts/containers/cri.md
@@ -42,6 +42,29 @@ runtime has been upgraded, the runtime must support the `v1` CRI API for the
 connection to succeed. This might require a restart of the kubelet after the
 container runtime is correctly configured.
 
+## List streaming {#list-streaming}
+
+{{< feature-state feature_gate_name="CRIListStreaming" >}}
+
+The standard CRI list RPCs (`ListContainers`, `ListPodSandbox`, `ListImages`) return
+all results in a single unary response. On nodes with a large number of containers
+(for example, more than roughly 10,000 including both running and stopped), these
+responses can exceed gRPC's default 16 MiB message size limit, causing the kubelet
+to fail when reconciling state with the container runtime.
+
+With the `CRIListStreaming` feature gate enabled, the kubelet uses server-side
+streaming RPCs (such as `StreamContainers`, `StreamPodSandboxes`,
+`StreamImages`) that allow the container runtime to divide results across
+multiple response messages, bypassing the per-message size limit. This is
+particularly useful for:
+
+- High container churn environments (CI/CD systems)
+- Large-scale batch processing workloads
+
+If the container runtime does not support streaming RPCs, the kubelet
+automatically falls back to the standard unary RPCs for backward
+compatibility.
+
 ## {{% heading "whatsnext" %}}
 
 - Learn more about the CRI [protocol definition](https://github.com/kubernetes/cri-api/blob/v0.33.1/pkg/apis/runtime/v1/api.proto)
diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates/CRIListStreaming.md b/content/en/docs/reference/command-line-tools-reference/feature-gates/CRIListStreaming.md
@@ -0,0 +1,19 @@
+---
+title: CRIListStreaming
+content_type: feature_gate
+_build:
+  list: never
+  render: false
+
+stages:
+  - stage: alpha
+    defaultValue: false
+    fromVersion: "1.36"
+---
+Enable streaming RPCs for CRI list operations (`ListContainers`,
+`ListPodSandbox`, `ListImages`). When enabled, the kubelet uses server-side
+streaming RPCs (e.g., `StreamContainers`, `StreamPodSandboxes`) that allow the
+container runtime to divide results across multiple response messages,
+bypassing the 16 MiB gRPC message size limit. This allows listing containers
+on nodes with thousands of containers without failures. If the container
+runtime does not support streaming RPCs, the kubelet falls back to unary RPCs.
