容器运行时：从 CRI 到容器进程¶

容器运行时负责根据 Pod 的运行配置在节点上创建和管理容器，并维护镜像与容器状态。Kubelet 通过 CRI 向容器运行时发送创建、启动、停止和删除请求。创建容器时，运行时准备镜像与运行环境，协调 Pod 网络接入，并将 Kubelet 已经准备好的 Volume 挂载到容器中。

容器运行时¶

按照调用层级，容器运行时可以分为高级容器运行时和低级容器运行时。这里的“高级”和“低级”表示它们在调用链中的位置，不表示功能强弱。

• 高级容器运行时：负责镜像管理、容器网络以及与 Kubernetes 等编排系统的集成。常见实现包括 containerd、CRI-O 和 Docker Engine。
• 低级容器运行时：负责实际执行容器，根据 OCI Bundle 创建隔离环境并启动容器进程。常见实现包括 runc、crun、gVisor 和 Kata Containers。

CRI 是 Kubelet 与高级容器运行时之间的标准接口，定义了拉取镜像、创建 Pod Sandbox 和管理容器等请求。containerd 和 CRI-O 实现 CRI，接收 Kubelet 的请求并管理镜像与容器状态；创建普通 Linux 容器时，它们再调用 runc、crun 等执行后端启动容器进程。下图展示了这条调用关系。

图：Kubelet、CRI、高级容器运行时与 OCI 执行后端的分层关系。来源：Vikas Yadav，Why CRI Matters: Enhancing Kubernetes with Standardized Runtimes!

CRI¶

容器运行时接口（Container Runtime Interface，CRI）是 Kubernetes 中基于 gRPC 的标准化 API 层。gRPC 是一种高性能远程过程调用协议，Kubelet 通过它与 containerd、CRI-O 等容器运行时通信。

CRI 抽象了拉取镜像、启动和停止容器等生命周期操作，使 Kubernetes 无需修改便可使用不同的容器运行时。它包含两个核心组件，用于定义 Kubernetes 与容器运行时的协作方式：

• RuntimeService：处理容器的生命周期。它管理 Pod Sandbox，使容器能够在需要时共享网络和存储等资源。
• ImageService：管理运行时使用的容器镜像。它通过镜像拉取和缓存提高部署效率。

在 CRI 出现之前，Kubernetes 需要分别与每种运行时直接集成，导致系统过度依赖通用型运行时，也限制了开发者体验和性能选择。

使用 CRI 后，Kubernetes 保持了灵活、模块化的运行时架构。组织可以避免厂商锁定，并根据实际需求选择合适的运行时。

CRI 的演进¶

下图展示了 Kubernetes CRI 的演进过程。

%%{init: {"flowchart": {"nodeSpacing": 22, "rankSpacing": 42}, "themeVariables": {"fontSize": "14px"}}}%%
flowchart TB
    subgraph BEFORE["Kubernetes 1.5 以前"]
        direction LR
        BEFORE_KUBELET["Kubelet<br/>运行时专用适配代码"]
        BEFORE_DOCKER["Docker Engine"]
        BEFORE_RKT["rkt"]
        BEFORE_KUBELET -->|"Docker 专用适配"| BEFORE_DOCKER
        BEFORE_KUBELET -->|"rkt 专用适配"| BEFORE_RKT
        BEFORE_DOCKER --> BEFORE_CONTAINER_1["Container"]
        BEFORE_DOCKER --> BEFORE_CONTAINER_2["Container"]
        BEFORE_RKT --> BEFORE_CONTAINER_3["Container"]
    end

    subgraph CRI_PHASE["CRI 引入后、dockershim 移除前（1.5–1.23）"]
        direction LR
        CRI_KUBELET["Kubelet"]
        DOCKERSHIM["dockershim<br/>Kubelet 内置"]
        DOCKER_ENGINE["Docker Engine"]
        CONTAINERD["containerd 1.1<br/>内置 CRI Plugin<br/>Kubernetes 1.10+"]
        CRIO["CRI-O<br/>直接实现 CRI"]

        CRI_KUBELET -->|"CRI gRPC"| DOCKERSHIM
        DOCKERSHIM -->|"Docker API"| DOCKER_ENGINE
        CRI_KUBELET -->|"CRI gRPC"| CONTAINERD
        CRI_KUBELET -->|"CRI gRPC"| CRIO
        DOCKER_ENGINE --> CRI_CONTAINER_1["Container"]
        CONTAINERD --> CRI_CONTAINER_2["Container"]
        CRIO --> CRI_CONTAINER_3["Container"]
    end

    subgraph CURRENT["Kubernetes 1.24 及以后"]
        direction LR
        CURRENT_KUBELET["Kubelet"]
        CURRENT_RUNTIME["containerd / CRI-O<br/>直接提供 CRI Endpoint"]
        CURRENT_KUBELET -->|"CRI gRPC"| CURRENT_RUNTIME
        CURRENT_RUNTIME --> CURRENT_CONTAINER_1["Container"]
        CURRENT_RUNTIME --> CURRENT_CONTAINER_2["Container"]
        CURRENT_RUNTIME --> CURRENT_CONTAINER_3["Container"]
    end

    BEFORE ~~~ CRI_PHASE
    CRI_PHASE ~~~ CURRENT

    classDef kubelet fill:#eef3ff,stroke:#4c64e8,stroke-width:1.5px;
    classDef adapter fill:#f3efff,stroke:#7650d8,stroke-width:1.5px;
    classDef runtime fill:#effbf3,stroke:#22875a,stroke-width:1.5px;
    classDef container fill:#ffffff,stroke:#5f6470,stroke-width:1.25px;

    class BEFORE_KUBELET,CRI_KUBELET,CURRENT_KUBELET kubelet;
    class DOCKERSHIM adapter;
    class BEFORE_DOCKER,BEFORE_RKT,DOCKER_ENGINE,CONTAINERD,CRIO,CURRENT_RUNTIME runtime;
    class BEFORE_CONTAINER_1,BEFORE_CONTAINER_2,BEFORE_CONTAINER_3,CRI_CONTAINER_1,CRI_CONTAINER_2,CRI_CONTAINER_3,CURRENT_CONTAINER_1,CURRENT_CONTAINER_2,CURRENT_CONTAINER_3 container;

• Kubernetes 1.5 以前：Kubelet 源码中维护 Docker、rkt 等运行时各自的适配代码。Kubernetes 1.5 开始以 Alpha 功能提供 CRI。

• Kubernetes 1.5–1.23：Kubelet 内置适配和运行时直接实现 CRI 的方式曾经并存：

  • Docker Engine：Kubelet 内置 dockershim，将 CRI 请求转换为 Docker API。
  • containerd：containerd 1.1 将 CRI Plugin 集成到 containerd 进程中，支持 Kubernetes 1.10 及以上版本。
  • CRI-O：CRI-O 直接提供 CRI 服务。

• Kubernetes 1.24 及以后：Kubelet 移除内置 dockershim，通过 CRI Endpoint 连接 containerd、CRI-O 等运行时。

RuntimeService¶

RuntimeService 管理 Pod Sandbox、容器进程以及节点运行时状态。Kubelet 先通过 RunPodSandbox 请求运行时创建 Pod Sandbox，准备 Pod 内容器共享的网络等运行环境。随后使用 CreateContainer 和 StartContainer 创建并启动 Init Container、Sidecar Container 与 App Container。

ImageService¶

ImageService 管理节点本地镜像。Kubelet 根据 PodSpec 和本地缓存状态决定是否拉取镜像，再把镜像引用、Registry 认证信息和 Pod Sandbox 配置传给 PullImage。容器运行时从镜像仓库下载镜像，校验镜像数据，并保存到节点本地，供后续创建容器使用。

CRI 调用链¶

Pod 分配到节点后，Kubelet 通过 CRI 请求容器运行时创建 Pod Sandbox、准备镜像并启动容器。下图以 containerd 为例，展示镜像拉取策略为 IfNotPresent、节点尚未缓存应用镜像时的调用过程。

• 创建 Pod Sandbox（图中 1–3）：Kubelet 调用 RuntimeService 的 RunPodSandbox。containerd 创建 Pod Sandbox 并配置网络，完成后向 Kubelet 返回 Sandbox ID。
• 检查本地镜像（图中 4–5）：Kubelet 调用 ImageService 的 ImageStatus，查询应用镜像是否已在节点上。图中镜像尚未缓存，因此需要继续拉取。
• 拉取镜像（图中 6–8）：Kubelet 调用 ImageService 的 PullImage。containerd 从镜像仓库下载并解包镜像，完成后返回镜像引用，供后续创建容器使用。
• 创建容器（图中 9–11）：Kubelet 调用 RuntimeService 的 CreateContainer，传入 Sandbox ID 和容器配置。containerd 保存容器元数据并生成 OCI 运行配置，返回 Container ID。
• 启动容器（图中 12–14）：Kubelet 使用 Container ID 调用 RuntimeService 的 StartContainer。containerd 创建并启动容器进程，成功后向 Kubelet 返回响应。

sequenceDiagram
    autonumber
    participant K as Kubelet Runtime Manager
    box transparent containerd CRI Plugin
        participant R as CRI RuntimeService
        participant I as CRI ImageService
    end

    K->>R: RunPodSandbox(config, runtimeHandler)
    R->>R: Create sandbox and configure network
    R-->>K: Sandbox ID
    K->>I: ImageStatus(image)
    I-->>K: Image not present
    K->>I: PullImage(image, auth, sandboxConfig)
    I->>I: Fetch and unpack image
    I-->>K: Image reference
    K->>R: CreateContainer(sandboxID, config)
    R->>R: Create container metadata and OCI spec
    R-->>K: Container ID
    K->>R: StartContainer(containerID)
    R->>R: Create and start task
    R-->>K: Success

crictl¶

crictl 是 Kubernetes SIG Node 维护的 CRI 调试客户端。它调用 RuntimeService 和 ImageService，适合检查 Kubelet 所看到的 Pod Sandbox、Container、Image 和运行时状态。

可以在 /etc/crictl.yaml 中配置 crictl 连接的 RuntimeService 和 ImageService 地址：

runtime-endpoint: unix:///run/containerd/containerd.sock
image-endpoint: unix:///run/containerd/containerd.sock
timeout: 10
debug: false

常用命令分别查看运行时状态、Sandbox、容器和镜像：

# 查看当前节点的容器运行时信息
crictl info

# 列出当前节点的 Pod Sandbox
crictl pods

# 列出当前节点的所有容器，包括已退出的容器
crictl ps --all

# 列出当前节点的本地镜像
crictl images

# 查看指定 Pod Sandbox 的详细信息
crictl inspectp "$POD_ID"

# 查看指定容器的详细信息
crictl inspect "$CONTAINER_ID"

高级容器运行时¶

高级容器运行时是常驻在节点上的管理服务。它接收 Docker API、containerd API 或 CRI 请求，管理镜像、rootfs、容器配置和运行状态，再调用低级容器运行时创建并启动容器。

常见的高级容器运行时有 Docker Engine、containerd 和 CRI-O：

Docker Engine¶

Docker Engine 提供面向用户和开发工具的容器 API。它管理 Image、Container、Network、Volume 等 Docker 对象，并把容器生命周期交给 containerd。

Kubernetes 1.24 移除了 Kubelet 内置的 dockershim。Docker Engine 本身不实现 CRI，需要继续使用 Docker Engine 作为节点容器运行时时，可以通过外置的 cri-dockerd 接入 Kubelet。

组件架构¶

Docker Engine 使用 Client-Server 架构。下图展示了 Docker Client、dockerd、Registry，以及镜像、容器等资源之间的关系。

图：Docker Engine Client-Server 架构。来源：Docker Architecture。

