单节点Kubernetes如何使用tar导入的本地Docker镜像并解决拉取报错

1. 优先确认Kubernetes容器运行时类型 #

这是90%以上此类问题的根因：目前主流K8s版本默认使用containerd作为容器运行时，而非Docker。你通过docker load导入的镜像仅存于Docker的存储体系中，containerd无法读取。

• 验证命令：kubectl describe node <你的单节点名称> | grep "Container Runtime Version"
• 如果输出为containerd://<版本号>，执行以下命令将镜像导入到K8s使用的containerd命名空间下：

ctr -n k8s.io images import images.tar
# 导入后验证镜像存在
ctr -n k8s.io images list | grep nginx-custom

2. 确认镜像名称与标签完全匹配 #

Docker本地镜像的全称（仓库地址/镜像名/标签）必须和Deployment中image字段100%一致，大小写、符号均不能有差异：

• 验证命令：docker images --format "{{.Repository}}:{{.Tag}}" | grep myprivatehub.com/nginx/nginx-custom
• 确认输出结果完全等于myprivatehub.com/nginx/nginx-custom:v1.1.8

3. 确认imagePullPolicy配置已生效 #

你使用的extensions/v1beta1是已废弃多年的API版本，在1.16及以上K8s版本中可能存在配置解析异常，导致imagePullPolicy: Never未生效：

• 先验证当前生效的Deployment配置：kubectl get deployment nginx-custom -o yaml | grep imagePullPolicy
• 如果输出不是Never，将Deployment的API版本升级为apps/v1后重新apply：

# 修正后的Deployment配置示例
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-custom
  namespace: default
spec:
  selector:
    matchLabels:
      run: nginx-custom
  replicas: 5 
  template:
    metadata:
      labels:
        run: nginx-custom
    spec:
      containers:
      - image: myprivatehub.com/nginx/nginx-custom:v1.1.8
        imagePullPolicy: Never
        name: nginx-custom
        ports:
        - containerPort: 80

• 重新apply后删除旧Pod触发重建：kubectl delete pod -l run=nginx-custom

4. 特殊场景排查 #

如果以上步骤都未解决，检查单节点是否开启了强制镜像拉取的准入控制器，或者kubelet是否配置了--always-pull-images启动参数，单节点默认部署不会开启此类配置，可通过ps aux | grep kubelet查看启动参数确认。

内容的提问来源于stack exchange，提问作者Mozhi