Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions content/en/docs/concepts/containers/cri.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Original file line number Diff line number Diff line change
@@ -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.