• Docker Client：docker CLI 将 run、pull、build 等命令转换成 Docker API 请求。Client 可以连接本机 Unix Socket，也可以通过配置连接远端 daemon。
• Docker API：Docker SDK 和 CLI 通过同一组 HTTP API 管理镜像、容器、网络和数据卷。
• dockerd：dockerd 处理 API 请求，保存这些资源的元数据，并管理它们的生命周期。
• containerd：Docker Engine 使用 containerd 管理容器生命周期。containerd 准备 Task 并连接 Runtime v2 Shim，默认路径继续调用 runc。
• Registry：docker pull 从 Registry 取得 Image Manifest、Config 和 Layer；docker push 将本地构建结果上传到 Registry。

使用方式¶

docker version 同时查询 Client 和 Server。docker info 展示 daemon 当前使用的 Runtime、Storage Driver 和 cgroup 配置：

docker version --format \
  'Client={{.Client.Version}} Server={{.Server.Version}} API={{.Server.APIVersion}}'
# 输出示例
Client=29.4.0 Server=29.4.0 API=1.54

docker info --format \
  'DefaultRuntime={{.DefaultRuntime}} StorageDriver={{.Driver}} CgroupDriver={{.CgroupDriver}} CgroupVersion={{.CgroupVersion}}'
# 输出示例
DefaultRuntime=runc StorageDriver=overlay2 CgroupDriver=cgroupfs CgroupVersion=2

下面的命令拉取 Alpine Image、创建 Container，并在 Container 中启动一个进程。--rm 在进程退出后删除 Container 元数据和可写层：

docker run --rm alpine:3.22 \
  sh -c 'printf "pid=%s hostname=%s\n" "$$" "$(hostname)"'

containerd¶

containerd 是面向系统组件的容器运行时，负责管理镜像、容器文件系统和容器生命周期。Docker Engine 和 Kubernetes 都可以把它作为节点上的运行时管理层。

核心概念¶

containerd 在拉取镜像、准备容器文件系统和运行容器时，涉及以下核心概念和服务：

• Image：镜像的元数据记录，保存镜像名称、标签，以及指向镜像清单（Manifest）或索引（Index）的描述信息。例如，docker.io/library/alpine:3.22 这个名称通过 Image 记录关联到具体的镜像内容。
• Content：镜像的原始内容，包括 Index、Manifest、配置和镜像层。Content Store 是 containerd 在节点上保存和读取这些内容的存储组件。它将每份内容作为独立的数据块（Blob）保存，并以内容摘要（Digest）作为标识。相同内容只需保存一份，可以被多个镜像复用。
• Snapshot：容器文件系统的快照，记录文件系统状态，不包含进程内存。Snapshotter 是创建和管理这些快照的存储插件。它为镜像解包准备文件系统，为容器准备可写层，并提供挂载根文件系统（rootfs）所需的信息。常见实现包括 overlayfs（默认）、native、blockfile、devmapper、btrfs、zfs 和 erofs。
• Diff：计算和应用文件系统差异。镜像解包时，它读取 Content Store 中的镜像层，将文件的新增、修改和删除应用到 Snapshotter 准备的文件系统中；生成镜像层时，它计算两个文件系统状态之间的差异，并将结果保存到 Content Store。
• Container：容器的持久化配置，记录使用哪个镜像、文件系统和运行时，以及要执行的命令等信息。创建 Container 是保存这份配置，实际进程由 Task 管理。
• Task：容器的进程执行实例，用于管理进程的启动、暂停、终止、输入输出和退出状态。Task 被删除后，Container 配置仍可保留，用于再次创建 Task。
• Events：事件发布与订阅服务，用于传递镜像、容器和任务的状态变化。例如，容器进程退出后，TaskExit 事件携带容器 ID、PID、退出码和退出时间，订阅者可以据此更新状态。

下图展示了 containerd 的主要服务及其职责划分。

图：containerd 核心服务架构。来源：containerd v2.3.4 README。

容器运行过程¶

containerd 创建并启动容器的过程分为以下三个步骤：

• 创建 Container：客户端请求 Container Service 保存镜像引用、运行时选择、Snapshot 引用和 OCI 运行配置等元数据。这一步建立 Container 记录，供后续创建 Task 使用，应用进程尚未创建。
• 创建 Task：客户端请求 Task Service 创建 Task。Task Service 读取 Container 配置，再通过 TaskManager.Create 准备 Bundle、建立或复用 Shim 连接，并向 Shim 发送创建请求。Shim 调用低级容器运行时准备容器的初始进程；在 runc 路径中，此时尚未执行应用入口命令。
• 启动 Task：客户端向 Task Service 发送 Start 请求。containerd 将请求交给 Shim，由运行时启动应用命令，成功后向客户端返回进程 PID。

下图展示了客户端通过 Container Service 和 Task Service 创建并启动容器的调用过程。

图：Container 与 Task 的创建和启动。来源：Cai Wei、Shaobao Feng，Build Container Runtime Based on Sandbox API of Containerd，KubeCon + CloudNativeCon China 2024，第 7 页。

CRI Plugin¶

CRI Plugin 实现了 Kubernetes 的容器运行时接口（CRI）。containerd 与 Kubelet 运行在同一个节点上，内置的 CRI Plugin 处理来自 Kubelet 的所有 CRI 服务请求，并调用 containerd 的内部功能管理容器和镜像。

CRI Plugin 使用 containerd 管理容器的完整生命周期和镜像，并通过 CNI 管理 Pod 网络。下图展示了这些组件之间的关系。

图：containerd CRI Plugin 架构。

以 Kubelet 创建一个只包含单个应用容器的 Pod 为例，CRI Plugin 的处理过程如下：

1. Kubelet 通过 CRI RuntimeService API 调用 CRI Plugin，请求创建 Pod 的运行环境。
2. CRI Plugin 创建 Pod 的网络命名空间，并使用 CNI 配置网络。
3. CRI Plugin 调用 containerd 的内部功能，创建并启动一个特殊的 pause 容器（Sandbox Container），将它放入 Pod 的 cgroup 和命名空间中。
4. Kubelet 通过 CRI ImageService API 调用 CRI Plugin，请求拉取应用容器的镜像。
5. 如果节点上没有该镜像，CRI Plugin 使用 containerd 拉取镜像。
6. Kubelet 通过 CRI RuntimeService API 调用 CRI Plugin，请求使用已拉取的镜像在 Pod 内创建并启动应用容器。
7. CRI Plugin 调用 containerd 的内部功能创建应用容器，将它放入 Pod 的 cgroup 和命名空间中，然后启动容器。

完成这些操作后，Pod 的运行环境已经建立，应用容器开始运行。

Runtime v2 与 Shim¶

Runtime v2 为低级容器运行时提供接入 containerd 的 Shim API，接口主要处理容器的执行生命周期。containerd 管理镜像内容、文件系统和容器配置，再通过这组接口请求运行时创建、启动和停止容器。

containerd 通过 Shim 接入具体的运行时。以 runc 为例，containerd-shim-runc-v2 负责接收 containerd 的请求，再调用运行时引擎 runc 完成容器的创建、启动和停止。

下图展示了 containerd、Shim 与容器之间的关系：

• 请求与事件：containerd 通过 Socket 向 Shim 的 Task Service 发送创建、启动和停止等请求。Shim 将容器状态变化等事件转发给 containerd 的 Event Service，对应图中反向的事件箭头。右侧列出了 Task Service 的接口。
• Shim 与容器：一个 Shim 可以管理多个容器。在 runc 路径中，containerd-shim-runc-v2 接收 Task 请求，再调用 runc 完成容器的创建、启动等操作。runc 完成创建后退出，但它创建的容器初始进程仍然存在。Linux 内核将这个失去父进程的容器初始进程交给作为 Subreaper 的 Shim，使 Shim 成为它的新父进程。Shim 继续维护容器进程的输入输出和退出状态，并在容器进程退出后回收。
• 不同运行时接入：containerd-shim-runc-v2、containerd-shim-wasmtime-v1 和 containerd-shim-kata-v2 分别用于将 runc、Wasmtime 和 Kata 接入 containerd。containerd 通过 Task API 发送容器操作请求，由对应的 Shim 和运行时完成执行。

图：Task & Shim。来源：Cai Wei、Shaobao Feng，Build Container Runtime Based on Sandbox API of Containerd，KubeCon + CloudNativeCon China 2024，第 8 页。

Sandbox API¶

在引入 Sandbox API 之前，containerd 尚未为容器组的共享运行环境提供独立的管理接口。pause 容器的生命周期和 Sandbox 元数据都由 CRI Plugin 管理，这种实现存在以下限制：

• 实现依赖 pause 容器：Pod Sandbox 的管理流程以 pause 容器为基础。对于需要自行管理虚拟机监控器（VMM）的运行时，缺少统一的 Sandbox 接入接口。
• 缺少生命周期扩展点：Sandbox 的创建、启动、停止和清理逻辑位于 CRI Plugin 内部，运行时开发者难以通过独立接口定制这些行为。
• 生命周期以 Task 为中心：原有接口围绕 Task 的创建和销毁组织运行时操作，而 Sandbox 需要在内部容器不断创建、退出时保持运行。管理共享环境的 Shim 因此需要独立的生命周期控制。

Sandbox API 将一组容器共享的运行环境定义为 Sandbox，并在 Runtime v2 Shim 架构上提供专门的生命周期管理接口。其设计目标是：

• 统一容器组管理：通过统一的 Controller 接口 管理共享运行环境，使 microVM 等不同实现能够通过同一接口接入。Shim 侧的 RPC 定义见 SandboxService。
• 将具体实现与 CRI Plugin 解耦：让运行时开发者通过实现接口提供自己的 Sandbox，而无需为每种实现修改 containerd 或 CRI Plugin。pause 容器成为一种 Sandbox 实现，而不是固定的实现前提。

组件与接口¶

以下三个接口用于管理 Sandbox 的生命周期：

• Sandbox Controller Service：containerd 提供给进程外客户端的 gRPC 接口。SDK 客户端或 ctr sandboxes run 等命令通过它发送 Sandbox 管理请求，containerd 再将请求交给选定的 Sandbox Controller。独立于 containerd 进程运行的 Sandbox 管理程序（外部 sandboxer）也可以提供这一服务，由 containerd 内部的 proxy plugin 通过 gRPC 调用。
• Sandbox Controller：定义 Sandbox 的创建、启动、停止和清理等操作，由 podsandbox、shim 等 Controller 负责具体实现。CRI Plugin 直接调用选定的 Sandbox Controller 管理 Sandbox，无需经过面向进程外客户端的 Sandbox Controller Service。
• Runtime Sandbox Service：运行时通过 Shim 提供的 Sandbox 管理服务。containerd 的 shim Controller 调用它，完成 Sandbox 的创建、启动、停止和清理。

图：Sandbox API 的接口与调用关系。根据 containerd v2.3.4 Sandbox API 及上述源码绘制。

Sandbox Controller 实现¶

containerd v2.3.4 提供 podsandbox 和 shim 两种内置的 Sandbox Controller 实现。两种实现都会使用 Shim。下图分别展示了它们创建和启动 Sandbox 的执行路径。

• podsandbox：沿用 Sandbox API 引入前的 pause 容器方案，通过 Task Service 创建和启动 pause 容器，维持 Pod 的共享运行环境。 当前实现位于 CRI Plugin 内部，也实现了 Sandbox Controller 接口。具体流程为：

  1. Create：初始化并保存控制器内部的 Sandbox 状态。

  2. Start：准备并启动 pause 容器，依次完成以下操作：

     1. 创建 pause 容器的 Container 记录：Controller 调用 NewContainer，通过 Container Service 保存 pause 容器的运行配置、Snapshot 引用和运行时选择。
     2. 创建 pause 容器的 Task：Controller 调用 NewTask。Task Service 经由 TaskManager.Create 建立 Shim 连接，再向 Shim 的 Task Service 发送创建请求，准备 pause 容器的初始进程。
     3. 启动 pause 进程：Controller 调用 task.Start，请求经 Task Service 传到 Shim，启动 pause 进程。后续业务容器根据 Pod 配置加入这些共享 Namespace。

