# AI时代的K3s教程30招-第8招-containerd、CRI和镜像到底是怎么把Pod跑起来的？

> Pod 卡在 ContainerCreating，是镜像问题，还是运行时链路问题？

```text
[读者] 正在把企业数字人平台搬上 K3s 的后端工程师
[痛点] 会写 YAML，却说不清 Pod 到底由谁创建，crictl 与 ctr 输出对不上
[现在读] 平台要接 ASR、TTS、LLM Gateway 和 GPU Worker，运行时层不能再靠猜
[读完] 能沿着 kubelet → CRI → containerd 链路定位 Pod 启动问题，并读懂 K3s 生成的 runtime 配置
```

```text
[旧方案] 单节点 Docker Compose 起数字人服务，docker ps 看容器
    |
    v
[新需求] 迁到 K3s，多节点、GPU、镜像仓库、Pod 沙箱都要统一治理
    |
    v
[冲突] Docker CLI 习惯解释不了 CRI Pod Sandbox，ctr 默认命名空间也看不到 K8s 容器
    |
    v
[后果] 排障时在 docker、crictl、ctr 三者之间打转，误改 config.toml，Pod 反复起不来
```

我是老李，在企业数字人平台做基础设施。那天早上的任务是：把 avatar-runtime-demo 从 Docker Compose 挪到 K3s，并让 User Service、ASR、TTS、LLM Gateway 能在同一集群里互相调用。过去用 Docker Compose，docker ps 一眼看全。现在 K3s 的 Pod 由 kubelet 管，容器却由 containerd 创建。第一次排障时，docker ps 什么都没有，crictl ps 看得到，ctr containers list 又看不到。

企业数字人平台不是单体应用。User Service 接会话，ASR 做语音识别，TTS 做语音合成，LLM Gateway 接 RAG 和 Model Inference，LiveKit 负责媒体流，Avatar Inference 跑在 GPU Worker 上。每一个 Pod 能跑起来，底层都要经过镜像拉取、Pod Sandbox 创建、容器创建、CRI 接口调用这几步。

旧方案里，Docker Engine 既是运行时，也是 CLI，也是镜像仓库客户端。新方案里，K3s 默认内置 containerd，kubelet 不再直接管 Docker，而是通过 CRI 调 containerd。命令没换几个，抽象却换了一层。

那么，K3s 的 kubelet 到底通过什么接口让 containerd 创建 Pod？

遇到 Pod 启动失败，应该先看 crictl 还是 ctr？

如果为了兼容旧习惯，把 Docker Engine 设为默认运行时，会付出什么代价？

# 01、故事

故事发生在企业数字人平台从单机 Compose 迁到 K3s 的第一周。任务是让 avatar-runtime-demo 先跑起来，再逐步接 ASR、TTS、LLM Gateway。旧环境里，docker-compose up 之后，docker ps 能看到所有容器，镜像用 docker images 查，日志用 docker logs 看。

迁到 K3s 后，kubectl get pod 显示 Running，但我想确认容器到底在不在，第一反应还是 docker ps。结果是空的。同事提醒我：K3s 默认用 containerd，不用 Docker Engine。于是我又试 crictl ps，看到了容器；再试 ctr containers list，还是空的。

同一个 Pod，为什么 crictl 能看到，ctr 看不到？为什么 K3s 要内置 containerd，而不是继续用 Docker？为什么 /var/lib/rancher/k3s/agent/etc/containerd/config.toml 这个文件改了不生效？

这三个问题不解决，后面接 GPU Worker、私有仓库、Air-Gap 部署都会踩坑。因为镜像、沙箱、运行时、命名空间这四件事，全部挂在 containerd 这条链上。

> 一栈两世界
> 一云一旧念
> 一错镜中寻
> 一链终分明

# 02、问题

旧方案失效得很直接：Docker CLI 看不到 K3s 的容器。业务影响是排障时间变长，发布时不敢确认镜像是否真的被拉取，Pod 起不来时只能反复重启。技术表现是三个命令输出不一致：kubectl 说 Running，crictl 说 No containers，ctr 说 containers 为空。

更麻烦的是，企业数字人平台的镜像体积不小。ASR、TTS、LLM Gateway、Avatar Inference 各自依赖不同，镜像层多，拉取慢。如果连镜像在哪个命名空间、由哪个运行时管理都说不清，私有仓库接入和 GPU 节点调度就会变成黑盒。

