Containerd 客户端工具

containerd 的客户端工具有 ctr、crictl 和 nerdctl，三者定位与适用场景差异显著：

• ctr：👉 containerd 官方底层工具，适用于调试/学习，不适合 K8s 运维和日常运行容器
• crictl：👉 Kubernetes 专用 CRI 工具，排障必备，不能 创建容器、不能 exec
• nerdctl：👉 Docker CLI 替代品，日常使用最顺手

核心定位对比

工具	官方定位	面向对象	是否推荐使用
ctr	containerd 原生 CLI	containerd 开发者	不推荐
crictl	CRI 调试工具	Kubernetes 运维	仅排障
nerdctl	Docker CLI 兼容工具	运维 / 开发	强烈推荐

---

🔍 三大工具核心能力对比

对比项	ctr	crictl	nerdctl
直接操作 containerd	✅	❌（走 CRI 协议）	✅
支持 Kubernetes	❌	✅	⚠️（需指定 namespace）
兼容 Docker 命令习惯	❌	❌	✅
支持 Compose	❌	❌	✅（nerdctl compose）
镜像构建（build）	⚠️（需 buildctl）	❌	✅
镜像推/拉/登录	⚠️（需额外配置）	❌	✅
存储卷/网络管理	⚠️/❌	❌/❌	✅/✅
Rootless 模式	❌	❌	✅
Namespace 概念	强制指定	自动隐藏	自动处理
学习成本	⭐⭐⭐⭐（高）	⭐⭐⭐（中）	⭐（低）

---

💡 关键细节解读：Namespace（90% 的坑都在这）

containerd 用 namespace 做资源隔离，三个工具的默认 namespace 完全不同，是最易踩坑点：

• ctr/nerdctl 默认使用 default 命名空间，看不到 Kubernetes 容器
• crictl 默认走 k8s.io 命名空间，能直接看到 Pod 容器
• 如需用 ctr/nerdctl 查看 Kubernetes 容器，必须手动指定 -n k8s.io

命令示例（运维高频场景）

# 1. 查看普通容器（default 命名空间）
ctr containers ls               

# 2. 查看 K8s 容器（指定 k8s.io 命名空间）
ctr -n k8s.io containers ls      

# 3. crictl 直接查看 K8s 容器（无需指定 namespace）
crictl ps                       

# 4. nerdctl 查看 K8s 容器（需手动指定 namespace）
nerdctl -n k8s.io ps            

---

常见命令对照表（运维最常用）

需求场景	Docker 命令	nerdctl 命令	crictl 命令	ctr 命令
查看运行中容器	docker ps	nerdctl ps	crictl ps	ctr containers ls（简写：ctr c ls）
查看本地镜像	docker images	nerdctl images	crictl images	ctr images ls（简写：ctr i ls）
进入容器终端	docker exec -it <容器ID> sh	nerdctl exec -it <容器ID> sh	❌ 不支持	❌ 不支持
查看容器日志	docker logs <容器ID>	nerdctl logs <容器ID>	crictl logs <容器ID>	❌ 不支持
拉取镜像	docker pull <镜像名>	nerdctl pull <镜像名>	crictl pull <镜像名>	ctr images pull <镜像名>（简写：ctr i pull）
构建镜像	docker build -t <标签> .	nerdctl build -t <标签> .	❌ 不支持	❌ 不支持

---

全量命令对照表（镜像+容器+交互）

操作场景	Docker 命令	ctr (containerd 原生)	crictl (Kubernetes CRI)
镜像管理
查看本地镜像	docker images	ctr image ls	crictl images
拉取镜像	docker pull <镜像名>	ctr image pull <镜像名>	crictl pull <镜像名>
推送镜像	docker push <镜像名>	ctr image push <镜像名>	❌ 不支持
删除镜像	docker rmi <镜像ID>	ctr image rm <镜像ID>	crictl rmi <镜像ID>
导入镜像（从 tar 包）	docker load -i <文件.tar>	ctr image import <文件.tar>	❌ 不支持
导出镜像（为 tar 包）	docker save -o <文件.tar> <镜像>	ctr image export <文件.tar> <镜像>	❌ 不支持
修改镜像标签	docker tag <源> <目标>	ctr image tag <源> <目标>	❌ 不支持
容器生命周期
创建容器	docker create	ctr container create	crictl create
运行容器	docker run	ctr run	❌ 不支持（K8s 最小单元为 Pod）
删除容器	docker rm <容器ID>	ctr container rm <容器ID>	crictl rm <容器ID>
查看运行中容器	docker ps	ctr task ls / ctr container ls	crictl ps
启动已停止容器	docker start <容器ID>	ctr task start <容器ID>	crictl start <容器ID>
停止运行容器	docker stop <容器ID>	ctr task kill <容器ID>	crictl stop <容器ID>
容器交互与监控
在容器内执行命令	docker exec -it <容器ID> sh	❌ 不支持	crictl exec -it <容器ID> sh
查看容器详情	docker inspect <容器ID>	ctr container info <容器ID>	crictl inspect <容器ID>
查看容器日志	docker logs <容器ID>	❌ 不支持	crictl logs <容器ID>
查看容器资源占用	docker stats <容器ID>	❌ 不支持	crictl stats <容器ID>