• shim：采用 Sandbox API 的原生管理方式，通过专门的 Runtime Sandbox Service 直接管理 Sandbox 的生命周期。 Controller 调用支持 Sandbox RPC 的 Shim 完成具体操作，共享运行环境可以由运行时实现为轻量虚拟机等形式：

  1. Create：准备 Sandbox 并建立与 Shim 的连接，依次完成以下操作：

     1. 准备 Bundle：Controller 调用 NewBundle，按 Sandbox ID 创建 Bundle 目录。
     2. 启动 Shim：Controller 通过 ShimManager 启动 Sandbox 对应的 Shim，建立后续 RPC 调用所需的连接。
     3. 创建 Sandbox：Controller 向 Shim 的 Sandbox Service 发送 CreateSandbox 请求，传入 Sandbox ID、Bundle 路径和网络 Namespace 路径等信息，由 Shim 准备共享运行环境。

  2. Start：向 Shim 的 Sandbox Service 发送 StartSandbox 请求，启动已经创建的 Sandbox，并取得 PID 和连接地址等信息。

  同一个 Shim 通过 Sandbox Service 管理 Sandbox，通过 Task Service 管理其中的容器进程。创建业务容器的 Task 时，containerd 复用该 Sandbox 的 Shim 连接。

图：Sandbox API 与 Shim 的两条执行路径。来源：Cai Wei、Shaobao Feng，Build Container Runtime Based on Sandbox API of Containerd，KubeCon + CloudNativeCon China 2024，第 13 页。

命令行工具¶

ctr¶

ctr 是随 containerd 一起发布的命令行调试工具，直接调用 containerd API。它可以查询 Plugin、Namespace、Image、Content、Snapshot、Container 和 Task 等信息，并执行镜像拉取、容器运行等操作。

ctr 默认使用 default Namespace。Kubernetes 对象通常位于 k8s.io，查询时需要显式指定：

# 查看 containerd 的插件及其状态
ctr plugins list

# 查看 containerd 中的 Namespace
ctr namespaces list

# 查看 k8s.io Namespace 中的镜像
ctr --namespace k8s.io images list

# 查看 k8s.io Namespace 中的 Container 记录
ctr --namespace k8s.io containers list

# 查看 k8s.io Namespace 中的 Task 及其状态
ctr --namespace k8s.io tasks list

下面的命令在独立的 ctr-demo Namespace 中运行 Alpine，并清理示例资源。删除镜像时使用 --sync 等待关联资源回收，再删除 Namespace：

# 创建示例使用的 Namespace
ctr namespaces create ctr-demo

# 拉取并解包 Alpine 镜像
ctr --namespace ctr-demo images pull docker.io/library/alpine:3.22

# 在 Alpine 容器中执行 uname -a，退出后删除 Container 和 Task
ctr --namespace ctr-demo run --rm \
  docker.io/library/alpine:3.22 \
  alpine-demo \
  uname -a

# 删除示例镜像，并等待不再使用的关联资源回收
ctr --namespace ctr-demo images remove --sync docker.io/library/alpine:3.22

# 删除示例 Namespace
ctr namespaces remove ctr-demo

nerdctl¶

nerdctl 是面向 containerd、兼容 Docker CLI 的命令行工具，可用于管理容器、镜像、网络和数据卷。它支持 Docker Compose、Rootless Mode，并通过 BuildKit 构建镜像。

安装步骤及网络、数据卷的使用方式见 nerdctl 示例。

下面在 nerdctl-demo Namespace 中创建网络和数据卷，再运行 Alpine 容器，将数据卷挂载到容器的 /data 目录。示例使用 bridge 网络，需要节点已安装 CNI Plugins：

# 创建示例使用的 Namespace
nerdctl namespace create nerdctl-demo

# 创建名为 demo-net 的 bridge 网络
nerdctl --namespace nerdctl-demo network create --driver bridge demo-net

# 查看 demo-net 的网络配置
nerdctl --namespace nerdctl-demo network inspect demo-net

# 创建名为 demo-data 的数据卷
nerdctl --namespace nerdctl-demo volume create demo-data

# 查看 demo-data 的存储路径等信息
nerdctl --namespace nerdctl-demo volume inspect demo-data

# 连接 demo-net 并挂载 demo-data，执行 uname -a 后自动删除容器
nerdctl --namespace nerdctl-demo run --rm \
  --name alpine-demo \
  --network demo-net \
  --volume demo-data:/data \
  alpine:3.22 uname -a

# 查看 nerdctl-demo Namespace 中的镜像
nerdctl --namespace nerdctl-demo images

# 查看 nerdctl-demo Namespace 中的所有容器，包括已停止的容器
nerdctl --namespace nerdctl-demo ps --all

# 删除示例网络
nerdctl --namespace nerdctl-demo network rm demo-net

# 删除示例数据卷，命名数据卷不会随 --rm 自动删除
nerdctl --namespace nerdctl-demo volume rm demo-data

查看当前节点上 Kubernetes 使用的容器和镜像时，指定 k8s.io Namespace：

# 查看 Kubernetes 使用的所有容器，包括已停止的容器
nerdctl --namespace k8s.io ps --all

# 查看 Kubernetes 使用的本地镜像
nerdctl --namespace k8s.io images

SDK¶

containerd 提供 Go Client SDK，便于在自己的项目中调用 containerd。

示例通过 Client SDK 拉取并运行 Redis Server，需要在已运行 containerd 的 Linux 环境中执行。Go 版本要求见 containerd v2.3.4 的 go.mod。

连接 containerd

创建 main.go，导入 containerd Client 包，并连接默认的 containerd Socket：

package main

import (
    "log"

    containerd "github.com/containerd/containerd/v2/client"
)

func main() {
    if err := redisExample(); err != nil {
        log.Fatal(err)
    }
}

func redisExample() error {
    client, err := containerd.New("/run/containerd/containerd.sock")
    if err != nil {
        return err
    }
    defer client.Close()
    return nil
}

containerd.New 创建连接到 /run/containerd/containerd.sock 的 Client。Client 通过 gRPC 与 containerd daemon 通信，调用方法时需要传入 context。containerd 使用 Namespace 区分 API 调用方管理的资源，这里通过 namespaces.WithNamespace 设置 example Namespace：

    ctx := namespaces.WithNamespace(context.Background(), "example")

使用独立的 Namespace，可以避免示例中的容器、镜像等资源与同一个 daemon 的其他使用者发生命名冲突。

拉取 Redis 镜像

使用 Client 从 Docker Hub 拉取基于 Alpine Linux 的 Redis 镜像：

    image, err := client.Pull(ctx, "docker.io/library/redis:alpine", containerd.WithPullUnpack)
    if err != nil {
        return err
    }

containerd Client 的许多方法通过 Opts 参数配置行为。containerd.WithPullUnpack 使镜像内容下载到 Content Store 后继续解包，通过 Snapshotter 准备后续容器使用的根文件系统。

下面的代码完成镜像拉取，并在终端打印镜像名称：

package main

import (
        "context"
        "log"

        containerd "github.com/containerd/containerd/v2/client"
        "github.com/containerd/containerd/v2/pkg/namespaces"
)

func main() {
        if err := redisExample(); err != nil {
                log.Fatal(err)
        }
}

func redisExample() error {
        client, err := containerd.New("/run/containerd/containerd.sock")
        if err != nil {
                return err
        }
        defer client.Close()

        ctx := namespaces.WithNamespace(context.Background(), "example")
        image, err := client.Pull(ctx, "docker.io/library/redis:alpine", containerd.WithPullUnpack)
        if err != nil {
                return err
        }
        log.Printf("Successfully pulled %s image\n", image.Name())

        return nil
}

编译和运行命令，以及官方文档中的输出示例：

> go build main.go
> sudo ./main

2017/08/13 17:43:21 Successfully pulled docker.io/library/redis:alpine image

创建 OCI Spec 与 Container

取得镜像后，需要为容器生成 OCI 运行配置，并创建 Container。containerd 提供默认的 OCI Spec，也支持通过选项将镜像中的配置应用到 Spec。

下面的代码为容器分配一个可写 Snapshot，并根据镜像配置生成 OCI Spec：

    container, err := client.NewContainer(
        ctx,
        "redis-server",
        containerd.WithNewSnapshot("redis-server-snapshot", image),
        containerd.WithNewSpec(oci.WithImageConfig(image)),
    )
    if err != nil {
        return err
    }
    defer container.Delete(ctx, containerd.WithSnapshotCleanup)

如果已经有 OCI Spec，可以使用 containerd.WithSpec 将它设置到 Container 上。

创建 Snapshot 时需要提供 Snapshot ID 和作为基础的 Image。Snapshot ID 与 Container ID 分开指定，便于在不同 Container 之间复用已有的 Snapshot。containerd.WithSnapshotCleanup 则在删除 Container 时一并清理它使用的 Snapshot。

下面的代码拉取 Redis 镜像、生成 OCI Spec、创建 Container，并在函数退出时删除 Container 和 Snapshot：

package main

import (
        "context"
        "log"

        containerd "github.com/containerd/containerd/v2/client"
        "github.com/containerd/containerd/v2/pkg/namespaces"
        "github.com/containerd/containerd/v2/pkg/oci"
)

func main() {
        if err := redisExample(); err != nil {
                log.Fatal(err)
        }
}

func redisExample() error {
        client, err := containerd.New("/run/containerd/containerd.sock")
        if err != nil {
                return err
        }
        defer client.Close()

        ctx := namespaces.WithNamespace(context.Background(), "example")
        image, err := client.Pull(ctx, "docker.io/library/redis:alpine", containerd.WithPullUnpack)
        if err != nil {
                return err
        }
        log.Printf("Successfully pulled %s image\n", image.Name())

        container, err := client.NewContainer(
                ctx,
                "redis-server",
                containerd.WithNewSnapshot("redis-server-snapshot", image),
                containerd.WithNewSpec(oci.WithImageConfig(image)),
        )
        if err != nil {
                return err
        }
        defer container.Delete(ctx, containerd.WithSnapshotCleanup)
        log.Printf("Successfully created container with ID %s and snapshot with ID redis-server-snapshot", container.ID())

        return nil
}

编译和运行命令，以及官方文档中的输出示例：

> go build main.go
> sudo ./main

2017/08/13 18:01:35 Successfully pulled docker.io/library/redis:alpine image
2017/08/13 18:01:35 Successfully created container with ID redis-server and snapshot with ID redis-server-snapshot

创建 Task

Container 是保存配置并关联资源的元数据对象，Task 对应实际的进程执行实例。每次运行结束后应删除 Task，Container 则可以继续保留、更新和查询。

通过 container.NewTask 创建 Task：

    task, err := container.NewTask(ctx, cio.NewCreator(cio.WithStdio))
    if err != nil {
        return err
    }
    defer task.Delete(ctx)

cio.WithStdio 将容器的标准输入、输出和错误连接到示例程序，使 Redis 日志能够显示在当前终端。

此时 Task 处于 OCI 生命周期的 created 状态。命名空间、根文件系统和容器级配置已经初始化，但用户指定的 redis-server 尚未启动。调用方可以在此时设置网络接口或连接监控工具，containerd 也会准备退出状态和 cgroup 指标的监控。

将 containerd 的 Metrics 监听地址配置为 127.0.0.1:1338 后，可以按原文使用以下命令查看容器指标。Metrics 服务源码注册了 /v1/metrics 路径；监听地址为空时，该服务不会启动：

> curl 127.0.0.1:1338/v1/metrics

等待与启动 Task

在启动 Task 之前调用 task.Wait，先建立退出通知，再调用 task.Start。这样可以避免执行 /bin/true 等立即退出的程序时，因等待建立得太晚而出现竞态：

    exitStatusC, err := task.Wait(ctx)
    if err != nil {
        return err
    }

    if err := task.Start(ctx); err != nil {
        return err
    }

