Proxy cache isn't tagging images

Products

• VMware Tanzu Kubernetes Grid Integrated Edition

Issue/Introduction

When using a Harbor Proxy Cache repository configured to proxy docker.io, users may notice that certain images—specifically official Docker images (e.g., docker.io/library/httpd)—do not appear with their expected tags in the Harbor UI after being pulled.

This issue primarily arises when the image is copied using Skopeo, which skips the HEAD request needed for Harbor to properly associate the tag.

Environment

Harbor below 2.15

Cause

When Skopeo is used to copy an image, it does not send a HEAD request for the tag to the source registry (docker.io). Harbor's proxy caching mechanism depends on the HEAD request to create the tag reference for proxied content.

Since official images from Docker Hub (those under the implicit library namespace) rely on tag resolution via such requests, the absence of HEAD means the tag isn't registered in Harbor, even though the image content is cached.

Resolution

In future versions, Harbor Proxy will push a manifest referencing a digest and tag to the local repo if both are known. The fix will be included in Harbor version 2.15, which is expected to be released before the end of year 2025.

In the meantime, these are possible workarounds.

• Use docker pull instead of Skopeo, which includes the appropriate HEAD request:

E.g docker pull ${HARBOR_URL}/docker.io/library/httpd:2.4.41

• Alternatively, manually trigger a HEAD request (e.g., via curl) for the tag before or after the Skopeo copy operation:

curl -I -H "Authorization: Bearer <token>" \
  https://${HARBOR_URL}/v2/docker.io/library/httpd/manifests/2.4.41

(Ensure token has appropriate scope or use Harbor's API directly if accessible)

Additional Information

Git related issues and PR

https://github.com/goharbor/harbor/issues/21122

https://github.com/goharbor/harbor/pull/21141