K8S 拉取镜像失败的解决办法

  1. 参考
  2. 镜像地址
  3. 个人解决方案
  4. DeepSeek回答

参考

镜像地址

# docker.io
用渡渡鸟或者华为云镜像
DockerHub 镜像仓库  是否正常
docker.m.daocloud.io  正常
## swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/vllm/vllm-openai:latest  
swr.cn-north-4.myhuaweicloud.com/ddn-k8s/
ccr.ccs.tencentyun.com  正常
docker.1ms.run  正常
hub.xdark.top  正常
dhub.kubesre.xyz  正常
docker.kejilion.pro  正常
docker.xuanyuan.me  正常
docker.hlmirror.com  正常
run-docker.cn  正常
docker.sunzishaokao.com  正常
image.cloudlayer.icu  正常
docker-0.unsee.tech  正常
docker.tbedu.top  正常
hub.crdz.gq  正常
docker.melikeme.cn  正常

# registry.k8s.io / k8s.grc.io https://k8s.dockerproxy.net https://k8s.linkos.org https://registry.aliyuncs.com/google_containers
# gcr.io https://gcr.linkos.org
# ghcr.io8 https://ghcr.linkos.org
# quay.io https://quay.linkos.org

个人解决方案

我将containerd的源进行了重定向,可以正常进行拉取,当时发现有sendbox无法create的问题,还在排查

dockerproxy.net 这个拉镜像挺方便的

version = 2
root = "/var/lib/containerd"
state = "/run/containerd"

