Containerd 运行时的 K8S 集群离线导入镜像的方案

原创已于 2025-12-23 10:40:45 修改 · 695 阅读

12 ·

CC 4.0 BY-SA版权

文章标签：

#containerd #容器运行时 #容器

于 2025-12-21 21:39:02 首次发布

在 Containerd 运行时的 K8S 集群中离线导入应用镜像，关键在于将镜像正确导入到 containerd 的 k8s.io命名空间，并确保 K8S部署时能使用这些本地镜像。

1. 准备与传输镜像

首先，你需要在可以访问互联网的环境中，准备好要部署的应用镜像。

拉取并保存镜像：使用 Docker 拉取镜像，重新标记为符合 K8s 需求的标签（如需），然后导出为 .tar文件。

docker pull <原镜像名称:标签>
docker tag <原镜像名称:标签> <新镜像名称:标签> # 可选，使镜像标签符合部署要求
docker save -o <镜像文件名>.tar <新镜像名称:标签>

docker pull nginx:latest
docker save -o nginx.tar nginx:latest

提示：docker save保存的是展开后的格式，文件可能较大。虽然 docker save也支持输出为 .tar.gz，但 ctr image import命令不支持直接导入压缩格式，如果得到的是 .tar.gz文件，需要先解压。

# Docker 运行时服务器压缩
docker save my-app:v1.0 | gzip > my-app-v1.0.tar.gz

# 传输到Containerd 运行时服务器

# Containerd 运行时服务器解压
gunzip    my-app-v1.0.tar.gz  
ctr   -n=k8s.io   images    import   my-app-v1.0.tar

举例：如需部署 nginx:latest，操作如下：
传输镜像文件：将生成的 .tar文件复制到离线环境中的 K8s 工作节点（如果需要部署到多个节点，则每个节点都需要复制）。

scp    <镜像文件名>.tar     用户名>@<节点IP>:<目标路径>

2. 导入镜像

这是最关键的一步，需要将镜像导入到 containerd 的正确命名空间中。

导入镜像：登录到目标 K8s 节点，使用 ctr命令导入镜像。务必使用 -n k8s.io参数，这能确保镜像被导入到 Kubernetes 使用的命名空间。
```
ctr -n k8s.io image import <镜像文件名>.tar
```
- 注意：如果镜像文件是 .tar.gz格式，需要先解压：

验证导入：导入完成后，使用以下命令检查镜像是否存在。

# 使用 ctr 查看
ctr -n k8s.io images list | grep <镜像名称>

# 或者使用与 CRI 接口兼容的 crictl 查看
crictl images | grep <镜像名称>

3. 部署应用

镜像准备就绪后，就可以在 K8s 集群中部署你的应用了。

创建部署配置文件：编写一个 K8s 的 Deployment YAML 文件。关键点在于需要设置 imagePullPolicy: IfNotPresent或 imagePullPolicy: Never。这会指示 Kubelet 不要尝试从远程仓库拉取镜像，而是直接使用本地已存在的镜像。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: your-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: your-app
  template:
    metadata:
      labels:
        app: your-app
    spec:
      containers:
      - name: your-app-container
        image: <你在节点上导入的完整镜像名称和标签>  # 例如: nginx:latest
        imagePullPolicy: IfNotPresent  # 重要！
        ports:
        - containerPort: 80

应用配置：使用 kubectl部署你的应用。
```
kubectl apply -f your-deployment.yaml
```

4. 技巧与注意事项

批量操作：如果需要导入多个镜像，可以写一个简单的循环脚本。
```
for image in /path/to/your/*.tar; do
    ctr -n k8s.io image import "$image"
done
```
镜像已经存在：如果导入时提示镜像已存在，可以使用 ctr -n k8s.io images rm <镜像名>先删除旧镜像再导入，或者使用 --force选项强制替换（如果 ctr版本支持）。