# 容器运行时接口（CRI）

LLMS index: [llms.txt](/llms.txt)

---

<!-- 
title: Container Runtime Interface (CRI)
content_type: concept
weight: 60
-->

<!-- overview -->
<!-- 
The CRI is a plugin interface which enables the kubelet to use a wide variety of
container runtimes, without having a need to recompile the cluster components.

You need a working
<a class='glossary-tooltip' title='容器运行时是负责运行容器的软件。' data-bs-toggle='tooltip' data-bs-placement='top' href='/zh-cn/docs/setup/production-environment/container-runtimes' target='_blank' aria-label='container runtime'>container runtime</a> on
each Node in your cluster, so that the
<a class='glossary-tooltip' title='一个在集群中每个节点上运行的代理。它保证容器都运行在 Pod 中。' data-bs-toggle='tooltip' data-bs-placement='top' href='/zh-cn/docs/reference/command-line-tools-reference/kubelet' target='_blank' aria-label='kubelet'>kubelet</a> can launch
<a class='glossary-tooltip' title='Pod 表示你的集群上一组正在运行的容器。' data-bs-toggle='tooltip' data-bs-placement='top' href='/zh-cn/docs/concepts/workloads/pods/' target='_blank' aria-label='Pods'>Pods</a> and their containers.
-->
CRI 是一个插件接口，它使 kubelet 能够使用各种容器运行时，无需重新编译集群组件。

你需要在集群中的每个节点上都有一个可以正常工作的<a class='glossary-tooltip' title='容器运行时是负责运行容器的软件。' data-bs-toggle='tooltip' data-bs-placement='top' href='/zh-cn/docs/setup/production-environment/container-runtimes' target='_blank' aria-label='容器运行时'>容器运行时</a>，
这样 <a class='glossary-tooltip' title='一个在集群中每个节点上运行的代理。它保证容器都运行在 Pod 中。' data-bs-toggle='tooltip' data-bs-placement='top' href='/zh-cn/docs/reference/command-line-tools-reference/kubelet' target='_blank' aria-label='kubelet'>kubelet</a> 能启动
<a class='glossary-tooltip' title='Pod 表示你的集群上一组正在运行的容器。' data-bs-toggle='tooltip' data-bs-placement='top' href='/zh-cn/docs/concepts/workloads/pods/' target='_blank' aria-label='Pod'>Pod</a> 及其容器。

<!--
title: Container Runtime Interface (CRI)
id: cri
full_link: /docs/concepts/architecture/cri
short_description: >
  Protocol for communication between the kubelet and the local container runtime.

aka:
tags:
  - fundamental