---

工具详解

1. ctr & crictl

• ctr：containerd 官方提供的原生客户端工具，深度绑定 containerd 底层能力。
• crictl：CRI 兼容的容器运行时命令行工具，与 containerd 无强关联，由 kubernetes-sigs 维护，专用于 K8s 节点容器运行时调试。

crictl 配置示例

https://kubernetes.io/docs/tasks/debug/debug-cluster/crictl/
# 查看 crictl 配置文件
cat /etc/crictl.yaml
# 典型配置内容
runtime-endpoint: unix:///var/run/containerd/containerd.sock
image-endpoint: unix:///var/run/containerd/containerd.sock
timeout: 10
debug: true

SIGs 介绍

https://github.com/kubernetes-sigs
Special Interest Groups (SIGs) 是 Kubernetes 社区内的子组，专注于 Kubernetes 开发的特定领域或领域。它们由对项目的特定方面有共同兴趣的个人和组织组成。SIG 负责推动设计提案、审查和批准新功能、维护和发展现有功能，以及为更广泛的 Kubernetes 社区提供指导和支持。

ctr 导入镜像示例

# 导入本地 tar 包镜像
ctr image import flannel-v0.27.4.tar 
# 查看导入后的镜像
ctr image ls

2. nerdctl

2.1 介绍

nerdctl 是 Docker 兼容的 Containerd CLI 工具，支持 Compose，命令语法与 Docker 高度一致，学习成本低，为 containerd 官网推荐工具。

• 项目地址：https://github.com/containerd/nerdctl
• 发布包类型：
  • Minimal：仅含 nerdctl 二进制 + rootless 辅助脚本
  • Full：全量包，包含 Containerd、CNI、runc、BuildKit 等完整组件

2.2 单机安装（替代 Docker）

# 下载版本（以 2.2.1 为例）
VERSION=2.2.1

wget https://github.com/containerd/nerdctl/releases/download/v${VERSION}/nerdctl-full-${VERSION}-linux-amd64.tar.gz

# 查看包内容
tar tf nerdctl-full-${VERSION}-linux-amd64.tar.gz

# 解压安装（至 /usr/local）
tar Cxvf /usr/local nerdctl-full-${VERSION}-linux-amd64.tar.gz

# 查看帮助
nerdctl --help

2.3 K8s 集群中安装使用

# 所有节点执行（下载 Minimal 包）
VERSION=2.2.1
# 直接下载
wget https://github.com/containerd/nerdctl/releases/download/v${VERSION}/nerdctl-${VERSION}-linux-amd64.tar.gz
# 加速下载（可选）
wget https://mirror.ghproxy.com/https://github.com/containerd/nerdctl/releases/download/v${VERSION}/nerdctl-${VERSION}-linux-amd64.tar.gz

# 解压安装（至 /usr/local/bin）
tar xf nerdctl-${VERSION}-linux-amd64.tar.gz -C /usr/local/bin/

# 方式1：手动指定 namespace 查看 K8s 容器/镜像
nerdctl -n k8s.io images
nerdctl -n k8s.io ps

# 方式2：配置默认 namespace（无需每次指定 -n k8s.io）
mkdir /etc/nerdctl/
cat > /etc/nerdctl/nerdctl.toml << EOF
namespace = "k8s.io" # 默认命名空间
debug = false
debug_full = false
insecure_registry = true  # 启用非安全镜像仓库
EOF

# 导入镜像（指定/默认 namespace）
nerdctl load -i flannel-v0.26.7.tar                # 默认 namespace
nerdctl -n k8s.io load -i flannel-v0.26.7.tar     # K8s namespace

2.4 常见问题：CNI 版本不兼容

问题现象：创建容器时报错 incompatible CNI versions

新版已无此问题

nerdctl run -d --name nginx -p 80:80 nginx:alpine
# 报错：plugin type="bridge" failed (add): incompatible CNI versions

解决方法：

# 查看 containerd 配置的 CNI 目录
grep cni /etc/containerd/config.toml  # 通常为 /opt/cni/bin
    [plugins."io.containerd.grpc.v1.cri".cni]
      bin_dir = "/opt/cni/bin"
      conf_dir = "/etc/cni/net.d"
        cni_conf_dir = ""
        cni_max_conf_num = 0
          cni_conf_dir = ""
          cni_max_conf_num = 0
        cni_conf_dir = ""
        cni_max_conf_num = 0

# 备份原有 CNI 插件
mv /opt/cni/bin/ /srv/

# 下载新版 CNI 插件（v1.1.1 为例）
wget https://github.com/containernetworking/plugins/releases/download/v1.1.1/cni-plugins-linux-amd64-v1.1.1.tgz

tar xf cni-plugins-linux-amd64-v1.1.1.tgz -C /opt/cni/bin/

# 重新创建容器
nerdctl rm -f nginx
nerdctl run -d --name nginx -p 80:80 nginx:alpine

# 验证运行状态
nerdctl ps