diff --git a/content/en/docs/concepts/containers/cri.md b/content/en/docs/concepts/containers/cri.md index ae57ebf366cd1..967f9a1f2b45f 100644 --- a/content/en/docs/concepts/containers/cri.md +++ b/content/en/docs/concepts/containers/cri.md @@ -42,6 +42,28 @@ 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 +(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 new file mode 100644 index 0000000000000..3fa588b0fddfd --- /dev/null +++ b/content/en/docs/reference/command-line-tools-reference/feature-gates/CRIListStreaming.md @@ -0,0 +1,20 @@ +--- +title: CRIListStreaming +content_type: feature_gate +_build: + list: never + render: false + +stages: + - stage: alpha + defaultValue: false + fromVersion: "1.36" +removed: false +--- +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.