使用k3d本地私有仓库拉取Docker镜像失败求助

问题根源 #

Pod 内部的 localhost 指向容器自身，而非 k3d registry 容器；同时镜像引用地址与集群内部 registry 访问地址不匹配，导致 kubelet 无法建立连接。

修复操作步骤 #

1. 修正镜像标签与推送地址 #

宿主机推送镜像时，需使用集群内部可识别的 registry 域名：

# 重新打标签
docker tag nginx:latest k3d-registry.localhost:8087/nginx:latest
# 重新推送镜像
docker push k3d-registry.localhost:8087/nginx:latest

2. 更新 Pod 配置的镜像地址 #

将你的 Deployment/Pod YAML 中的镜像地址改为 k3d-registry.localhost:8087/nginx:latest，替换原来的 localhost:8087/nginx:latest。

3. 验证集群内部 registry 连通性 #

进入集群节点容器测试网络：

# 列出集群节点
k3d node list
# 进入节点容器（替换为实际节点名，如k3d-dev-server-0）
docker exec -it k3d-dev-server-0 sh
# 测试registry可达性
curl http://k3d-registry.localhost:8087/v2/

返回空JSON {} 即为连通正常。

4. 调整 registry.yaml 配置 #

确保镜像加速配置的镜像名与内部地址一致：

mirrors:
  'k3d-registry.localhost:8087':
    endpoint:
      - http://k3d-registry.localhost:8087

此配置让 containerd 在拉取该域名镜像时直接访问内部地址。

5. 重建集群（若上述操作无效） #

删除现有集群后重新创建：

k3d cluster delete dev
k3d cluster create dev -p "8000:80@loadbalancer" --registry-use k3d-registry.localhost:8087 --registry-config registry.yaml

关键说明 #

k3d 创建的 registry 容器在集群内部的域名是 k3d-registry.localhost，宿主机通过端口映射可用 localhost:8087 访问，但集群内的 Pod/节点必须使用内部域名才能正确解析。

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