-->
<!--
The main protocol for the communication between the <a class='glossary-tooltip' title='一个在集群中每个节点上运行的代理。它保证容器都运行在 Pod 中。' data-bs-toggle='tooltip' data-bs-placement='top' href='/zh-cn/docs/reference/command-line-tools-reference/kubelet' target='_blank' aria-label='kubelet'>kubelet</a> and Container Runtime.
-->
<p><p>容器运行时接口（CRI）是 在 <a class='glossary-tooltip' title='一个在集群中每个节点上运行的代理。它保证容器都运行在 Pod 中。' data-bs-toggle='tooltip' data-bs-placement='top' href='/zh-cn/docs/reference/command-line-tools-reference/kubelet' target='_blank' aria-label='kubelet'>kubelet</a> 与容器运行时之间通信的主要协议。</p></p>
<!--
The Kubernetes Container Runtime Interface (CRI) defines the main
[gRPC](https://grpc.io) protocol for the communication between the
[node components](/docs/concepts/architecture/#node-components)
<a class='glossary-tooltip' title='一个在集群中每个节点上运行的代理。它保证容器都运行在 Pod 中。' data-bs-toggle='tooltip' data-bs-placement='top' href='/zh-cn/docs/reference/command-line-tools-reference/kubelet' target='_blank' aria-label='kubelet'>kubelet</a> and
<a class='glossary-tooltip' title='容器运行时是负责运行容器的软件。' data-bs-toggle='tooltip' data-bs-placement='top' href='/zh-cn/docs/setup/production-environment/container-runtimes' target='_blank' aria-label='container runtime'>container runtime</a>.
-->
<p>Kubernetes 容器运行时接口（CRI）定义了在<a href="/zh-cn/docs/concepts/architecture/#node-components">节点组件</a>
<a class='glossary-tooltip' title='一个在集群中每个节点上运行的代理。它保证容器都运行在 Pod 中。' data-bs-toggle='tooltip' data-bs-placement='top' href='/zh-cn/docs/reference/command-line-tools-reference/kubelet' target='_blank' aria-label='kubelet'>kubelet</a>
和<a class='glossary-tooltip' title='容器运行时是负责运行容器的软件。' data-bs-toggle='tooltip' data-bs-placement='top' href='/zh-cn/docs/setup/production-environment/container-runtimes' target='_blank' aria-label='容器运行时'>容器运行时</a>之间通信的主要
<a href="https://grpc.io">gRPC</a> 协议。</p>

<!-- body -->

<!--
## The API {#api}
-->
## API {#api}








  <div class="feature-state-notice feature-stable">
      <span class="feature-state-name">特性状态：</span>
      <code>Kubernetes v1.23 [stable]</code>
    </div>
  



<!--
The kubelet acts as a client when connecting to the container runtime via gRPC.
The runtime and image service endpoints have to be available in the container
runtime, which can be configured separately within the kubelet by using the
`--container-runtime-endpoint`
[command line flag](/docs/reference/command-line-tools-reference/kubelet/).
-->
当通过 gRPC 连接到容器运行时，kubelet 将充当客户端。运行时和镜像服务端点必须在容器运行时中可用，
可以使用 `--container-runtime-endpoint`
[命令行标志](/zh-cn/docs/reference/command-line-tools-reference/kubelet)在
kubelet 中单独配置。

<!-- 
For Kubernetes v1.26 and later, the kubelet requires that the container runtime
supports the `v1` CRI API. If a container runtime does not support the `v1` API,
the kubelet will not register the node.
-->
对于 Kubernetes v1.26 及更高版本，
kubelet 要求容器运行时必须支持 `v1` 版本的 CRI API。
如果容器运行时不支持 `v1` API，kubelet 将不会注册该节点。

<!-- 
## Upgrading

When upgrading the Kubernetes version on a node, the kubelet restarts. If the
container runtime does not support the `v1` CRI API, the kubelet will fail to
register and report an error. If a gRPC re-dial is required because the container
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.
-->
## 升级  {#upgrading}

在节点上升级 Kubernetes 版本时，kubelet 会重新启动。
如果容器运行时不支持 `v1` 版本的 CRI API，kubelet 将无法注册节点并报告错误。
如果由于容器运行时已升级而需要重新建立 gRPC 连接，
则该容器运行时必须支持 v1 版本的 CRI API，连接才能成功。
在容器运行时正确配置后，可能需要重新启动 kubelet 才能建立连接。

<!--
## List streaming {#list-streaming}
-->
## List 流  {#list-streaming}








  <div class="feature-state-notice feature-alpha" title="特性门控： CRIListStreaming">
              <span class="feature-state-name">特性状态：</span> 
              <code>Kubernetes v1.36 [alpha]</code>（默认禁用）</div>


<!--
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.
-->
标准的 CRI list RPC（`ListContainers`、`ListPodSandbox`、`ListImages`）
会将所有结果返回在一个单一的单元响应中。
在容器数量庞大的节点上（例如，包括运行中的和已停止的容器在内，总数超过约 10,000 个），
这些响应可能会超过 gRPC 默认的 16 MiB 消息大小限制，导致 kubelet 在与容器运行时同步状态时失败。

<!--
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
-->
启用 `CRIListStreaming` 特性后，kubelet 使用服务器端流式
RPC（例如 `StreamContainers`、`StreamPodSandboxes`、`StreamImages`），
允许容器运行时将结果拆分到多个响应消息中，从而绕过单个消息的大小限制。
这对于以下情况尤其有用：

- 容器频繁变更的环境（CI/CD 系统）
- 大规模批处理工作负载

<!--
If the container runtime does not support streaming RPCs, the kubelet
automatically falls back to the standard unary RPCs for backward
compatibility.
-->
如果容器运行时不支持流式 RPC，kubelet 会自动回退到标准一元 RPC 以实现向后兼容。

## 接下来

<!-- 
- Learn more about the CRI [protocol definition](https://github.com/kubernetes/cri-api/blob/v0.33.1/pkg/apis/runtime/v1/api.proto)
-->
- 了解更多有关 CRI [协议定义](https://github.com/kubernetes/cri-api/blob/v0.33.1/pkg/apis/runtime/v1/api.proto)