从零实现 crictl pull kubesphere/kube-apiserver:v1.31.0 的全流程操作-CSDN博客

kubesphere/kube-apiserver:v1.31.0 是 KubeSphere v4.1（对标 K8s v1.31）的核心控制面镜像。若机器直接访问 Docker Hub 受限或目标集群处于内网，必须先把镜像「拉取—导出—导入」到运行时（containerd/CRI-O）才能正常启动 kube-apiserver。
Docker 客户端对 containerd 并不天然可见，因此推荐使用 crictl（或 ctr）与 CRI 交互。

步骤一：准备 crictl 运行环境

安装 crictl

curl -LO https://github.com/kubernetes-sigs/cri-tools/releases/download/v1.31.0/crictl-v1.31.0-linux-amd64.tar.gz
sudo tar -C /usr/local/bin -xzvf crictl-v1.31.0-linux-amd64.tar.gz

配置连接端点 (/etc/crictl.yaml)

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

验证 CLI 可用性

crictl info | jq '.status.runtimeType'     # 输出应为 "containerd"

步骤二：在线直接拉取（能出网）

sudo crictl pull docker.io/kubesphere/kube-apiserver:v1.31.0

Tip crictl pull 默认写入 containerd 的 k8s.io namespace，无需额外指定。
镜像 7 个月前已推送到 Docker Hub，可正常拉取 citeturn0search1

步骤三：离线/网络受限环境处理

3-1 在有外网的跳板机上

# 1. 拉取
docker pull kubesphere/kube-apiserver:v1.31.0

# 2. 导出为 tar
docker save kubesphere/kube-apiserver:v1.31.0 \
  -o kube-apiserver-v1.31.0.tar

若 Docker Hub 被墙，可先配置镜像加速器或从自建私服同步，再执行 docker pull。

3-2 拷贝到目标节点并导入

# 3. 传输文件（示例用 scp）
scp kube-apiserver-v1.31.0.tar user@master:/tmp/

# 4. 在目标节点导入到 containerd
sudo ctr -n k8s.io images import /tmp/kube-apiserver-v1.31.0.tar

# 5. 查看镜像
crictl images | grep kube-apiserver

步骤四：验证镜像可用性

# test-apiserver.yaml
apiVersion: v1
kind: Pod
metadata:
  name: test-apiserver
spec:
  containers:
  - name: kube-apiserver
    image: kubesphere/kube-apiserver:v1.31.0
    command: ["kube-apiserver","--help"]    # 只做启动测试
    resources:
      limits:
        cpu: 50m
        memory: 128Mi

kubectl apply -f test-apiserver.yaml
kubectl get pod test-apiserver

Pod 若快速进入 Completed/Running 即表示镜像已被正确加载。

常见问题与解决方案

现象	可能原因	解决办法
`rpc error: code = NotFound`	镜像版本/仓库名称写错	确认 Docker Hub 标签存在 (`kubesphere/kube-apiserver:v1.31.0`) citeturn0search1
`x509: certificate signed by unknown authority`	目标私有仓库为自签证书	在 `/etc/containerd/config.toml` 的 `config_tls` 中信任 CA；或在 `/etc/containers/registries.conf` 标记为 `insecure`
导入后 Pod 仍 `ImagePullBackOff`	镜像被误导入 `default` namespace	使用 `sudo ctr -n k8s.io images import ...` 重新导入
多架构集群拉取失败	拉取到不匹配架构的 Manifest	`crictl pull --platform=linux/arm64 ...` 指定架构；或提前裁剪 Manifest List

高级操作

1. 配置 containerd 镜像加速

在 /etc/containerd/config.toml 中添加：

[plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
  endpoint = ["https://registry.cn-hangzhou.aliyuncs.com"]

重启服务后，crictl pull kubesphere/kube-apiserver:v1.31.0 直接走国内镜像加速。

2. 批量拉取脚本

#!/usr/bin/env bash
IMAGES=(
  "kubesphere/kube-apiserver:v1.31.0"
  "kubesphere/kube-controller-manager:v1.31.0"
)
for img in "${IMAGES[@]}"; do
  docker pull ${img} &&
  docker save ${img} -o $(basename ${img//[:\/]/_}).tar
done

关键命令速查表

操作	命令
在线拉取	`sudo crictl pull docker.io/kubesphere/kube-apiserver:v1.31.0`
导出镜像	`docker save kubesphere/kube-apiserver:v1.31.0 -o kube-apiserver.tar`
导入至 containerd	`sudo ctr -n k8s.io images import kube-apiserver.tar`
查看镜像	`crictl images