What is the canonical way to see if an image exists in the docker public registry?

Question

We want to check if an image exists in the public registry (Docker Hub) automatically before we start a deployment. With the v1 API, we would just query https://index.docker.io/v1/repositories/gliderlabs/alpine/tags/3.2 for example.

But now the official API for the registry is v2, what is the official way of checking the existence of an image in the public registry?

v1

$ curl -i https://index.docker.io/v1/repositories/gliderlabs/alpine/tags/latest
HTTP/1.1 200 OK
Server: nginx/1.6.2
Date: Tue, 11 Aug 2015 10:02:09 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Vary: Cookie
X-Frame-Options: SAMEORIGIN
Strict-Transport-Security: max-age=31536000

[{"pk": 20307475, "id": "5bd56d81"}, {"pk": 20355979, "id": "511136ea"}]

v2:

$ curl -i https://index.docker.io/v2/repositories/gliderlabs/alpine/tags/latest
HTTP/1.1 301 MOVED PERMANENTLY
Server: nginx/1.6.2
Date: Tue, 11 Aug 2015 10:04:20 GMT
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked
X-Frame-Options: SAMEORIGIN
Location: https://index.docker.io/v2/repositories/gliderlabs/alpine/tags/latest/
Strict-Transport-Security: max-age=31536000

$ curl -i https://index.docker.io/v2/repositories/gliderlabs/alpine/tags/latest/
HTTP/1.1 301 MOVED PERMANENTLY
Server: nginx/1.6.2
Date: Tue, 11 Aug 2015 10:04:26 GMT
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked
X-Frame-Options: SAMEORIGIN
Location: https://registry.hub.docker.com/v2/repositories/gliderlabs/alpine/tags/latest/
Strict-Transport-Security: max-age=31536000

$ curl -i https://registry.hub.docker.com/v2/repositories/gliderlabs/alpine/tags/latest/
HTTP/1.1 200 OK
Server: nginx/1.6.2
Date: Tue, 11 Aug 2015 10:04:34 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Vary: Cookie
X-Frame-Options: SAMEORIGIN
Allow: GET, DELETE, HEAD, OPTIONS
Strict-Transport-Security: max-age=31536000

{"name": "latest", "full_size": 5250074, "id": 130839, "repository": 127805, "creator": 152141, "last_updater": 152141, "image_id": null, "v2": false}

Am I supposed to stick to the v1 url even though it is now kind of deprecated or use v2 URLs but there is no documentation about it? If I use v2, shall I use directly https://registry.hub.docker.com/v2/ or still use https://index.docker.io/v1/ and follow the redirects?

Answer 1

Upstream's download-frozen-image-v2.sh script should be of some use as at least a decent API example here (https://github.com/docker/docker/blob/6bf8844f1179108b9fabd271a655bf9eaaf1ee8c/contrib/download-frozen-image-v2.sh#L47-L54).

The main key is that you'll need to be hitting registry-1.docker.io instead of index.docker.io, and that you need a "token" from auth.docker.io (https://auth.docker.io/token?service=registry.docker.io&scope=repository:gliderlabs/alpine:pull), even if you're just requesting read-only access to a public repository. Once you've got that token, you can hit https://registry-1.docker.io/v2/gliderlabs/alpine/manifests/latest with an Authorization header which will either return the JSON manifest of the image or error out with a 404.

token="$(curl -sSL "https://auth.docker.io/token?service=registry.docker.io&scope=repository:$image:pull" | jq --raw-output .token)"

curl -fsSL -H "Authorization: Bearer $token" "https://registry-1.docker.io/v2/$image/manifests/$digest"