K3s集群拉取Harbor私有仓库镜像报ImagePullBackOff如何解决

• 核心配置不兼容：K3s默认使用containerd作为容器运行时，不会读取Docker的/etc/docker/daemon.json配置。你修改Docker配置的操作仅对Docker客户端本身生效，K3s的kubelet调用containerd拉取镜像时完全不会加载该规则，无法识别你的Harbor实例为非安全仓库，直接发起HTTPS校验时就会连接失败。
• 现有Docker配置格式错误：insecure-registries字段要求为数组类型，你当前配置为字符串格式，即使节点使用Docker作为运行时，该配置也无法正常生效。
• 潜在拼写错误：Pod配置中镜像地址写为my-harbor-server/my-project/mayapp:v1.0，镜像名mayapp与容器名myapp不一致，存在手滑打错镜像名、导致Harbor中不存在对应镜像的可能。

• 配置K3s全局私有仓库规则：在所有K3s节点（包括Server控制节点和Agent工作节点）创建或修改/etc/rancher/k3s/registries.yaml文件，写入以下配置（根据你的Harbor部署协议调整endpoint）：

mirrors:
  "my-harbor-server:443":
    endpoint:
      - "https://my-harbor-server:443" # HTTP部署就替换为http://开头的地址
configs:
  "my-harbor-server:443":
    tls:
      insecure_skip_verify: true # HTTP部署/使用自签名证书时开启，跳过TLS证书校验

如果你希望全局配置拉取凭证，也可以在configs下添加auth字段填写Harbor账号密码，就不需要每个命名空间单独创建imagePullSecret；如果保留现有Secret方式，可不配置auth段。

• 重启K3s服务加载配置：所有Server节点执行systemctl restart k3s，所有Agent节点执行systemctl restart k3s-agent，等待1-2分钟服务恢复。
• 修正Docker配置（如果节点需要用Docker推拉镜像）：修改/etc/docker/daemon.json为正确格式，之后执行systemctl restart docker重启Docker：

{
  "insecure-registries" : ["my-harbor-server:443"]
}

• 校验配置正确性：
  1. 执行crictl info | grep -A 15 my-harbor-server，确认返回结果中能看到你配置的insecure_skip_verify为true，说明containerd已加载仓库规则。
  2. 核对Harbor控制台中镜像的完整路径、标签，确认和Pod yaml中写的image字段完全一致，修正可能存在的拼写错误。
  3. 执行kubectl get secret regcred -n <Pod所在命名空间>，确认拉取凭证Secret和Pod在同一个命名空间，跨命名空间的Secret无法被引用。
• 重新创建Pod：删除之前创建失败的Pod，重新执行kubectl apply -f pod.yml即可正常拉取镜像。

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