[grpc] address = "/run/containerd/containerd.sock"
[plugins] [plugins."io.containerd.grpc.v1.cri"] disable = false sandbox_image = "sealos.hub:5000/pause:3.7"
[plugins."io.containerd.grpc.v1.cri".containerd] snapshotter = "overlayfs" default_runtime_name = "runc"
[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc] runtime_type = "io.containerd.runc.v2" [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options] SystemdCgroup = true
[plugins."io.containerd.grpc.v1.cri".registry] [plugins."io.containerd.grpc.v1.cri".registry.mirrors] [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"] endpoint = ["https://dockerproxy.net"] # 替换为网易、阿里云等 Docker Hub 镜像 [plugins."io.containerd.grpc.v1.cri".registry.mirrors."k8s.gcr.io"] endpoint = ["https://registry.aliyuncs.com/google_containers"] # 替换为阿里云地址 [plugins."io.containerd.grpc.v1.cri".registry.mirrors."registry.k8s.io"] endpoint = ["https://k8s.dockerproxy.net"] # 替换为阿里云地址 [plugins."io.containerd.grpc.v1.cri".registry.mirrors."gcr.io"] endpoint = ["https://gcr-mirror.qiniu.com"] # 替换为中科大 gcr 镜像 [plugins."io.containerd.grpc.v1.cri".registry.mirrors."quay.io"] endpoint = ["https://quay-mirror.qiniu.com"] # 替换为中科大 quay 镜像

DeepSeek回答

好的,这个问题在 Kubernetes 环境中非常常见,尤其是在国内网络环境下。我们来一步步拆解:

1. 为什么镜像地址会不一样?不应该都是在 docker.io 上拉取吗?

  • Docker Hub (docker.io) 只是一个公共仓库: 它是最大的、最流行的公共容器镜像注册中心,很多开源项目和个人镜像都托管在这里。当你看到 nginx, redis, mysql 等镜像名时,默认就是从 docker.io/library/nginx 等路径拉取的(library 是官方镜像的命名空间)。
  • 其他组织/公司有自己的镜像仓库:
    • k8s.gcr.io** (老地址是 gcr.io/google-containers):** *这是 Google Container Registry (GCR) 上专门存放 Kubernetes 核心组件(如 kube-apiserver, kube-controller-manager, kube-scheduler, kube-proxy, etcd, coredns, pause 等)官方镜像的地址。* Kubernetes 项目由 Google 发起并深度参与,这些官方组件的镜像自然托管在 Google 的仓库里。注意:k8s.io** 通常重定向到 ****k8s.gcr.io**,本质是同一个东西。 现在官方推荐使用 registry.k8s.io 作为新地址(但背后映射关系可能变化,国内访问问题依旧)。
    • **quay.io**: 这是另一个非常流行的公共容器镜像注册中心,由 CoreOS(后被 Red Hat 收购,现属 IBM)运营。许多云原生项目(如 Prometheus, Grafana, Operator Framework 相关项目等)选择将镜像托管在这里。例如 quay.io/prometheus/prometheus。
    • **gcr.io**: 这是 Google Container Registry 的通用地址,除了 Kubernetes 镜像,Google 的其他服务和项目(如 Google Cloud SDK 镜像、TensorFlow 官方镜像等)也放在这里。
    • registry.gitlab.com** / ****ghcr.io**: GitLab 和 GitHub 也提供自己的容器镜像仓库服务,供托管在它们平台上的项目使用。
    • 私有仓库: 企业内部通常搭建自己的私有镜像仓库(如 Harbor, Nexus, JFrog Artifactory, AWS ECR, GCP GCR, Azure ACR 等),地址就是公司内部的域名或云服务商提供的地址(如 mycompany-registry.example.com, 123456789012.dkr.ecr.us-east-1.amazonaws.com)。
  • 结论: 镜像地址不同,是因为镜像的所有者/维护者选择了不同的容器镜像注册中心(Registry) 来存储和分发他们的镜像。Docker Hub (docker.io) 只是众多注册中心中的一个,虽然最大最通用,但绝非唯一。

2. 常见的镜像仓库地址有哪些?

  • docker.io** / ****index.docker.io**: Docker Hub (公共/私有)
  • registry.k8s.io** / k8s.gcr.io (逐步淘汰中):** Kubernetes 官方组件镜像 (本质在 Google Cloud 上)
  • **gcr.io**: Google Container Registry (Google 服务/项目相关镜像)
  • **quay.io**: Quay.io (CoreOS/Red Hat/IBM 相关及许多云原生项目镜像)
  • **ghcr.io**: GitHub Container Registry
  • **registry.gitlab.com**: GitLab Container Registry
  • **nvcr.io**: NVIDIA GPU Cloud Registry (NVIDIA GPU 相关镜像)
  • **mcr.microsoft.com**: Microsoft Container Registry (微软相关镜像,如 .NET, Azure 服务)
  • 各种云厂商的仓库:
    • AWS: <account-id>.dkr.ecr.<region>.amazonaws.com
    • GCP: gcr.io/<project-id>, us.gcr.io/<project-id> (区域级), eu.gcr.io/<project-id> 等
    • Azure: <registry-name>.azurecr.io
  • 私有仓库地址: your.private.registry:5000 (常见端口,可自定义) 或企业自定义域名。

**3. 国内环境怎么解决访问问题?(特别是 registry.k8s.io/k8s.gcr.io, quay.io, ****gcr.io**)

由于网络限制,国内直接访问 registry.k8s.io/k8s.gcr.io, quay.io, gcr.io 等仓库通常非常慢甚至完全不可用。有几种主要解决方案:

方案一:使用国内镜像仓库作为代理/缓存(最常用、最推荐)

  • 原理: 国内云服务商或组织维护的镜像仓库会定期(或按需)同步国外热门仓库(尤其是 registry.k8s.io)的镜像。你只需将 k8s.gcr.io/some/image:tag 替换成 国内仓库地址/google_containers/some/image:tag 即可。

  • 常用国内镜像源:

    • 阿里云: registry.aliyuncs.com/google_containers (同步 registry.k8s.io/k8s.gcr.io)
      • 例如:k8s.gcr.io/kube-apiserver:v1.27.3 -> registry.aliyuncs.com/google_containers/kube-apiserver:v1.27.3
    • 微软中国 (Azure China): mcr.azk8s.cn (包含 docker.io, gcr.io, quay.io 等常用库的缓存)
      • 例如:k8s.gcr.io/pause:3.6 -> mcr.azk8s.cn/k8s/core/pause:3.6 (路径可能需查证或尝试)
    • 中科大镜像站: quay-mirror.qiniu.com (同步 quay.io), gcr-mirror.qiniu.com (同步 gcr.io 和 k8s.gcr.io), docker-mirror.qiniu.com (同步 docker.io)
      • 例如:quay.io/prometheus/prometheus:v2.37.0 -> quay-mirror.qiniu.com/prometheus/prometheus:v2.37.0
    • 网易云: hub-mirror.c.163.com (主要同步 docker.io)
    • DaoCloud: f1361db2.m.daocloud.io (提供多个仓库的加速)
  • 如何使用:

    1. 手动替换: 在 Pod YAML 或 Deployment YAML 的 image 字段中直接使用国内镜像地址。

    2. kubeadm** 初始化/升级:** 使用 --image-repository 参数指定国内仓库地址:

      kubeadm init --image-repository=registry.aliyuncs.com/google_containers ...
      kubeadm upgrade node --image-repository=registry.aliyuncs.com/google_containers ...
      
    3. 修改 containerd/Docker 配置 (全局代理): 配置容器运行时,将所有对 k8s.gcr.io 的请求重定向到国内镜像源。以 containerd 为例 (/etc/containerd/config.toml):

      [plugins."io.containerd.grpc.v1.cri".registry]
        [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
          [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
            endpoint = ["https://dockerproxy.net"] # 替换为网易、阿里云等 Docker Hub 镜像
          [plugins."io.containerd.grpc.v1.cri".registry.mirrors."k8s.gcr.io"]
            endpoint = ["https://registry.aliyuncs.com/google_containers"] # 替换为阿里云地址
          [plugins."io.containerd.grpc.v1.cri".registry.mirrors."gcr.io"]
            endpoint = ["https://gcr-mirror.qiniu.com"] # 替换为中科大 gcr 镜像
          [plugins."io.containerd.grpc.v1.cri".registry.mirrors."quay.io"]
            endpoint = ["https://quay-mirror.qiniu.com"] # 替换为中科大 quay 镜像
      

      修改后重启 containerd (systemctl restart containerd)。Docker 也有类似配置 (/etc/docker/daemon.json 中的 registry-mirrors 和 insecure-registries 对于非 HTTPS 仓库)。

  • 优点: 速度快,稳定,配置相对简单(尤其手动替换和 kubeadm 参数)。

  • 缺点: 镜像同步可能有延迟;需要查找或知道对应关系;部分小众镜像可能未被同步。

方案二:搭建私有代理仓库(如 Harbor)

  • 原理: 在企业内部搭建 Harbor 等私有仓库。配置 Harbor 的代理缓存功能(Registry Proxy Cache),让它去拉取国外的镜像并缓存下来。Kubernetes 节点直接从 Harbor 拉取。
  • 步骤:
    1. 部署 Harbor。
    2. 在 Harbor 中创建代理缓存项目,配置上游仓库地址 (如 https://k8s.gcr.io, https://quay.io)。
    3. 将 Kubernetes 节点上容器运行时的 registry 配置指向 Harbor。
    4. 在 Pod YAML 中使用 Harbor 项目中的镜像地址 (如 my-harbor.com/proxy-cache-project/k8s.gcr.io/kube-apiserver:v1.27.3)。
  • 优点: 完全自控,缓存效率高,适合企业级环境,可以代理任意仓库。
  • 缺点: 部署和维护 Harbor 需要额外成本;需要配置节点指向 Harbor。

方案三:HTTP/HTTPS 代理

  • 原理: 为 Kubernetes 节点(更准确地说,是为节点上的 kubelet 和容器运行时 Docker/containerd)配置网络代理,使其通过代理服务器访问国外镜像仓库。

  • 如何配置:

    • Docker: 在 /etc/systemd/system/docker.service.d/http-proxy.conf 中设置环境变量:

      [Service]
      Environment="HTTP_PROXY=http://proxy-ip:port"
      Environment="HTTPS_PROXY=http://proxy-ip:port" # 如果代理支持 HTTPS 流量也用这个
      Environment="NO_PROXY=localhost,127.0.0.1,.internal-domain,.svc,.cluster.local"
      

      重启 Docker (systemctl daemon-reload && systemctl restart docker)。

    • containerd: containerd 不直接读取系统环境变量。需要在它的启动环境文件 (如 /etc/environment) 或 systemd service 文件 (/etc/systemd/system/containerd.service.d/http-proxy.conf) 中设置 HTTP_PROXY, HTTPS_PROXY, NO_PROXY 环境变量,并确保 containerd 服务能继承它们。重启 containerd。

    • kubelet: 理论上也需要设置代理,但通常配置容器运行时代理后,kubelet 拉取镜像的行为就由运行时通过代理完成了。如果 kubelet 需要直接访问外部(如云提供商 API),可能也需要单独配置代理(通过 /etc/systemd/system/kubelet.service.d/http-proxy.conf)。

  • 优点: 可以访问所有国外仓库,无需修改镜像地址。

  • 缺点:

    • 配置相对复杂且分散(Docker/containerd/kubelet)。
    • 需要稳定、可靠的代理服务器(且能访问目标仓库),代理本身也可能成为瓶颈或单点故障。
    • 代理的认证、安全、带宽管理需要额外考虑。
    • 容器内应用如果需要访问外部网络,也会走这个代理(除非在 Pod 级别单独配置),这可能不是期望的行为。

方案四:拉取镜像后推送到私有仓库

  • 原理: 在一台能访问国外仓库的机器上(如个人开发机、跳板机、海外虚拟机),用 docker pull 拉取所需镜像,然后用 docker tag 打上私有仓库的标签,再用 docker push 推送到企业内部可访问的私有仓库(Harbor, ECR, ACR 等)。最后修改 Kubernetes YAML 使用私有仓库地址。
  • 优点: 完全可控,镜像存在于私有仓库,拉取速度快。
  • 缺点: 操作繁琐,需要人工或额外脚本维护同步,不适合频繁更新或大量镜像的场景。

4. 对应到镜像仓库该怎么解决?

  • registry.k8s.io/k8s.gcr.io** (K8s 官方镜像):** 首选方案一(国内镜像源替换),尤其是阿里云的 registry.aliyuncs.com/google_containers。方案二(私有代理 Harbor)也是企业好选择。kubeadm --image-repository 非常方便。
  • **quay.io**: **方案一(国内镜像源如中科大 ****quay-mirror.qiniu.com**)。方案二(Harbor 代理)或方案四(手动拉取推送)。
  • gcr.io** (其他 Google 镜像):** **方案一(国内镜像源如中科大 ****gcr-mirror.qiniu.com**)。方案二(Harbor 代理)或方案四(手动拉取推送)。
  • docker.io** (Docker Hub):** 方案一(配置 Docker/containerd 的 registry mirror 使用网易 hub-mirror.c.163.com 或阿里云 <your-id>.mirror.aliyuncs.com 等)。这是最通用、最有效的加速 Docker Hub 的方式。方案三(代理)也可行,但通常不如镜像加速器稳定高效。
  • 其他小众仓库: 方案二(Harbor 代理)最通用。方案三(代理)次之。方案四(手动)作为临时手段。

5. 有代理访问的方式吗?

有。就是上面提到的方案三(HTTP/HTTPS 代理)。

  • 核心: 在运行容器引擎(Docker/containerd)的 Kubernetes 节点上,设置 HTTP_PROXY 和 HTTPS_PROXY 环境变量,并确保这些变量被容器引擎的服务正确加载(通过 systemd drop-in 文件或环境文件)。
  • 关键点:
    • 代理服务器本身需要能访问目标镜像仓库 (k8s.gcr.io, quay.io 等)。
    • 正确配置 NO_PROXY 以避免内部网络流量(如访问 apiserver, etcd, 集群内部服务 .svc, .cluster.local)也被发送到代理,这会导致严重问题。
    • Kubelet 可能也需要代理: 虽然容器运行时拉镜像是主要问题,但如果 kubelet 自身需要访问外网(如 cloud provider 集成),也需单独配置其代理。

总结与推荐:

  • 对于国内个人和小团队: 优先使用国内镜像源替换(方案一)。配置 Docker/containerd 的 registry-mirrors 加速 docker.io。使用阿里云、中科大等地址替换 k8s.gcr.io, quay.io 的镜像地址。这是最简单、最快速、最稳定的方案。
  • 对于国内企业:
    • 强烈推荐搭建 Harbor(方案二) 并配置代理缓存功能。统一管理所有镜像(包括国外代理过来的和私有的),安全性、可控性、缓存效率最高。
    • 同时可以**配置容器运行时的 registry mirrors 加速 ****docker.io**。
  • HTTP 代理(方案三): 可以作为备选方案,或在已有稳定企业代理的情况下使用。但配置相对复杂,且可能引入额外依赖和问题。
  • 手动推送(方案四): 适用于临时解决少量特定镜像或无法使用其他方案的情况。
    选择哪种方案取决于你的具体环境、团队规模、技术能力和需求。对于绝大多数国内 Kubernetes 用户,国内镜像源替换和自建 Harbor 代理缓存是解决国外镜像拉取问题的最主流和最有效的实践。

转载请注明来源,欢迎对文章中的引用来源进行考证,欢迎指出任何有错误或不够清晰的表达。可以在下面评论区评论,也可以邮件至 365433079@qq.com