Task 启动后，终端中会显示 redis-server 的日志。

终止 Task

Redis Server 会持续运行。示例等待 3 秒，让终端显示日志，然后通过 task.Kill 发送 SIGTERM，等待进程退出并获取退出状态：

    time.Sleep(3 * time.Second)

    if err := task.Kill(ctx, syscall.SIGTERM); err != nil {
        return err
    }

    status := <-exitStatusC
    code, exitedAt, err := status.Result()
    if err != nil {
        return err
    }
    fmt.Printf("redis-server exited with status: %d\n", code)

从退出通知通道读取状态，可以确认 Task 已经结束并取得退出码。如果重新加载了 Container，或之前没有等待 Task 退出，task.Delete 也会返回退出状态：

status, err := task.Delete(ctx)

package main

import (
    "context"
    "fmt"
    "log"
    "syscall"
    "time"

    "github.com/containerd/containerd/v2/pkg/cio"
    containerd "github.com/containerd/containerd/v2/client"
    "github.com/containerd/containerd/v2/pkg/oci"
    "github.com/containerd/containerd/v2/pkg/namespaces"
)

func main() {
    if err := redisExample(); err != nil {
        log.Fatal(err)
    }
}

func redisExample() error {
    // create a new client connected to the default socket path for containerd
    client, err := containerd.New("/run/containerd/containerd.sock")
    if err != nil {
        return err
    }
    defer client.Close()

    // create a new context with an "example" namespace
    ctx := namespaces.WithNamespace(context.Background(), "example")

    // pull the redis image from DockerHub
    image, err := client.Pull(ctx, "docker.io/library/redis:alpine", containerd.WithPullUnpack)
    if err != nil {
        return err
    }

    // create a container
    container, err := client.NewContainer(
        ctx,
        "redis-server",
        containerd.WithImage(image),
        containerd.WithNewSnapshot("redis-server-snapshot", image),
        containerd.WithNewSpec(oci.WithImageConfig(image)),
    )
    if err != nil {
        return err
    }
    defer container.Delete(ctx, containerd.WithSnapshotCleanup)

    // create a task from the container
    task, err := container.NewTask(ctx, cio.NewCreator(cio.WithStdio))
    if err != nil {
        return err
    }
    defer task.Delete(ctx)

    // make sure we wait before calling start
    exitStatusC, err := task.Wait(ctx)
    if err != nil {
        return err
    }

    // call start on the task to execute the redis server
    if err := task.Start(ctx); err != nil {
        return err
    }

    // sleep for a lil bit to see the logs
    time.Sleep(3 * time.Second)

    // kill the process and get the exit status
    if err := task.Kill(ctx, syscall.SIGTERM); err != nil {
        return err
    }

    // wait for the process to fully exit and print out the exit status

    status := <-exitStatusC
    code, _, err := status.Result()
    if err != nil {
        return err
    }
    fmt.Printf("redis-server exited with status: %d\n", code)

    return nil
}

> go build main.go
> sudo ./main

1:C 04 Aug 20:41:37.682 # oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo
1:C 04 Aug 20:41:37.682 # Redis version=4.0.1, bits=64, commit=00000000, modified=0, pid=1, just started
1:C 04 Aug 20:41:37.682 # Warning: no config file specified, using the default config. In order to specify a config file use redis-server /path/to/redis.conf
1:M 04 Aug 20:41:37.682 # You requested maxclients of 10000 requiring at least 10032 max file descriptors.
1:M 04 Aug 20:41:37.682 # Server can't set maximum open files to 10032 because of OS error: Operation not permitted.
1:M 04 Aug 20:41:37.682 # Current maximum open files is 1024. maxclients has been reduced to 992 to compensate for low ulimit. If you need higher maxclients increase 'ulimit -n'.
1:M 04 Aug 20:41:37.683 * Running mode=standalone, port=6379.
1:M 04 Aug 20:41:37.683 # WARNING: The TCP backlog setting of 511 cannot be enforced because /proc/sys/net/core/somaxconn is set to the lower value of 128.
1:M 04 Aug 20:41:37.684 # Server initialized
1:M 04 Aug 20:41:37.684 # WARNING overcommit_memory is set to 0! Background save may fail under low memory condition. To fix this issue add 'vm.overcommit_memory = 1' to /etc/sysctl.conf and then reboot or run the command 'sysctl vm.overcommit_memory=1' for this to take effect.
1:M 04 Aug 20:41:37.684 # WARNING you have Transparent Huge Pages (THP) support enabled in your kernel. This will create latency and memory usage issues with Redis. To fix this issue run the command 'echo never > /sys/kernel/mm/transparent_hugepage/enabled' as root, and add it to your /etc/rc.local in order to retain the setting after a reboot. Redis must be restarted after THP is disabled.
1:M 04 Aug 20:41:37.684 * Ready to accept connections
1:signal-handler (1501879300) Received SIGTERM scheduling shutdown...
1:M 04 Aug 20:41:40.791 # User requested shutdown...
1:M 04 Aug 20:41:40.791 * Saving the final RDB snapshot before exiting.
1:M 04 Aug 20:41:40.794 * DB saved on disk
1:M 04 Aug 20:41:40.794 # Redis is now ready to exit, bye bye...
redis-server exited with status: 0

CRI-O¶

CRI-O 专门实现 Kubernetes CRI，接收 Kubelet 的 Runtime Service 和 Image Service 请求。它使用 containers/image library 拉取镜像，使用 containers/storage library 管理镜像层和容器 rootfs。在 runc、crun 等 OCI Runtime 的执行路径中，conmon 进程调用运行时创建容器，并持续监控容器进程。

根据 Compatibility matrix: CRI-O ⬄ Kubernetes，CRI-O 的次版本发布周期与 Kubernetes 保持一致，例如 Kubernetes 1.36 对应 CRI-O 1.36。两者的补丁版本不保持同步：Kubernetes 按月发布补丁版本，CRI-O 则仅在需要时发布。当某个 Kubernetes 版本停止维护（End of Life）时，对应的 CRI-O 版本也应视为停止维护。

组件架构¶

下图展示了 CRI-O 从 Kubelet 到 Image、Storage、CNI、conmon 和 OCI Runtime 的调用关系。

• CRI Server：默认监听 Unix Socket /var/run/crio/crio.sock，提供 Runtime Service 和 Image Service，接收 Kubelet 的 Pod Sandbox、容器和镜像管理请求。
• containers/image：镜像操作 library，处理镜像仓库访问、认证和镜像验证策略，将远端镜像复制到本地存储。
• containers/storage：容器存储 library，管理镜像层、容器可写层及相关元数据，通过 OverlayFS 等存储驱动准备容器 rootfs。
• CNI：CRI-O 调用 CNI Plugins，为 Pod Sandbox 配置网络接口、IP 地址和路由。
• conmon：独立的容器监控进程，调用配置的 OCI Runtime 创建容器，维护容器的标准输入输出、写入日志，并记录退出时间和退出码。
• OCI Runtime：读取 OCI Bundle，按照运行配置创建容器进程及其隔离环境。CRI-O 1.36.4 在 Linux 上默认使用 crun，也可通过 Runtime Handler 选择 runc。Kata Containers 等 VM 后端使用独立的 VM 运行时路径接入。

图：CRI-O 组件架构。来源：CRI-O Architecture。

镜像与存储¶

CRI-O 根据镜像名称和认证信息，从镜像仓库拉取镜像，并在本地保存镜像内容。创建容器时，再以镜像的文件系统层为基础准备容器可写层和 rootfs。这两个环节分别由以下 library 提供支持：

• 镜像拉取：containers/image 处理镜像仓库访问、认证、签名验证策略和镜像复制。CRI-O 收到拉取请求后，读取请求中的镜像名称和认证信息，完成拉取后返回镜像引用。对应入口是 Server.PullImage。
• 镜像层与容器可写层：containers/storage 管理镜像层、容器存储记录及相关元数据，并通过存储驱动准备 rootfs。每个容器拥有自己的可写层；例如，使用 OverlayFS 时，同一镜像创建的两个容器可以共享只读镜像层，各自在独立的可写层中保存修改。

容器创建与启动¶

CRI-O 根据 Kubelet 的创建请求准备容器的 rootfs 和 OCI 运行配置，再通过 conmon 调用 crun 或 runc 创建容器。收到启动请求后，CRI-O 调用运行时启动容器中的应用进程。

1. 准备 rootfs 和运行配置：CRI-O 根据创建请求中的 Sandbox ID 找到所属 Pod Sandbox，沿用它的 Runtime Handler。随后创建容器存储记录和可写层、挂载 rootfs，并将启动命令、挂载和资源限制等信息保存到 OCI config.json。
2. 创建容器：CRI-O 启动 conmon 进程，将 OCI Bundle、运行时可执行文件和日志文件的路径等信息传给它。conmon 调用 OCI Runtime 创建容器进程及其隔离环境，容器进入 created 状态，等待启动请求。
3. 启动应用进程：Kubelet 发送启动请求后，CRI-O 检查容器处于 created 状态，再通过 OCI Runtime 启动容器。

配置文件¶

CRI-O 默认使用以下配置文件和目录：

• /etc/crio/crio.conf：主配置文件，集中设置 CRI-O 的运行参数。
• /etc/crio/crio.conf.d/：配置片段目录，可将存储、Sandbox 镜像和运行时等配置分别保存在独立的 .conf 文件中。

以下示例介绍 CRI-O 的 API、存储、Sandbox 镜像、运行时、CNI 网络、cgroup，以及镜像仓库与认证配置。完整配置项见 CRI-O v1.36.4 crio.conf(5)。

API 配置

[crio.api] 配置 CRI-O 的 CRI 服务与 Streaming Server。Streaming Server 用于持续传输容器的交互输入、输出和端口转发数据，主要服务于三类操作：

• kubectl exec：在容器中启动命令，并传输输入输出，例如进入容器执行交互式 Shell。
• kubectl attach：连接容器中已经运行的进程，查看输出或发送输入。
• kubectl port-forward：将本地端口的数据转发到 Pod 中的端口。

处理这三类操作时，CRI 服务接收请求并返回会话连接地址，Streaming Server 负责随后持续传输的数据。使用 kubectl 时，数据经过 API Server 和 Kubelet 代理。具体过程见 Kubernetes CRI 流式通信说明。

下面使用 CRI-O v1.36.4 的默认连接地址，字段定义见 CRI-O API 配置：

• listen：CRI 服务监听的 Unix Socket 路径。Kubelet 和 crictl 使用 unix:///var/run/crio/crio.sock 连接该服务。
• stream_address：Streaming Server 的监听 IP 地址。
• stream_port：Streaming Server 的监听端口，"0" 表示自动选择空闲端口。
• stream_enable_tls：是否为 Streaming Server 启用 TLS。启用时还需配置 stream_tls_cert 和 stream_tls_key，分别指定证书与私钥文件。

[crio.api]
listen = "/var/run/crio/crio.sock"
stream_address = "127.0.0.1"
stream_port = "0"
stream_enable_tls = false

存储配置

下面的配置指定本地存储目录，并使用 OverlayFS 准备镜像层和容器文件系统，字段定义见 CRI-O 存储配置：

• root：保存镜像层、容器可写层和元数据等持久数据。
• runroot：保存挂载状态等运行期间的临时数据。
• storage_driver：选择存储驱动，overlay 表示使用 OverlayFS。

[crio]
root = "/var/lib/containers/storage"
runroot = "/var/run/containers/storage"
storage_driver = "overlay"

Sandbox 镜像配置

pause_image 指定 Pod Sandbox 使用的 pause 镜像。示例使用 registry.k8s.io/pause:3.10.1，部署时可按节点要求调整镜像地址和版本，字段定义见 CRI-O 镜像配置：

