如何配置Containerd对接Harbor代理缓存仓库的指定端点

我正在搭建Kubernetes集群，使用containerd作为容器运行时。已配置Harbor仓库的代理缓存项目kubernetes-cache，用于缓存外部仓库registry.k8s.io的镜像，Harbor实例地址为https://harbor.private.com。

尝试通过该配置拉取镜像时遇到问题：直接拉取registry.k8s.io/kube-proxy:v1.26.5会返回400 Bad Request错误，请求路径为/v2/proxy.kubernetes-cache/，但使用docker pull harbor.private.com/kubernetes-cache/kube-proxy:v1.26.5可正常拉取。containerd错误日志如下：

level=error msg="PullImage \"registry.k8s.io/kube-proxy:v1.26.5\" failed" error="failed to pull and unpack image \"registry.k8s.io/kube-proxy:v1.26.5\": failed to resolve reference \"registry.k8s.io/kube-proxy:v1.26.5\": pulling from host harbor.private.com failed with status code [manifests v1.26.5]: 400 Bad Request"

当前containerd的仓库端点配置如下：

[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."registry.k8s.io"]
          endpoint = ["https://harbor.private.com/kubernetes-cache"]

我的问题如下：

1. 此场景下仓库端点的正确格式是什么？是否需要包含项目名kubernetes-cache，还是仅使用Harbor实例的基础URL？
2. 拉取请求需采用何种特定格式才能与Harbor代理缓存兼容？例如，镜像名称是否需要包含项目名或额外路径？
3. 是否需要在containerd或Harbor中进行额外配置，以确保请求被正确路由并被Harbor识别？

1. 仓库端点的正确格式 #

不能将项目名kubernetes-cache直接写入endpoint。正确的endpoint应为Harbor的基础URLhttps://harbor.private.com，代理缓存项目的映射需通过镜像重写规则实现。

当前配置会让containerd生成错误的请求路径：https://harbor.private.com/kubernetes-cache/v2/registry.k8s.io/kube-proxy/manifests/v1.26.5，这不符合Harbor代理缓存的请求规范，因此触发400错误。

2. 拉取请求的兼容格式 #

配置正确后，依然可以使用原镜像名registry.k8s.io/kube-proxy:v1.26.5直接拉取，无需修改镜像名称格式。containerd会通过重写规则自动将请求转换为Harbor代理缓存可识别的路径。

手动拉取的兼容格式为harbor.private.com/kubernetes-cache/kube-proxy:v1.26.5，即你之前测试成功的格式。

3. 必要的额外配置 #

需修改containerd配置，添加镜像重写规则，具体步骤如下：

1. 编辑containerd配置文件（通常路径为/etc/containerd/config.toml）：

[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."registry.k8s.io"]
    endpoint = ["https://harbor.private.com"]

# 若Harbor开启认证，添加以下配置（无需认证则可省略）
[plugins."io.containerd.grpc.v1.cri".registry.configs]
  [plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.private.com".auth]
    username = "your-harbor-username"
    password = "your-harbor-password"

# 添加镜像重写规则，将原镜像路径映射到Harbor代理缓存项目
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."registry.k8s.io".rewrite]
  pattern = "^(.*)$"
  replacement = "kubernetes-cache/$1"

2. 重启containerd服务：

systemctl restart containerd

3. 验证配置：
   尝试拉取原镜像名，检查containerd日志是否正常，或查看Harbor的kubernetes-cache项目是否已缓存目标镜像。

关键原理 #

Harbor代理缓存项目要求请求路径为/v2/<project-name>/<image-path>/manifests/<tag>，而containerd默认会将原镜像名直接拼接在endpoint后。通过添加重写规则，我们将registry.k8s.io/kube-proxy转换为kubernetes-cache/kube-proxy，确保请求被Harbor正确路由到代理缓存项目，完成镜像拉取与缓存。

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