Kubernetes从Nexus3私有镜像仓库拉取镜像失败问题排查求助

我来帮你一步步排查和解决这个问题——咱们先从验证你创建的Secret有效性开始，再逐步定位镜像拉取失败的核心原因。

一、验证私有仓库Secret的有效性 #

首先得确认你创建的Secret确实能正常用于仓库认证：

1. 检查Secret的基本信息
   运行命令查看Secret的类型和结构，确保是kubernetes.io/dockerconfigjson类型（这是Docker私有仓库认证的标准类型）：

kubectl get secret <你的Secret名称> -o yaml

重点看两个地方：

• type字段是不是kubernetes.io/dockerconfigjson
• data.dockerconfigjson有没有值（是base64编码的认证信息）

你还可以解码这个字段，查看实际的认证内容是否正确：

echo "<yaml里的dockerconfigjson值>" | base64 -d

解码后应该能看到类似这样的结构，其中serveraddress要和你的Nexus仓库地址完全一致，auth是用户名密码的base64编码：

{
  "auths": {
    "nexus3provaterepo:port": {
      "auth": "xxxxxxxxx",
      "email": "xxx@xxx.com"
    }
  }
}

2. 用临时Pod测试Secret的可用性
   创建一个临时Pod，挂载你的Secret，然后直接在Pod里测试仓库连接：

apiVersion: v1
kind: Pod
metadata:
  name: test-secret-pod
spec:
  containers:
  - name: test-container
    image: busybox:latest
    command: ["sleep", "3600"]
  imagePullSecrets:
  - name: <你的Secret名称>

创建Pod后，进入Pod的终端：

kubectl exec -it test-secret-pod -- sh

在Pod里用curl测试仓库的镜像列表（替换成你的仓库地址、用户名和密码）：

curl -u <用户名>:<密码> http://nexus3provaterepo:port/v2/_catalog

如果能返回仓库里的镜像列表，说明Secret和仓库连接是正常的；如果返回401 Unauthorized，那就是用户名密码或者权限配置有问题。

二、排查镜像拉取失败的常见原因 #

如果Secret没问题，那就要检查K8s部署配置和环境的问题了：

1. 确认Pod/Deployment配置了imagePullSecrets
   你用kubectl run创建部署的时候，有没有加上--image-pull-secrets参数？默认情况下，K8s不会自动使用你创建的Secret，必须显式指定：

kubectl run deployname --image=nexus3provaterepo:port/image:tag --image-pull-secrets=<你的Secret名称>

如果是已经创建的Deployment，你可以编辑它加上imagePullSecrets：

kubectl edit deployment deployname

在spec.template.spec下添加：

imagePullSecrets:
- name: <你的Secret名称>

2. 检查镜像地址的正确性

• 确保镜像地址包含完整的tag（比如:latest或者具体版本号），如果没写tag，K8s会默认拉取latest，但你的Nexus仓库里可能没有这个tag的镜像。
• 尝试用IP代替域名（比如192.168.1.100:8082/image:tag），避免K8s节点的DNS解析问题。

3. 检查Nexus仓库的用户权限
   登录Nexus控制台，确认你用来认证的用户有该镜像仓库的读取权限：

• 进入Nexus的「Security」→「Roles」，查看该用户所属角色的权限，确保包含nx-repository-view-<仓库类型>-<仓库名>-read（比如nx-repository-view-docker-myrepo-read）。

4. 检查K8s节点的镜像运行时配置
   如果你的K8s集群用的是containerd而不是Docker，那只配置Docker的daemon.json是没用的，需要给containerd配置私有仓库认证：

• 编辑节点上的/etc/containerd/config.toml，在[plugins."io.containerd.grpc.v1.cri".registry.mirrors]下添加你的Nexus仓库配置，同时在[plugins."io.containerd.grpc.v1.cri".registry.configs]里配置认证信息。
• 重启containerd服务：systemctl restart containerd

5. 查看Pod的事件日志获取具体错误
   这是最关键的一步——通过Pod的事件信息，你能直接看到镜像拉取失败的具体原因：

kubectl describe pod <失败的Pod名称>

在输出的Events部分，你会看到类似这样的错误：

• Failed to pull image "xxx": rpc error: code = Unknown desc = unauthorized: authentication required：说明Secret没生效或者认证失败
• Failed to pull image "xxx": rpc error: code = Unknown desc = failed to resolve image "nexus3provaterepo:port/image": no available registry endpoint：说明节点连不上Nexus仓库，检查网络或者防火墙

三、总结解决步骤 #

1. 验证Secret的类型和内容是否正确，确保能通过Secret正常访问Nexus仓库。
2. 确保Deployment/Pod显式配置了imagePullSecrets，指向正确的Secret。
3. 检查镜像地址的完整性（域名/IP、端口、tag），避免DNS或镜像不存在的问题。
4. 确认Nexus用户有镜像的读取权限。
5. 根据Pod事件的具体错误信息，针对性修复（比如网络问题、运行时配置问题）。

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