[crio.image]
pause_image = "registry.k8s.io/pause:3.10.1"

运行时配置

下面的配置注册 crun 和 runc 两个 Runtime Handler，节点需已安装对应的运行时：

• default_runtime：选择未指定 Runtime Handler 时使用的默认后端。
• runtime_path：指定运行时可执行文件的路径。
• runtime_type：指定运行时类型，这两个 Handler 均使用 oci。

Kubernetes RuntimeClass 的 handler 字段与 [crio.runtime.runtimes.<handler>] 中的名称对应。默认运行时和 Handler 字段分别见 CRI-O 运行时配置和 Runtime Handler 配置。

[crio.runtime]
default_runtime = "crun"

[crio.runtime.runtimes.crun]
runtime_path = "/usr/bin/crun"
runtime_type = "oci"

[crio.runtime.runtimes.runc]
runtime_path = "/usr/bin/runc"
runtime_type = "oci"

CNI 网络配置

CRI-O 从 [crio.network] 指定的目录读取网络配置并寻找 CNI 插件，字段定义见 CRI-O 网络配置：

• network_dir：CNI 配置文件所在的目录。
• plugin_dirs：CNI 插件可执行文件所在的目录列表。

下面使用默认目录。节点需要已安装 CNI 插件，并在配置目录中提供对应的网络配置：

[crio.network]
network_dir = "/etc/cni/net.d/"
plugin_dirs = ["/opt/cni/bin/"]

cgroup 配置

[crio.runtime] 中的 cgroup_manager 指定 cgroup 管理方式，默认是 systemd，字段定义见 CRI-O 运行时配置。Kubelet 与 CRI-O 使用的 cgroup driver 应保持一致，配置要求见 Kubernetes cgroup driver 配置。下面显式使用 systemd：

[crio.runtime]
cgroup_manager = "systemd"

镜像仓库与认证配置