本篇的可验证完成标准有四条。第一，能解释 kubelet 通过 CRI 调 containerd 创建 Pod Sandbox 和 Container。第二，能用 crictl ps/images/logs 定位 Pod 级问题。第三，能用 ctr -n k8s.io containers/images 看到同一批容器和镜像。第四，能读懂 K3s 生成的 config.toml，不再直接手改生成文件。

这四条不是背命令，而是建立一条排障链路：先看 CRI，再看 containerd，最后看配置和镜像仓库。链路清楚了，Docker Engine 是否要当默认运行时，也就有了判断依据。

> 旧法不相容
> 新需已不同
> 一问定方向
> 一考可验收

# 03、原理

K3s 默认内置 containerd。kubelet 不直接创建容器，而是通过 CRI 与容器运行时通信。CRI 是 Kubernetes 定义的容器运行时接口，包含 RuntimeService 和 ImageService。RuntimeService 负责 Pod Sandbox 和 Container 的生命周期，ImageService 负责镜像拉取、查询和删除。

containerd 内置 CRI plugin，K3s 启动 agent 时会生成 containerd 配置，路径是 /var/lib/rancher/k3s/agent/etc/containerd/config.toml。这个文件是生成物，不是手改入口。K3s 会结合内置模板、用户模板 config.toml.tmpl 和 registries.yaml 生成最终配置。直接改 config.toml，重启后会被覆盖。

反直觉判断：crictl 不是 containerd 的客户端，而是 CRI 的客户端。crictl 面向 kubelet 使用的 CRI 端点，所以它看到的是 Kubernetes 语义下的 Pod Sandbox 和容器。ctr 是 containerd 自带客户端，面向 containerd 原生 API，默认命名空间不是 k8s.io，所以不指定 -n k8s.io 时看不到 K8s 容器。

Pod Sandbox 也不是业务容器。以 containerd 为例，一个 Pod 通常先有 sandbox 容器，负责网络命名空间等基础设施，然后才有业务容器。crictl pods 看 sandbox，crictl ps 看业务容器。理解这一层，才能解释为什么 kubectl 显示 Pod 已创建，但业务容器还在 ContainerCreating。

> 接口藏深意
> 沙箱非容器
> 反直觉处
> 真相自显现

# 04、架构

```text
[输入] kubectl apply 或 K3s 内部控制器提交 Pod 规格
    |
    v
[模块] kubelet + CRI + containerd CRI plugin
    |
    v
[数据/状态] Pod Sandbox、Container、镜像、snapshotter、命名空间 k8s.io
    |
    v
[处理] 拉取镜像、创建 sandbox、创建业务容器、启动任务
    |
    v
[输出] 节点上的 containerd task 与 Pod 网络，kubectl 看到 Running
```

这条链的边界很清楚。kubelet 负责 Pod 生命周期和 CRI 调用，containerd 负责镜像与容器运行，CNI 负责网络，K3s 负责生成运行时配置。收益是运行时内置、依赖少、升级路径统一。代价是 Docker CLI 习惯失效，排障要换成 crictl 和 ctr，配置要理解生成逻辑。

适用条件是 K3s 默认安装、使用内置 containerd。若使用外部 CRI 端点，需通过 K3s agent 的 --container-runtime-endpoint 指向对应 socket，具体参数以当前官方文档为准。

> 一入CRI门
> 二分沙箱身
> 三存镜像地
> 四出Pod成

# 05、实战一次

环境：单节点 K3s，Linux，内置 containerd。依赖：kubectl、crictl、ctr 可用。未在当前环境实测，以下为预期结果。

先写一个最小应用。

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: avatar-runtime-demo
data:
  APP_MODE: runtime-demo
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: avatar-runtime-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: avatar-runtime-demo
  template:
    metadata:
      labels:
        app: avatar-runtime-demo
    spec:
      containers:
        - name: app
          image: busybox:1.36
          command: ['sh','-c','while true; do echo $APP_MODE; sleep 30; done']
          envFrom:
            - configMapRef:
                name: avatar-runtime-demo
