使用Helm部署自定义Grafana镜像失败，寻求故障排查建议

报错信息 #

Failed to pull image "my-registry/grafana:9.4.1": rpc error: code = Unknown desc = failed to pull and unpack image "docker.io/my-registry/grafana:9.4.1": failed to resolve reference "docker.io/my-registry/grafana:9.4.1": pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed

当前配置 #

repository: my-registry/grafana
#Overrides the Grafana image tag whose default is the chart appVersion 
 tag: "9.4.1" 
 sha: ""
 pullPolicy: IfNotPresent
#Optionally specify an array of imagePullSecrets.
 #Secrets must be manually created in the namespace.
 #ref: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/
 #Can be templated.
 #pullSecrets:
 #- myRegistrKeySecretName
imagePullSecrets:
-name: secretname

可能的原因及解决方法 #

• 镜像仓库地址不完整：报错中显示Kubernetes自动给镜像地址添加了docker.io/前缀，说明你的repository字段未填写私有仓库的完整域名。比如私有仓库地址是my-registry.com，应配置为my-registry.com/grafana，否则Kubernetes会默认去Docker Hub查找该仓库，导致找不到资源。

• YAML配置格式错误：imagePullSecrets的列表项格式不符合YAML规范，正确写法需保证缩进层级正确，且-后有空格：

  imagePullSecrets:
    - name: secretname
  

• Secret本身无效：

  • 确认Secret是通过正确命令创建的，需指定私有仓库地址、用户名、密码：

    kubectl create secret docker-registry secretname --docker-server=<私有仓库地址> --docker-username=<用户名> --docker-password=<密码> --docker-email=<邮箱>
    

  • 确认Secret与Grafana Pod处于同一命名空间，Kubernetes不支持跨命名空间引用Secret。
  • 解密检查Secret内容是否正确：

    kubectl get secret secretname -o jsonpath='{.data.dockerconfigjson}' | base64 -d
    

    验证输出中的仓库地址、账号信息是否与实际一致。

• 仓库权限不足：确认用于拉取镜像的账号，对my-registry/grafana:9.4.1镜像拥有明确的拉取权限，部分场景下即使Secret配置正确，账号权限不足也会触发insufficient_scope错误。

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