CRI-O 通过 /etc/containers/registries.conf 和 /etc/containers/registries.conf.d/*.conf 配置镜像仓库与 Mirror，语法和加载方式分别见镜像仓库配置和镜像仓库配置片段。

• registry.prefix：匹配待拉取镜像的名称前缀，例如 docker.io。
• registry.location：指定该前缀对应的实际仓库位置。
• registry.mirror.location：指定优先尝试的 Mirror 地址。
• registry.mirror.pull-from-mirror：限制使用 Mirror 的镜像引用类型，digest-only 表示仅在按 digest 拉取时使用。

下面为 docker.io 配置 Mirror，使用时将文件放入 /etc/containers/registries.conf.d/，并把 mirror.example.com 替换为保留相同仓库路径的实际镜像源。示例仅对按 digest 拉取的镜像使用 Mirror；按 tag 拉取时仍访问 docker.io：

# 放入 /etc/containers/registries.conf.d/，并替换为实际 Mirror 地址。
[[registry]]
prefix = "docker.io"
location = "docker.io"

[[registry.mirror]]
location = "mirror.example.com"
pull-from-mirror = "digest-only"

私有仓库的节点级认证由 [crio.image] 中的 global_auth_file 配置，它指向保存镜像拉取凭据的文件，字段定义见 CRI-O 镜像配置。下面使用 /etc/crio/auth.json 作为自定义路径；启用前需要准备认证文件，并限制其访问权限。这个 CRI-O 配置片段应放入 /etc/crio/crio.conf.d/：

# 使用前准备此路径的认证文件，并限制其访问权限。
[crio.image]
global_auth_file = "/etc/crio/auth.json"

# 存储配置
[crio]
root = "/var/lib/containers/storage"
runroot = "/var/run/containers/storage"
storage_driver = "overlay"

# API 配置
[crio.api]
listen = "/var/run/crio/crio.sock"
stream_address = "127.0.0.1"
stream_port = "0"
stream_enable_tls = false

# Sandbox 镜像与认证配置
[crio.image]
pause_image = "registry.k8s.io/pause:3.10.1"

# 需要节点级镜像拉取凭据时，先准备认证文件，再启用此项
# global_auth_file = "/etc/crio/auth.json"

# 默认运行时与 cgroup 配置
[crio.runtime]
default_runtime = "crun"
cgroup_manager = "systemd"

# crun Runtime Handler
[crio.runtime.runtimes.crun]
runtime_path = "/usr/bin/crun"
runtime_type = "oci"

# runc Runtime Handler
[crio.runtime.runtimes.runc]
runtime_path = "/usr/bin/runc"
runtime_type = "oci"

# CNI 网络配置
[crio.network]
network_dir = "/etc/cni/net.d/"
plugin_dirs = ["/opt/cni/bin/"]

# 放入 /etc/containers/registries.conf.d/，并替换为实际 Mirror 地址。
[[registry]]
prefix = "docker.io"
location = "docker.io"

[[registry.mirror]]
location = "mirror.example.com"
pull-from-mirror = "digest-only"

命令行工具¶

服务检查

在由 systemd 管理 CRI-O 的节点上，可以检查服务状态、版本和监听地址：

# 查看 CRI-O 服务状态
systemctl status crio --no-pager

# 查看 CRI-O 版本
crio --version

# 查看 CRI-O 的 Unix Socket 监听状态
ss --listening --unix | grep '/var/run/crio/crio.sock'

crictl

crictl 通过 CRI 查询运行时信息、Pod Sandbox、容器和镜像。下面的命令连接 CRI-O 默认的 Unix Socket：

# 查看运行时状态和信息
crictl --runtime-endpoint unix:///var/run/crio/crio.sock info

# 列出 Pod Sandbox
crictl --runtime-endpoint unix:///var/run/crio/crio.sock pods

# 列出所有容器，包括已停止的容器
crictl --runtime-endpoint unix:///var/run/crio/crio.sock ps --all

# 通过 Image Service 列出本地镜像
crictl --image-endpoint unix:///var/run/crio/crio.sock images

状态查询

CRI-O 还通过同一个 Unix Socket 提供 Status API。/info 返回存储驱动、存储目录和 cgroup 驱动等信息，/config 返回当前生效的 TOML 配置：

# 查询 CRI-O 的存储和 cgroup 信息
curl --unix-socket /var/run/crio/crio.sock \
  http://localhost/info

# 查询 CRI-O 当前生效的配置
curl --unix-socket /var/run/crio/crio.sock \
  http://localhost/config

安装、配置与运行步骤见 CRI-O 示例。

低级容器运行时¶

低级容器运行时接收上层准备好的文件系统和运行配置，负责创建执行环境、设置隔离与资源限制，并启动应用程序。

下表列出了常见低级容器运行时的隔离方式和典型工作负载：

OCI 规范¶

OCI（Open Container Initiative）制定容器相关的开放标准。容器运行和镜像格式分别由以下两项规范定义：

• OCI Runtime Specification：定义容器的运行配置、执行环境和生命周期，包括进程参数、文件系统挂载、资源限制、容器状态，以及 create、start、kill、delete 等操作的行为。
• OCI Image Specification：定义容器镜像的格式，包括 Image Manifest、Image Index、Image Config 和文件系统 Layer，使构建工具和容器运行时能够按统一格式生成和读取镜像。

OCI Bundle¶

OCI Bundle 是 runc、crun 等低级容器运行时创建容器时读取的一组本地文件。对于普通 Linux 容器，Bundle 包含运行配置 config.json 和容器的根文件系统（rootfs）：config.json 描述启动哪个进程、挂载哪些目录以及使用什么资源限制；rootfs 提供容器内的应用程序、依赖库和配置文件。

config.json 中的 root.path 指定 rootfs 的位置。下面的示例将它设置为 rootfs，指向 Bundle 目录下的 rootfs/：

bundle/
├── config.json
└── rootfs/
    ├── bin/
    ├── etc/
    ├── lib/
    └── usr/

容器镜像保存用于分发的文件系统层和默认启动信息，创建容器前需要将这些内容准备成 OCI Bundle。以 containerd 为例，它协调镜像 Layer 的解包，并通过 Snapshotter 准备容器使用的 rootfs，具体过程见 containerd Content Flow。上层运行时还会结合镜像的默认配置和用户指定的运行参数，生成 Bundle 中的 config.json，供低级容器运行时读取并创建容器。

镜像中的 Image Config 是一份 JSON 元数据，保存默认启动命令、环境变量和工作目录等信息。创建容器时，上层运行时以这些默认值为基础，结合用户指定的运行参数，按 OCI 运行配置转换规则生成 Bundle 的 config.json。这份配置描述本次容器实际使用的启动命令和运行环境，还包含挂载、资源限制和隔离设置等。

config.json¶

config.json 描述将要启动的进程及其运行环境。完整字段见 OCI Runtime Configuration，常用字段包括：

• process：进程参数、环境变量、工作目录、用户、Capability 和资源限制。
• root：rootfs 路径以及是否只读。
• mounts：容器内的 Mount Point、文件系统类型和 Mount Option。
• linux.namespaces：需要创建或加入的 Linux Namespace。
• linux.resources：CPU、Memory、PIDs、Block I/O 等 cgroup 配置。
• linux.seccomp：允许、拒绝或审计的 System Call。
• hooks：在容器生命周期指定阶段运行的外部程序。
• annotations：传递给运行时的扩展元数据。

下面的配置用于通过 runc 启动 BusyBox。它为容器创建独立的 PID、Mount、Network、IPC、UTS 和 cgroup Namespace，并挂载 /proc、/dev、/sys 和 /sys/fs/cgroup 等文件系统，提供常见的 Linux 运行环境。

{
  "ociVersion": "1.3.0",
  "process": {
    "terminal": false,
    "user": {
      "uid": 0,
      "gid": 0
    },
    "args": ["sh", "-c", "printf \"runtime=runc pid=%s message=%s\\n\" \"$$\" \"hello-from-oci-bundle\""],
    "env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"],
    "cwd": "/"
  },
  "root": {
    "path": "rootfs",
    "readonly": false
  },
  "hostname": "oci-demo",
  "mounts": [
    {
      "destination": "/proc",
      "type": "proc",
      "source": "proc"
    },
    {
      "destination": "/dev",
      "type": "tmpfs",
      "source": "tmpfs",
      "options": ["nosuid", "strictatime", "mode=755", "size=65536k"]
    },
    {
      "destination": "/dev/pts",
      "type": "devpts",
      "source": "devpts",
      "options": ["nosuid", "noexec", "newinstance", "ptmxmode=0666", "mode=0620", "gid=5"]
    },
    {
      "destination": "/dev/shm",
      "type": "tmpfs",
      "source": "shm",
      "options": ["nosuid", "noexec", "nodev", "mode=1777", "size=65536k"]
    },
    {
      "destination": "/dev/mqueue",
      "type": "mqueue",
      "source": "mqueue",
      "options": ["nosuid", "noexec", "nodev"]
    },
    {
      "destination": "/sys",
      "type": "sysfs",
      "source": "sysfs",
      "options": ["nosuid", "noexec", "nodev", "ro"]
    },
    {
      "destination": "/sys/fs/cgroup",
      "type": "cgroup",
      "source": "cgroup",
      "options": ["nosuid", "noexec", "nodev", "relatime", "ro"]
    }
  ],
  "linux": {
    "resources": {
      "devices": [
        {
          "allow": false,
          "access": "rwm"
        }
      ]
    },
    "namespaces": [
      { "type": "pid" },
      { "type": "network" },
      { "type": "ipc" },
      { "type": "uts" },
      { "type": "mount" },
      { "type": "cgroup" }
    ],
    "maskedPaths": [
      "/proc/acpi",
      "/proc/asound",
      "/proc/kcore",
      "/proc/keys",
      "/proc/latency_stats",
      "/proc/timer_list",
      "/proc/timer_stats",
      "/proc/sched_debug",
      "/sys/firmware",
      "/proc/scsi"
    ],
    "readonlyPaths": [
      "/proc/bus",
      "/proc/fs",
      "/proc/irq",
      "/proc/sys",
      "/proc/sysrq-trigger"
    ]
  }
}

rootfs¶

rootfs 是容器进程看到的根文件系统，通常包含应用程序、依赖库和配置文件。OCI 的 root.path 指定它在节点上的位置，可以使用相对于 Bundle 的路径或绝对路径。例如设置为 rootfs 时，运行时使用 Bundle 目录下的 rootfs/ 作为容器的根文件系统；目录名也可以按需指定。

容器运行时根据镜像准备 rootfs，再结合容器的可写层和额外挂载，组成容器进程看到的目录树。

• 从镜像层到 rootfs：镜像 Layer 记录文件的新增、修改和删除，需要按顺序应用才能形成完整的文件系统。containerd 协调镜像层的解包，并通过 Snapshotter 保存每层处理后的文件系统快照。创建可写容器时，再基于最终的镜像快照准备该容器独立的可写快照，并取得挂载信息，供后续挂载为容器的 rootfs。具体过程见 containerd Content Flow。

• 容器中的文件读写：以 OverlayFS 为例，lowerdir 提供只读镜像内容，upperdir 保存当前容器的修改，容器看到的是合并后的目录树。新增文件写入可写层；修改仅存在于只读层的文件时，OverlayFS 会先将文件复制到可写层，再修改副本，这个过程称为 copy-up。例如修改镜像中的 /app/config.yaml 时，改变的是当前容器的副本，原镜像文件保持不变。这是 OverlayFS 的实现方式，其他 Snapshotter 可以采用不同机制，例如 native 通过复制父快照目录准备容器的文件系统。

  

• rootfs 与额外挂载：容器看到的目录树还可以包含额外挂载的文件系统。OCI 的 mounts 指定这些挂载，例如为 /proc、/dev 准备的文件系统，或挂载到 /data 的数据卷。如果 /data 挂载了独立的数据卷，写入 /data/result.txt 的内容会保存在该卷中，而不是 rootfs 的可写层。

Linux 容器实现原理¶

runc、crun 创建的 Linux 容器与宿主机共享内核。运行时根据 OCI 配置，为容器进程设置 Namespace、cgroup 和安全策略，分别控制它能看到哪些系统资源、能够使用多少资源，以及允许执行哪些操作。

Namespace¶

Namespace 将系统资源划分到不同的命名空间中，使一组进程拥有自己的资源视图。Linux 按资源类型划分 Namespace，不同类型的 Namespace 分别隔离对应的系统资源。

下表列出了各类 Namespace 及其作用，容器使用哪些类型取决于运行配置：

unshare 用于创建新的 Namespace，并在其中运行程序。

# Mount：创建独立的挂载视图，并查看挂载列表
sudo unshare --mount findmnt

# PID：创建独立的进程编号空间，并挂载对应的 /proc
sudo unshare --pid --fork --mount-proc ps -e -o pid,ppid,comm

# Network：创建独立的网络空间，并查看网络接口
sudo unshare --net ip -brief address

# IPC：创建独立的 IPC 空间，并查看 System V IPC 对象
sudo unshare --ipc ipcs

# UTS：在独立的 UTS Namespace 中设置并查看主机名
sudo unshare --uts sh -c 'hostname ns-demo; hostname'

# User：将当前用户映射为新 User Namespace 内的 root
unshare --user --map-root-user id

# cgroup：创建独立的 cgroup 路径视图
sudo unshare --cgroup cat /proc/self/cgroup

# Time：为启动时间时钟增加一小时偏移，并查看运行时长
sudo unshare --time --fork --boottime 3600 uptime -p

lsns 列出当前可见的 Namespace，/proc/<pid>/ns/ 则记录指定进程所属的 Namespace。

# 列出当前可见的 Namespace
$ sudo lsns
        NS TYPE   NPROCS     PID USER            COMMAND
4026531834 time     1627       1 root            /sbin/init
4026531835 cgroup   1510       1 root            /sbin/init
4026531836 pid      1510       1 root            /sbin/init
4026531837 user     1627       1 root            /sbin/init
4026531838 uts      1504       1 root            /sbin/init
...

# 查看当前 Shell 所属的 Namespace
$ lsns --task "$$"
        NS TYPE   NPROCS PID USER COMMAND
4026531834 time     1625   1 root /sbin/init
4026531835 cgroup   1508   1 root /sbin/init
4026531836 pid      1508   1 root /sbin/init
4026531837 user     1625   1 root /sbin/init
4026531838 uts      1502   1 root /sbin/init
4026531839 ipc      1508   1 root /sbin/init
4026531840 net      1506   1 root /sbin/init
4026531841 mnt      1495   1 root /sbin/init

# 只列出 Network Namespace，显示标识、代表进程 PID 和命令
$ sudo lsns --type net --output NS,PID,COMMAND
        NS     PID COMMAND
4026531840       1 /sbin/init
4026535754    6017 ├─/usr/libexec/accounts-daemon
4026537309  363539 └─/usr/libexec/rtkit-daemon
...

# 查看当前 Shell 的 Network Namespace 标识
# 输出形如 net:[4026531840]，其中的数字对应 lsns 的 NS 列。
# 同一台主机上，同类型 Namespace 的标识相同，表示进程共享该 Namespace。
$ readlink /proc/$$/ns/net
net:[4026531840]

nsenter 用于在已有的 Namespace 中运行程序。--target 指定目标进程在宿主机上的 PID，--net、--mount、--uts 等参数选择要加入的 Namespace 类型。多个类型参数可以组合使用：

# Network：加入目标进程的 Network Namespace，查看网络接口
sudo nsenter --target "$PID" --net ip -brief address

# Mount：加入目标进程的 Mount Namespace，查看挂载列表
sudo nsenter --target "$PID" --mount findmnt

# UTS：加入目标进程的 UTS Namespace，查看主机名
sudo nsenter --target "$PID" --uts hostname

# IPC：加入目标进程的 IPC Namespace，查看 System V IPC 对象
sudo nsenter --target "$PID" --ipc ipcs

# PID：同时加入 PID 和 Mount Namespace，通过目标环境的 /proc 查看进程
# --root 切换到目标进程的根目录，使用其中的 ps 和 /proc
sudo nsenter --target "$PID" --pid --mount --root ps -e -o pid,ppid,comm

# 同时加入四类 Namespace，使用目标根目录，从 / 启动交互式 Bash
sudo nsenter --target "$PID" --uts --pid --net --mount --root --wdns=/ bash

cgroup¶

cgroup（Control Group）将进程分组，由不同的 Controller 统计和控制 CPU、内存、任务数量和 I/O 等资源。内核通过虚拟文件系统提供管理接口：每个 cgroup 对应一个目录，目录中的文件用于查看进程、读取统计信息和设置资源限制。

cgroup v1 与 v2

cgroup v1 支持多棵层级树，CPU、内存等 Controller 可以分别挂载，也可以合并挂载。分别挂载时，各层级独立维护进程分组和资源设置，同一个进程可以在不同层级中属于不同的组。合并挂载时，多个 Controller 共用同一套分组结构和 cgroup.procs 进程列表。

# 查看 cgroup v1 的挂载点及其 Controller
findmnt --types cgroup --output TARGET,OPTIONS

# 在四棵层级树中分别创建 demo 组
sudo mkdir /sys/fs/cgroup/{cpu,memory,pids,blkio}/demo

# 将 1234 替换为目标进程的 PID
PID=1234

# 将进程加入 CPU 组
echo "$PID" | sudo tee /sys/fs/cgroup/cpu/demo/cgroup.procs

# 将进程加入内存组
echo "$PID" | sudo tee /sys/fs/cgroup/memory/demo/cgroup.procs

# 将进程加入任务数量限制组
echo "$PID" | sudo tee /sys/fs/cgroup/pids/demo/cgroup.procs

# 将进程加入块设备 I/O 组
echo "$PID" | sudo tee /sys/fs/cgroup/blkio/demo/cgroup.procs

# 指定示例进程的 PID
PID=1234

# 将进程加入 CPU 组，应用该组的 CPU 限制
echo "$PID" | sudo tee /sys/fs/cgroup/cpu/demo/cgroup.procs

# 将同一个进程加入内存组，应用该组的内存限制
echo "$PID" | sudo tee /sys/fs/cgroup/memory/demo/cgroup.procs

# 创建合并挂载的目录
sudo mkdir -p /sys/fs/cgroup/combined

# 将 CPU 和内存 Controller 挂载到同一棵层级树
sudo mount -t cgroup -o cpu,memory none /sys/fs/cgroup/combined

# 创建两个 Controller 共用的进程组
sudo mkdir /sys/fs/cgroup/combined/demo

# 指定目标进程的 PID
PID=1234

# 一次写入，将进程加入 CPU 和内存 Controller 共用的组
echo "$PID" | sudo tee /sys/fs/cgroup/combined/demo/cgroup.procs

app/
├── memory.limit_in_bytes       # 整个应用的内存上限
├── frontend/
│   ├── cpu.shares              # frontend 的 CPU 权重
│   └── memory.limit_in_bytes   # 同时形成内存子组
└── backend/
    ├── cpu.shares              # backend 的 CPU 权重
    └── memory.limit_in_bytes   # 同时形成内存子组

app/
├── memory.max                  # 1073741824，即 1 GiB
├── cgroup.subtree_control      # cpu
├── frontend/
│   └── cpu.weight              # 200
└── backend/
    └── cpu.weight              # 100

memory/
└── app/
    └── cgroup.procs            # 包含 PID 1234 和 5678

blkio/
├── user-a/
│   └── cgroup.procs            # 包含 PID 1234
└── user-b/
    └── cgroup.procs            # 包含 PID 5678

# v1：取消本组的 CPU 时间配额
echo -1 | sudo tee /sys/fs/cgroup/cpu/demo/cpu.cfs_quota_us

# v1：取消本组的任务数量上限
echo max | sudo tee /sys/fs/cgroup/pids/demo/pids.max

# v2：取消本组的 CPU 时间配额，周期设为 100000 微秒
echo 'max 100000' | sudo tee /sys/fs/cgroup/demo/cpu.max

# v2：取消本组的任务数量上限
echo max | sudo tee /sys/fs/cgroup/demo/pids.max

cgroup v2 使用统一层级，不同 Controller 基于同一套进程分组进行资源统计和控制。各级 cgroup 通过 cgroup.subtree_control 选择向子组启用哪些 Controller，使不同资源可以按需在不同层级进行细分管理。

# 查看 cgroup v2 的挂载位置
findmnt --types cgroup2 --output TARGET,OPTIONS

# 查看根组可用的 Controller
cat /sys/fs/cgroup/cgroup.controllers

# 为根组的直接子组启用 CPU、内存、任务数量和 I/O 控制
echo '+cpu +memory +pids +io' | sudo tee /sys/fs/cgroup/cgroup.subtree_control

# 创建统一管理各类资源的 demo 组
sudo mkdir /sys/fs/cgroup/demo

# 将 1234 替换为目标进程的 PID
PID=1234

# 将进程加入 demo 组，同时应用该组的各项资源配置
echo "$PID" | sudo tee /sys/fs/cgroup/demo/cgroup.procs

下图以 CPU 和内存为例，对比 v1 的独立层级与 v2 的统一层级，并展示 app 父组、frontend 和 background 子组的进程归属与资源配置：

cgroup v1 目录结构

下面以 demo 为例列出主要文件，将 cpu 和 cpuacct 合并挂载，其余控制器分别挂载。

/sys/fs/cgroup/
├── cpu,cpuacct/                       # CPU 调度与用量统计
│   ├── cgroup.procs
│   ├── tasks
│   ├── ...
│   └── demo/
│       ├── cgroup.procs               # 当前组的进程 PID
│       ├── tasks                      # 当前组的线程 TID
│       ├── cpu.cfs_period_us           # CPU 配额周期
│       ├── cpu.cfs_quota_us            # 每个周期可使用的 CPU 时间
│       ├── cpu.shares                  # CPU 相对权重
│       ├── cpu.stat                    # CPU 限流统计
│       ├── cpuacct.usage               # 累计 CPU 使用时间
│       ├── cpuacct.usage_percpu        # 各 CPU 上的使用时间
│       └── cpuacct.stat                # 用户态、内核态 CPU 时间
│
├── memory/                            # 内存控制
│   ├── ...
│   └── demo/
│       ├── cgroup.procs
│       ├── tasks
│       ├── memory.limit_in_bytes      # 内存上限
│       ├── memory.usage_in_bytes       # 当前内存用量
│       ├── memory.max_usage_in_bytes   # 内存用量峰值
│       ├── memory.failcnt              # 触及内存限制的计数
│       └── memory.stat                 # 内存分类统计
│
├── cpuset/                            # CPU 与 NUMA 节点分配
│   ├── ...
│   └── demo/
│       ├── cgroup.procs
│       ├── tasks
│       ├── cpuset.cpus                 # 配置的 CPU 集合
│       ├── cpuset.mems                 # 配置的 NUMA 内存节点集合
│       ├── cpuset.effective_cpus       # 实际生效的 CPU 集合
│       └── cpuset.effective_mems       # 实际生效的 NUMA 节点集合
│
├── blkio/                             # 块设备 I/O 控制
│   ├── ...
│   └── demo/
│       ├── cgroup.procs
│       ├── tasks
│       ├── blkio.throttle.read_bps_device   # 各设备读取带宽上限
│       ├── blkio.throttle.write_bps_device  # 各设备写入带宽上限
│       ├── blkio.throttle.read_iops_device  # 各设备读取 IOPS 上限
│       └── blkio.throttle.write_iops_device # 各设备写入 IOPS 上限
│
├── pids/                              # 任务数量控制，线程也计数
│   ├── ...
│   └── demo/
│       ├── cgroup.procs
│       ├── tasks
│       ├── pids.current               # 当前任务数量
│       ├── pids.max                   # 任务数量上限
│       └── pids.events                # 达到限制等事件计数
│
├── devices/                           # 设备访问权限
│   ├── ...
│   └── demo/
│       ├── cgroup.procs
│       ├── tasks
│       ├── devices.allow              # 添加允许访问的设备规则
│       ├── devices.deny               # 撤销设备访问权限
│       └── devices.list               # 当前允许规则
│
└── freezer/                           # 冻结与恢复任务
    ├── ...
    └── demo/
        ├── cgroup.procs
        ├── tasks
        └── freezer.state              # 冻结状态与控制

cgroup v2 目录结构

父级通过 cgroup.subtree_control 为子级启用控制器后，demo/ 中会出现对应的资源文件。下面假设已启用 CPU、内存、cpuset、I/O 和 pids 控制器。

/sys/fs/cgroup/
├── cgroup.controllers                 # 根层级可用的控制器
├── cgroup.subtree_control              # 为直接子级启用的控制器
├── cgroup.procs                        # 根 cgroup 的进程 PID
├── ...
│
└── demo/
    ├── cgroup.type                    # 当前 cgroup 类型
    ├── cgroup.procs                   # 当前组的进程 PID
    ├── cgroup.threads                 # 当前组的线程 TID
    ├── cgroup.controllers             # 可继续向子级启用的控制器
    ├── cgroup.subtree_control         # 为直接子级启用的控制器
    ├── cgroup.events                  # 子树是否有进程、是否已冻结
    ├── cgroup.stat                    # 子孙 cgroup 等统计
    ├── cgroup.freeze                  # 冻结或恢复整个子树
    ├── cgroup.kill                    # 终止整个子树中的进程
    ├── cgroup.max.depth               # 子孙 cgroup 的最大深度
    ├── cgroup.max.descendants         # 子孙 cgroup 的数量上限
    │
    ├── cpu.max                        # CPU 配额与周期
    ├── cpu.weight                     # CPU 相对权重
    ├── cpu.stat                       # CPU 用量与限流统计
    ├── cpu.pressure                   # CPU 压力统计
    │
    ├── cpuset.cpus                    # 配置的 CPU 集合
    ├── cpuset.cpus.effective           # 实际生效的 CPU 集合
    ├── cpuset.mems                    # 配置的 NUMA 内存节点集合
    ├── cpuset.mems.effective           # 实际生效的 NUMA 节点集合
    │
    ├── memory.current                 # 当前内存用量，包含后代组
    ├── memory.min                     # 硬性内存回收保护
    ├── memory.low                     # 尽力而为的内存回收保护
    ├── memory.high                    # 触发节流与回收的阈值
    ├── memory.max                     # 内存硬上限
    ├── memory.swap.current            # 当前 Swap 用量
    ├── memory.swap.max                # Swap 用量上限
    ├── memory.stat                    # 内存分类统计
    ├── memory.events                  # 内存限制、OOM 等事件计数
    ├── memory.pressure                # 内存压力统计
    │
    ├── io.max                         # 各设备的带宽与 IOPS 上限
    ├── io.weight                      # I/O 相对权重
    ├── io.stat                        # I/O 用量统计
    ├── io.pressure                    # I/O 压力统计
    │
    ├── pids.current                   # 当前任务数量，包含后代组
    ├── pids.max                       # 任务数量上限，线程也计数
    └── pids.events                    # 达到限制等事件计数

Capability、seccomp 与 LSM¶

容器进程的操作受到多种权限检查约束：Capability 控制进程可执行的特权操作，seccomp 过滤系统调用，LSM 根据安全策略检查资源访问。运行时负责配置这些限制，内核在进程运行时执行检查。

Capability：细分特权

Linux Capabilities 将特权拆成独立能力。例如，修改网络接口需要 CAP_NET_ADMIN，运行时可以只授予应用这项能力。即使进程的 UID 为 0，缺少相应能力时，操作仍会被拒绝。

常见的 Capability 及其允许的典型操作如下：

docker run --rm --network=none --cap-drop=ALL \
  alpine:3.22 ip link set lo mtu 1400

ip: ioctl 0x8922 failed: Operation not permitted

docker run --rm --network=none --cap-drop=ALL --cap-add=NET_ADMIN \
  alpine:3.22 sh -c '
    grep "^CapEff:" /proc/self/status
    ip link set lo mtu 1400 && ip link show lo
  '

CapEff: 0000000000001000
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 1400 qdisc noqueue state UNKNOWN qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00

seccomp：限制系统调用

seccomp Filter 使用 BPF 程序检查系统调用编号、架构和参数值，决定放行、返回错误或终止进程等。例如，可以让创建目录的 mkdir、mkdirat 系统调用直接返回 EPERM。

seccomp 的 BPF 过滤器可以检查系统调用参数的数值，但不能读取指针指向的内存内容。例如，它能检查 openat 的打开标志，却不能读取文件路径字符串。按路径控制文件访问，可以使用 AppArmor 等机制。

{
  "defaultAction": "SCMP_ACT_ALLOW",
  "syscalls": [
    {
      "names": ["mkdir", "mkdirat"],
      "action": "SCMP_ACT_ERRNO",
      "errnoRet": 1
    }
  ]
}

docker run --rm --network=none alpine:3.22 \
  sh -c 'mkdir /tmp/demo && echo "Created /tmp/demo"'

Created /tmp/demo

docker run --rm --network=none \
  --security-opt seccomp=./deny-mkdir.json \
  alpine:3.22 mkdir /tmp/demo

mkdir: can't create directory '/tmp/demo': Operation not permitted

LSM：按安全策略约束资源访问

LSM（Linux Security Modules） 是内核执行安全策略检查的框架。SELinux 和 AppArmor 是基于 LSM 框架实现的安全模块。 SELinux 根据进程和对象的安全标签执行访问控制；AppArmor 根据进程的 Profile，按文件路径等条件限制访问。例如，可以配置 AppArmor，允许应用读取配置文件、写入临时目录，同时禁止修改配置文件。

#include <tunables/global>

profile course-container-security-demo flags=(attach_disconnected,mediate_deleted) {
  #include <abstractions/base>

  file,
  signal,

  deny /etc/** w,
}

sudo apparmor_parser -a ./demo-config-readonly

docker run --rm --network=none \
  --security-opt apparmor=course-container-security-demo \
  alpine:3.22 cat /proc/self/attr/current

course-container-security-demo (enforce)

docker run --rm --network=none \
  --security-opt apparmor=course-container-security-demo \
  alpine:3.22 cat /etc/alpine-release

docker run --rm --network=none \
  --security-opt apparmor=course-container-security-demo \
  alpine:3.22 sh -c 'touch /tmp/demo && echo "Created /tmp/demo"'

docker run --rm --network=none \
  --security-opt apparmor=course-container-security-demo \
  alpine:3.22 sh -c 'echo changed > /etc/alpine-release'

3.22.6
Created /tmp/demo
sh: can't create /etc/alpine-release: Permission denied

sudo apparmor_parser -R ./demo-config-readonly

runc¶

运行机制¶

runc 是 OCI Runtime Specification 的常用实现，也是 Docker Engine 和 containerd 默认 Linux 运行路径中的执行后端。它读取 config.json，通过 libcontainer 创建容器的隔离环境和初始进程，并管理容器的生命周期。

containerd 使用 io.containerd.runc.v2 时，长期驻留的是 containerd-shim-runc-v2 和容器进程。runc 在创建、启动或删除等操作期间执行，完成对应操作后退出。Shim 独立于 containerd 运行，负责维护容器的输入输出连接并记录退出状态。containerd 正常重启期间，Shim 和容器进程可以继续运行。

使用方式¶

runc 官方把它定位为供高级容器工具调用的低级 CLI。直接运行时，需要先准备 OCI Bundle。下面的命令使用 Docker 解出 BusyBox rootfs，再由 runc spec 生成基础配置。

# 设置 OCI Bundle 目录
BUNDLE=/tmp/runc-demo

# 创建临时 Docker 容器，用于导出 BusyBox 文件系统
CONTAINER_ID=$(docker create busybox:1.37)

# 创建存放容器根文件系统的目录
sudo mkdir -p "${BUNDLE}/rootfs"

# 导出临时容器的文件系统，并解包到 rootfs 目录
docker export "${CONTAINER_ID}" \
  | sudo tar -C "${BUNDLE}/rootfs" -xf -

# 删除用于导出文件系统的临时 Docker 容器
docker rm "${CONTAINER_ID}"

# 进入 OCI Bundle 目录
cd "${BUNDLE}"

# 在当前目录生成默认的 OCI 运行配置 config.json
sudo runc spec

# 根据 config.json 和 rootfs 创建并启动容器
sudo runc run runc-demo

crun¶

运行机制¶

crun 是使用 C 编写的低级容器运行时，实现 OCI Runtime Specification。它读取 OCI Bundle，创建容器的隔离环境和初始进程，并管理容器的生命周期。crun 比 runc 运行更快，内存占用也更低。

crun 可以作为 runc 的替代实现，接入 Docker、containerd、CRI-O 和 Podman。

使用方式¶

Docker Engine 默认使用 runc 作为低级容器运行时。可以在 /etc/docker/daemon.json 中注册 crun，再通过 docker run --runtime=crun 为容器选择它，配置方式见 Docker Alternative container runtimes。

下面假定 crun 已安装在 /usr/bin/crun。将示例中的 runtimes.crun 配置合并到 /etc/docker/daemon.json，保留文件中的其他配置：

{
  "runtimes": {
    "crun": {
      "path": "/usr/bin/crun"
    }
  }
}

在由 systemd 管理 Docker 的 Linux 主机上，重新加载配置后使用 crun 运行容器：

# 重新加载 Docker 配置，注册 crun 运行时
sudo systemctl reload docker

# 使用 crun 启动 BusyBox 容器，并输出内核信息
docker run --rm --runtime=crun busybox:1.37 uname -a

如果希望新建容器默认使用 crun，可以在同一配置文件的顶层增加 "default-runtime": "crun"。重新加载配置后，新建容器无需再指定 --runtime。详细配置见 Docker Configure the default container runtime。

crun 也可以直接运行前面准备好的 OCI Bundle：

# 进入已经包含 config.json 和 rootfs 的 OCI Bundle 目录
cd /tmp/runc-demo

# 使用 crun 创建并启动容器
sudo crun run crun-demo

Kata Containers¶

Kata Containers 是一个开源容器运行时，让每个容器或 Kubernetes Pod 运行在各自独立的轻量虚拟机（VM）中。它保留标准 Linux 容器的使用方式，通过硬件虚拟化提供更强的工作负载隔离。

运行架构¶

在 Kubernetes 中，一个 Pod Sandbox 对应一台 VM，同一 Pod 中的容器共享这台 VM 的 Guest Kernel。容器仍在 Guest 内使用 Namespace 和 cgroup 隔离与管理资源，应用的系统调用由 Guest Kernel 处理。

Kata Containers 可在多种处理器架构（如 x86_64、aarch64、ppc64le 和 s390x）上运行，并支持多种 Hypervisor（如 QEMU、Cloud Hypervisor、Firecracker、Dragonball 和 StratoVirt）。

创建 Kata Pod 时，containerd 或 CRI-O 将请求交给 Kata Shim，由 Shim 启动 Hypervisor 并引导轻量 VM。VM 内的 kata-agent 负责启动和管理容器。容器中的应用执行文件读写、网络通信等操作时，相关系统调用由 VM 内的 Linux 内核（Guest Kernel）处理。容器文件（包括镜像的 rootfs）通过 virtio-fs 共享到 Guest，通常由 Host 上的 virtiofsd 提供服务，也可以使用 nydusd 替代。Nydus Snapshotter 则是 Host 上的 containerd 快照插件，负责 Nydus 镜像层和快照管理，与 nydusd 配合实现镜像数据的按需加载，集成方式见 Kata Containers with virtio-fs-nydus。

flowchart TB
    subgraph host["Host"]
        containerd["containerd / CRI-O"]
        shim["Kata shim (containerd-shim-kata-v2)"]
        vmm["Hypervisor / VMM (QEMU, Cloud Hypervisor, ...)"]
        virtiofs["virtio-fs daemon (virtiofsd / nydusd)"]
        containerd -->|"1. create pod"| shim
        shim -->|"2. launch VM"| vmm
        shim -->|"2. start fs daemon"| virtiofs
    end

    subgraph vm["Lightweight VM (own guest kernel)"]
        agent["kata-agent"]
        workload["Container workload"]
        agent -->|"4. start & manage"| workload
    end

    vmm ==>|"3. boot guest"| vm
    shim <-.->|"control channel over VSOCK"| agent
    virtiofs ==>|"share host content (virtio-fs)"| workload

图：Kata Containers 的 Host 与 Guest 组件，以及控制连接和文件共享路径。来源：Kata Containers Quick Start Guide，Apache License 2.0。

核心组件¶

• Kata Shim：运行在 Host 上的 containerd-shim-kata-v2 实现 containerd Runtime v2 接口，接收容器管理请求，并负责 VM、容器和资源的生命周期管理。在 Kubernetes 中，同一 Pod 的多个容器由一个 Kata Shim 进程管理。Kata Shim 的 Rust 实现源码位于 runtime-rs，编译后生成的可执行程序就是 containerd-shim-kata-v2。

  Kata Shim 的架构与实现演进

  Shim v2 架构

  下图对比了早期架构与 Shim v2 架构，变化主要在 Host 上的进程组织和容器管理请求的处理方式：

  • 早期架构（图上）：每个容器需要 containerd-shim 和 kata-shim，容器管理器通过 OCI 命令行多次执行 kata-runtime，完成创建、启动等操作。未使用 VSOCK 的配置还需要独立的 kata-proxy，连接 VM 内的 kata-agent。反复启动运行时进程会增加开销，也需要在多次调用之间保存和恢复 VM 状态，具体说明见 History。
  • Shim v2（图下）：Kata 从 1.5.0 开始支持 Shim v2。containerd 通过 Runtime v2 接口向常驻的 containerd-shim-kata-v2 发送请求，由同一进程管理一个 Pod 的 VM 和容器，并与 kata-agent 通信。原先分散在 kata-runtime、kata-shim 和 kata-proxy 中的管理职责合并到这个进程中，无需为每次容器操作重新启动运行时。

  

  图：Kubernetes 集成 Kata Containers 时，Shim v2 引入前后的组件关系。来源：How to use Kata Containers and Containerd，Apache License 2.0。

  Go 与 Rust Runtime

  早期 Kata Runtime 使用 Go 实现，源码位于 src/runtime，其 Shim v2 实现同样生成 containerd-shim-kata-v2。Kata Containers 3.0.0 引入 Rust 实现 runtime-rs，此时 Rust Runtime 作为新增实现与 Go Runtime 并存。

  从 Kata Containers 4.0.0 起，runtime-rs 成为默认 Runtime。Go Runtime 被标记为弃用，不再接受新提出的功能，弃用期间仍接收关键 Bug 和 CVE 修复。

  Shim v2 指 containerd 的运行时接口版本，Go 和 Rust 则是实现该接口的语言。 Kata 4.2.0 官方预构建包中，两种实现的安装路径不同：Go Runtime 为 /opt/kata/bin/containerd-shim-kata-v2，Rust Runtime 为 /opt/kata/runtime-rs/bin/containerd-shim-kata-v2，安装说明见 Installation。

• VMM：全称 Virtual Machine Monitor（虚拟机监控器），也称 Hypervisor，负责创建和运行 VM，管理 Guest 的 vCPU、内存和虚拟设备。Kata Shim 通过所选 VMM 启动 Guest Kernel，支持的 VMM 可以在这里找到 Hypervisors。

• Guest Assets：VMM 启动 VM 所需的 Linux 内核和最小根文件系统镜像。

  • Guest Kernel：传递给 VMM、用于启动 VM 的 Linux 内核，运行后为容器提供系统调用和资源管理功能。Kata 默认提供基于 Linux LTS 的内核，针对启动时间和内存占用进行优化，只保留容器工作负载所需的服务。

  • Guest Image：提供 VM 启动和运行 kata-agent 所需的最小根文件系统。Kata 支持以下两种形式：

    • rootfs 镜像：将根文件系统制作为磁盘镜像，由 VMM 提供给 VM，Guest Kernel 挂载其中的文件系统作为 VM 的根目录 /。
    • initrd：将根文件系统打包为压缩的 cpio 归档，启动时加载到 VM 内存中，由 Guest Kernel 解包，形成内存中的根文件系统。
  Guest Image 与容器镜像

  下图展示了一个使用 Kata Containers 运行的 Pod，其中的两个容器运行在同一台 VM 中。基于 Ubuntu 构建的 Guest Image 提供 VM 的启动文件和 kata-agent 的运行环境。VM 启动后，kata-agent 创建并管理两个容器，分别将 alpine 和 debian 镜像的 rootfs 设置为容器 A、B 的根目录。

  

  图：Guest Image 与容器镜像提供的根文件系统。

  图中的三个 / 表示不同运行环境中的根目录。容器 A 访问 /bin/sh、/lib 时，使用 Alpine 的文件；容器 B 使用 Debian 的文件；kata-agent 则继续使用 Guest Image 提供的环境。容器的 rootfs 不会替换 VM 的根文件系统，三个环境中的进程都通过系统调用使用同一个 Guest Kernel。

  将 rootfs 设置为容器根目录，就是让容器中的程序把这棵文件树当作自己的 /，从这里开始查找文件。容器 A 的 /bin/sh 对应 VM 中的 /containers/a/rootfs/bin/sh。容器 B 的 /bin/sh 则对应 /containers/b/rootfs/bin/sh。容器内只需使用 /bin/sh，无需填写 rootfs 前缀。VM 使用的 Guest Kernel 和 Guest Image 均由 Kata 配置指定。

• kata-agent：运行在 VM 内的常驻进程，打包在用于启动 VM 的 Guest Image 中。Kata Shim 通过配置的 VMM 启动 VM 后，kata-agent 随之启动，负责创建 VM 内的容器并管理其生命周期。Kata Shim 通过轻量级 RPC（远程过程调用）框架 ttRPC 向它发送容器管理请求，接口定义见 AgentService。

• virtio-fs daemon：运行在 Host 上的文件系统服务，通过 virtio-fs 将指定目录共享给 VM，处理 VM 对这些目录的文件访问请求。Kata 使用它向 VM 提供容器 rootfs 和挂载目录，通常使用 virtiofsd，也支持由 nydusd 提供 virtio-fs 服务。

容器创建与启动¶

以 containerd 调用 Kata 4.2.0 的 runtime-rs 为例，容器的创建与启动分为以下阶段：

图：containerd 创建与启动 Kata 容器的流程。

1. containerd 调用 Kata Shim：containerd 准备 OCI Bundle，启动 containerd-shim-kata-v2，通过 Runtime v2 的 Task 接口发送 Create 请求。Shim 读取 OCI 配置和 Kata 运行时配置，确定使用的 VMM、Guest Kernel、Guest Image 和资源配置。
2. 启动 VM：Shim 准备 VM 所需的资源，通过 start_vm() 启动作为 VMM（Virtual Machine Monitor，虚拟机监视器）的 QEMU。QEMU 通过宿主机的 KVM 接口创建 VM，并加载 Guest Kernel。Kata 利用 Linux 内核的 DAX 功能，将宿主机上的 Guest Image 映射到 VM 中，作为 VM 的根文件系统。Guest Kernel 从 /dev/pmem* 设备挂载这个文件系统，形成 VM 的根目录 /，提供 kata-agent 及其运行所需的文件。
3. 启动 Agent 并初始化 Sandbox：kata-agent 随 VM 启动。Shim 通过 VSOCK 或 hybrid VSOCK 与 Agent 建立 ttRPC 连接，再发送 CreateSandbox 请求，设置 VM 内 Sandbox 的主机名、DNS、共享 Namespace 和存储等。
4. 创建容器环境：Shim 将容器 rootfs 和数据卷接入宿主机共享目录，由 virtiofsd 通过 virtio-fs 向 VM 提供文件访问服务。Shim 发送 CreateContainer 请求后，Agent 根据 OCI 配置准备挂载、Namespace 和 cgroup，将共享的 rootfs 挂载到 VM 内为该容器准备的目录，再将其设置为 容器进程的根目录 /。VM 自身仍使用 Guest Image 提供的根文件系统。Agent 同时创建等待启动的初始进程，此时尚未执行应用的启动命令。
5. 启动应用：containerd 发送 Task Start 请求，Shim 调用 Agent 的 StartContainer，让初始进程执行 OCI 配置中的启动命令。应用使用容器 rootfs 中的程序和库，系统调用由 VM 的 Guest Kernel 处理。

同一 Pod 后续创建的容器复用已有 VM 和 kata-agent，分别准备各自的 rootfs 和容器环境，无需再次启动 VM。

使用方式¶

Docker Engine 26 及以上版本可以直接通过 Kata Shim 启动容器。这里使用 runtime-rs 和 QEMU，主机需要可用的 /dev/kvm；Kata 安装步骤见 Kata Containers Installation。

安装到 /opt/kata/ 后，将以下 runtimes.kata 配置合并到 /etc/docker/daemon.json。runtimeType 指定 Kata Shim 的路径，ConfigPath 选择 QEMU 对应的 Runtime 配置：

{
  "runtimes": {
    "kata": {
      "runtimeType": "/opt/kata/runtime-rs/bin/containerd-shim-kata-v2",
      "options": {
        "ConfigPath": "/opt/kata/share/defaults/kata-containers/runtime-rs/configuration-qemu-runtime-rs.toml"
      }
    }
  }
}