```

启动。

```bash
kubectl apply -f avatar-runtime-demo.yaml
kubectl get pod -o wide
```

示例输出如下。

```console
NAME                                  READY   STATUS    RESTARTS   AGE
avatar-runtime-demo-7c9d8f6b5d-abcde   1/1     Running   0          20s
```

现在用 crictl 看 CRI 视角。

```bash
crictl pods
crictl ps
crictl images
crictl logs <container-id>
```

再用 ctr 看 containerd 原生视角。

```bash
ctr -n k8s.io containers list
ctr -n k8s.io images list
ctr -n k8s.io tasks list
```

示例输出中，crictl ps 能看到名为 app 的业务容器，ctr -n k8s.io containers list 能看到对应容器，但 ctr containers list 不带命名空间时为空。最后查看 K3s 生成的配置。

```bash
cat /var/lib/rancher/k3s/agent/etc/containerd/config.toml
```

这个文件里能看到 CRI plugin、snapshotter 和 runtime 相关配置。不要直接编辑它。要改仓库镜像，用 /etc/rancher/k3s/registries.yaml；要改 containerd 模板，用 config.toml.tmpl。

> 一apply起
> 一pod立
> 一crictl看
> 一ctr验

# 06、排查

第一条诊断链。现象：Pod 一直 ContainerCreating，kubectl describe 显示 Failed to pull image。怀疑：镜像仓库不可达或镜像名错误。检查：kubectl describe pod 看 Events，crictl images 看节点镜像，ctr -n k8s.io images list 看 containerd 镜像。证据：Events 里出现 no such host 或 pull access denied。根因：私有仓库未通过 registries.yaml 接入，或镜像拉取凭证缺失。修复：在 /etc/rancher/k3s/registries.yaml 配置 mirror 和 auth，重启 K3s agent 后重新调度。

这里有一个错误尝试。

**错误尝试：** 直接编辑 /var/lib/rancher/k3s/agent/etc/containerd/config.toml，在文件里加 registry mirror，然后 systemctl restart k3s。重启后 crictl ps 仍然报镜像拉取失败，打开 config.toml 发现改动被覆盖。错误原因：K3s 会在启动时重新生成这个文件，手改生成物不是受支持的配置入口。正确做法是用 registries.yaml，或者用 config.toml.tmpl 写模板。

第二条诊断链。现象：crictl ps 能看到容器，ctr containers list 看不到，于是怀疑 containerd 丢失容器。怀疑：ctr 命令有问题。检查：ctr namespaces list，再执行 ctr -n k8s.io containers list。证据：namespaces list 里有 k8s.io，ctr 默认命名空间不是它。根因：ctr 原生客户端默认命名空间为 default，而 K3s 的 Kubernetes 容器在 k8s.io 命名空间下。修复：所有 ctr 查询命令统一加 -n k8s.io，并用 crictl 作为 Pod 级排障第一入口。

> 一查事件明
> 二看命名空
> 三改生成物
> 四复现根因

# 07、优化

基于第 06 章证据，根因有两个：配置入口用错，命名空间用错。V2 的第一个修改是，不再手改 config.toml，改用 /etc/rancher/k3s/registries.yaml 配置私有仓库。原因是 K3s 会把 registries.yaml 合并进生成的 containerd 配置。新行为是重启后镜像仓库配置仍然生效。验证方式是 crictl images 能看到私有仓库镜像，ctr -n k8s.io images list 能看到同一镜像。

V2 的第二个修改是，固定排障顺序。先 kubectl get pod 和 kubectl describe pod 看 Kubernetes 语义，再 crictl ps/images/logs 看 CRI 语义，最后 ctr -n k8s.io containers/images/tasks 看 containerd 语义。原因是三者面向的抽象层不同，顺序固定后不会在命令之间来回跳。验证方式是人为制造一个镜像拉取失败，按顺序定位到 Events 和 crictl images，不再误判为 containerd 故障。

V2 的第三个修改是，把 containerd 配置纳入版本管理。registries.yaml 和 config.toml.tmpl 放进平台仓库，节点安装时统一分发。原因是企业数字人平台有多个节点，手工改一台机器无法复制。验证方式是在新节点加入后，直接 crictl images 和 cat /var/lib/rancher/k3s/agent/etc/containerd/config.toml，确认生成的配置包含预期仓库和 runtime 配置。

> 一改registries
> 二用模板生
> 三验拉镜像
> 四定新流程

# 08、演进

```text
[同一输入]
    |
    +--[V1] 用 Docker 习惯排障，手改 config.toml，ctr 不带命名空间
    |       代价：配置被覆盖，容器看不到，根因误判
    |
    +--[V2] 用 crictl 看 CRI，用 ctr -n k8s.io 看 containerd，用 registries.yaml 和模板做配置
    |       代价：需要理解两层抽象，命令更多，学习成本上升
    |
