k3s集群无法拉取GitLab镜像仓库镜像的问题求助

以下是可能导致Pod无法拉取GitLab私有镜像的几个常见原因及排查方法：

1. Docker Registry Secret的Server地址格式错误 #

创建secret时指定的--docker-server参数不需要带https://前缀，Kubernetes容器运行时（如containerd）无法识别带协议头的仓库地址。

• 排查方法：解码secret查看内容：

  kubectl get secret regcred -n default -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d
  

  检查auths下的地址是否为gitlab.domain.tld:5050（而非带https的格式）。如果错误，重新创建secret：

  kubectl delete secret regcred -n default
  kubectl create secret docker-registry regcred --docker-server=gitlab.domain.tld:5050 --docker-username=USERNAME --docker-email=EMAIL --docker-password=TOKEN
  

2. GitLab令牌权限不足 #

确保使用的TOKEN具备镜像仓库的拉取权限：

• 如果是个人访问令牌：需在GitLab中勾选read_registry权限；
• 如果是项目/组令牌：需确保令牌关联的角色（如Reporter以上）拥有目标镜像仓库的拉取权限；
• 可直接用该TOKEN在本地测试验证：

  docker login gitlab.domain.tld:5050 -u USERNAME -p TOKEN
  docker pull gitlab.domain.tld:5050/group/appproject:1.0
  

3. Containerd未配置私有仓库信任（自签证书场景） #

如果GitLab镜像仓库使用自签SSL证书，k3s默认的containerd可能未信任该证书，部分场景下会表现为403权限错误：

• 排查方法：检查节点上的containerd配置文件/var/lib/rancher/k3s/agent/etc/containerd/config.toml，确认是否添加了该仓库的TLS配置：

  [plugins."io.containerd.grpc.v1.cri".registry.configs."gitlab.domain.tld:5050".tls]
    ca_file = "/path/to/ca.crt"
  

  测试环境下若允许不安全访问，可添加：

  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."gitlab.domain.tld:5050"]
    endpoint = ["https://gitlab.domain.tld:5050"]
  [plugins."io.containerd.grpc.v1.cri".registry.configs."gitlab.domain.tld:5050".tls]
    insecure_skip_verify = true
  

  修改后重启k3s agent：systemctl restart k3s-agent

4. Secret与Deployment的Namespace不匹配 #

虽然你提到都在default命名空间，仍需确认secret确实存在于目标Namespace：

kubectl get secrets -n default | grep regcred

如果不存在，重新在default命名空间创建secret。

5. 镜像地址拼写错误 #

确认Deployment中的镜像地址gitlab.domain.tld:5050/group/appproject:1.0与本地拉取的完全一致，注意路径大小写、端口号、标签是否正确。

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