Proxy cache endpoint health check fails for registry.istio.io

[kesslerdev]

Expected behavior and actual behavior

Expected behavior

Harbor should successfully validate https://registry.istio.io as a generic Docker Registry endpoint when no credentials are configured.

The registry hosts publicly accessible images. For example, the following anonymous pull succeeds:

docker pull registry.istio.io/release/proxyv2:1.26.4

Consequently, Harbor should:

• consider the endpoint healthy;
• allow it to be registered as a remote registry;
• allow the endpoint to be used by a proxy cache project.

Actual behavior

Harbor rejects the registry endpoint as unhealthy:

{"errors":[{"code":"BAD_REQUEST","message":"the registry is unhealthy"}]}

The Harbor core logs contain:

 [/pkg/reg/adapter/native/adapter.go:126]: failed to ping registry https://registry.istio.io: http status code: 400, body: {"error":"scope is required"}

Steps to reproduce the problem

Prerequisites

• A Harbor instance with administrator access
• Outbound HTTPS access from harbor-core to registry.istio.io
• No credentials configured for the remote registry
• Docker, Podman, crane, or another OCI client

Verify that the image is publicly pullable

docker logout registry.istio.io 2>/dev/null || true
docker pull registry.istio.io/release/proxyv2:1.26.4

Expected result:

1.26.4: Pulling from release/proxyv2
...
Status: Downloaded newer image for registry.istio.io/release/proxyv2:1.26.4

Reproduce the failure through the Harbor UI

In the Harbor administration interface:

• Open Administration → Registries.
• Select New Endpoint.
• Select Docker Registry as the provider.
• Enter a name such as istio.
• Enter: https://registry.istio.io
• Leave Access ID and Access Secret empty.
• Click Test Connection or save the endpoint.

Observed result:

The registry is unhealthy

Versions:

• harbor version: 2.14.3
• docker engine version: 28.5.1

[Jeansen]

Same here, Version v2.15.1-335c05f2

[chlins]

Harbor marks registry.istio.io as unhealthy because its bearer token request has no scope, and istio's token service rejects that with 400 scope is required.

The chain is:

1. No credentials → HealthCheck() calls PingSimple() → pings /v2/
2. istio returns 401 Bearer realm="…/v2/auth" service="registry.istio.io"
3. Before fetching the token, parseScopes() inspects the request path. But /v2/ is the base endpoint — it matches no pattern (manifest/blob/tag/catalog), so it returns nil (see the // base or no match, return nil line in bearer/scope.go).
4. fetchToken(nil) sends the token request with no scope param: …/v2/auth?service=registry.istio.io
5. istio's token service replies 400 scope is required
6. PingSimple() only tolerates 401/403 — a 400 is not whitelisted, so → unhealthy.

Why only istio registry breaks: most registries (Docker Hub, etc.) return an anonymous token for an empty scope, so the ping passes. istio's token service is stricter and rejects scope-less requests, which exposes this edge case.

[Jeansen]

@chlins Thank you for the explanation. So, nevertheless, Harbor should be able to handle thes edge cases, right?

[Adityakumar37]

@chlins @Jeansen

Since the root cause is that fetchToken sends no scope param when parseScopes() can't derive one from the base /v2/ path, and istio's token service (unlike most registries) hard-rejects that with 400, I see two possible fixes and wanted to check which direction you'd prefer before opening a PR:

Option A — widen PingSimple's tolerance (src/pkg/reg/adapter/native/adapter.go)

Treat 400 the same as the existing 401/403 allowance, since PingSimple's intent is only to check connectivity/cert validity, not auth outcome:

if errors.IsErr(err, errors.UnAuthorizedCode) ||
    errors.IsErr(err, errors.ForbiddenCode) ||
    errors.IsErr(err, errors.BadRequestCode) {
    return nil
}

Simple, low-risk, ships fast — but it's a blunt instrument that also swallows any other 400 a registry might return for unrelated reasons.

Option B — fix the actual scope-fetch gap (bearer/scope.go / token fetch)

When parseScopes() returns nil for a base /v2/ ping, fall back to requesting a token with a generic scope (e.g. registry:catalog:*) instead of no scope at all. This addresses the real gap — Harbor asking for an anonymous token with no scope — rather than just tolerating whatever error code comes back from that malformed request.

My inclination is Option B is the more correct fix long-term, but happy to do A as a stopgap and B as a follow-up if that's easier to review/merge. Let me know which you'd want, and I'll open a PR against main.

[Jeansen]

@Adityakumar37 Thank's for the insight. I don't have the urge and direct need for istio to be cached and accessed as a registry. It is some sort of an edge case and therefore I would also go directly with option B.