[Trade-off]
得到可复现的排障链路和可版本化的运行时配置；失去 Docker CLI 的即时熟悉感；适用边界是 K3s 默认 containerd 场景
```

比较正确性：V1 把生成文件当配置入口，正确性低；V2 用受支持的配置入口，正确性高。稳定性：V1 重启后配置丢失，稳定性差；V2 配置可重复生成，稳定性好。复杂度：V1 命令少但认知混乱；V2 命令多但分层清楚。成本：V2 要维护 registries.yaml 和模板；V1 省事但故障成本高。适用范围：V2 适合多节点、私有仓库、GPU 节点和后续 Air-Gap。遗留问题是 GPU runtime 和 NRI 配置还需要单独验证。

> 一入两路分
> 一取一舍间
> 一衡得与失
> 一演进自明

# 09、洞见

## 9.1 crictl 是 CRI 客户端，不是 containerd 客户端

反直觉判断：crictl 看起来像 docker，实际它面向的是 CRI 端点。它看到的是 Kubernetes 语义下的 Pod Sandbox 和 Container，而不是 containerd 原生对象。所以 crictl ps 能看到的容器，ctr 不带命名空间时看不到，并不矛盾。这条判断决定了排障第一入口应该是 crictl，而不是 ctr。

## 9.2 内置 containerd 是把运行时变成平台能力

反直觉判断：K3s 内置 containerd，不只是为了少装一个组件，而是为了把运行时从可替换依赖变成平台内置能力。企业数字人平台要跑 ASR、TTS、LLM Gateway 和 GPU Worker，运行时若还是外部拼装，镜像、仓库、配置、升级会各自为政。内置后，K3s 生成 config.toml，统一管理 CRI 端点、snapshotter 和 registry 配置。

## 9.3 不建议 Docker Engine 当默认运行时，关键在 CRI

反直觉判断：生产 K3s 不建议把 Docker Engine 当默认运行时，不是因为 Docker 差，而是因为 Kubernetes 要的是 CRI，不是 Docker API。Docker Engine 不是 CRI 运行时，需要 cri-dockerd 之类的 shim 才能接入。多一层 shim，就多一层升级、调试和故障面。K3s 默认 containerd，正好把这一层收进平台内部。

## 9.4 config.toml 是生成物，不是手改文件

反直觉判断：看到 /var/lib/rancher/k3s/agent/etc/containerd/config.toml 就想直接改，是 Docker 习惯的延续。但这个文件由 K3s 生成，手改会在重启后被覆盖。正确入口是 registries.yaml 和 config.toml.tmpl。把生成物当配置源，是运行时排障里最容易反复踩的坑。

## 9.5 排障顺序要先 CRI 后 containerd

先 kubectl 看 Pod 语义，再 crictl 看 CRI 语义，最后 ctr -n k8s.io 看 containerd 语义。顺序反过来，容易在 containerd 原生对象里迷失，忽略 Kubernetes 层的 Events 和调度信息。这条顺序在私有仓库、GPU 节点、Air-Gap 场景都适用。

> 一反直觉处
> 二证链路深
> 三辨边界线
> 四见真章明

# 10、系统落地

原来有什么？企业数字人平台有 Docker Compose 版本，有 docker ps、docker images、docker logs 的使用习惯。本篇新增了什么？新增了 K3s 默认 containerd 的运行时链路，新增了 crictl 与 ctr -n k8s.io 的排障方法，新增了 registries.yaml 和 config.toml.tmpl 的配置入口。

现在能做什么？能解释 kubelet 通过 CRI 调 containerd 创建 Pod Sandbox 和 Container，能在 Pod 启动失败时先看 CRI 再看 containerd，能读懂 K3s 生成的 config.toml，并能判断为什么不把 Docker Engine 当默认运行时。

还缺什么？还缺私有镜像仓库的完整接入，还缺 GPU Worker 的 runtime 配置，还缺 containerd 指标和日志的可观测体系，还缺多节点环境下的配置分发。下一步是把 registries.yaml 纳入节点初始化，把 config.toml.tmpl 模板化，再进入 GPU 调度和 Helm 部署。

> 一栈连数字人
> 一运行定根基
> 一补镜像仓
> 一望GPU路

# 11、小结

```text
Q1 → kubelet 通过 CRI 调 containerd，先创建 Pod Sandbox，再创建业务容器
Q2 → 先看 crictl，再看 ctr -n k8s.io，前者是 CRI 视角，后者是 containerd 原生视角
Q3 → Docker Engine 不是 CRI 运行时，设为默认会多出 shim 和升级调试成本，K3s 默认 containerd 更统一
状态 → 已建立从 kubectl 到 CRI 到 containerd 的 Pod 启动排障链路，并能读懂 K3s 生成的 runtime 配置
```

这一篇的可交付能力，不是多背几个命令，而是把 Pod 启动链路拆成三层：Kubernetes 层、CRI 层、containerd 层。企业数字人平台的 Pod 要跑起来，镜像要从仓库拉到 containerd，沙箱要由 CRI 创建，容器要由 containerd task 启动。三层对上，排障就不会乱。

> 一问一答明
> 二问二答清
> 三问三答定
> 状态可交付

# 12、作业

## 12.1 理解题：为什么 crictl ps 能看到容器，ctr containers list 看不到？

参考答案：crictl 面向 CRI 端点，使用 Kubernetes 语义，看到的是 Pod Sandbox 和容器。ctr 面向 containerd 原生 API，默认命名空间不是 k8s.io。K3s 的 Kubernetes 容器在 k8s.io 命名空间下，所以 ctr 必须加 -n k8s.io 才能看到。

## 12.2 实战题：写一个最小 Deployment，并用 crictl 和 ctr 各验证一次。

参考答案：使用 busybox 或 nginx 镜像创建单副本 Deployment，kubectl apply 后执行 kubectl get pod -o wide。再用 crictl ps 查看业务容器，用 crictl images 查看镜像。然后执行 ctr -n k8s.io containers list 和 ctr -n k8s.io images list，确认能看到同一批对象。

## 12.3 排障题：Pod 报 Failed to pull image，如何定位？

参考答案：先 kubectl describe pod 看 Events，确认是仓库不可达、镜像名错误还是认证失败。再 crictl images 看节点是否已有镜像。若确认是私有仓库问题，检查 /etc/rancher/k3s/registries.yaml 是否配置 mirror 和 auth。不要直接改 /var/lib/rancher/k3s/agent/etc/containerd/config.toml，因为它是生成物。

## 12.4 架构判断题：生产 K3s 是否应该把 Docker Engine 设为默认运行时？

参考答案：通常不应该。Kubernetes 需要 CRI 运行时，Docker Engine 不是 CRI 运行时，需要额外 shim。K3s 默认内置 containerd，已经提供 CRI plugin、镜像服务和运行时配置生成。把 Docker Engine 设为默认运行时会增加组件、升级和调试复杂度。特殊兼容场景需按当前官方文档核验。

> 一题一理清
> 二题一行证
> 三题一查明
> 四题一判准

# 13、思考

回到开头的问题：Pod 到底是怎么跑起来的？K3s 的答案不是 Docker CLI，而是 kubelet 通过 CRI 调 containerd，先创建 Pod Sandbox，再创建业务容器。crictl 看 CRI，ctr -n k8s.io 看 containerd，config.toml 是生成物而不是手改文件。Docker Engine 不是不能跑，而是不适合当 K3s 的默认运行时。这条判断可以复用到私有仓库、GPU 节点和后续多节点生产部署。

> 一念辨边界
> 一证定根因
> 一改知取舍
> 一役见真章

Pod 卡在 ContainerCreating，是镜像问题，还是运行时链路问题？

AI时代的K3s教程30招-第8招-containerd、CRI和镜像到底是怎么把Pod跑起来的？

从企业数字人平台的 Pod 启动链路切入，讲清 K3s 内置 containerd、CRI、crictl 与 ctr 的差异，以及为什么不把 Docker En

架构师

云计算

后端

运维

理解K3s Pod启动链路，掌握kubelet→CRI→containerd排障方法。解决crictl与ctr命名空间差异，正确配置registries.yaml而非手改生成文件，规避ContainerCreating故障，提升数字人平台运行时稳定性。

4核4G3M云服务器 新用户低至38元/年！

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

AI时代的K3s教程30招-第8招-containerd、CRI和镜像到底是怎么把Pod跑起来的？-腾讯云开发者社区-腾讯云

AI时代的K3s教程30招-第8招-containerd、CRI和镜像到底是怎么把Pod跑起来的？

AI时代的K3s教程30招-第8招-containerd、CRI和镜像到底是怎么把Pod跑起来的？

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