Using the Docker registry REST interface

Docker registry is a server application that stores and distributes Docker images. This note explain how to use curl, and optionally jq, to query the registry for information about container images and their history.

The server's endpoint is assumed to be in a shell variable, such as:
MY_REGISTRY=http://some.host:5000,

To list repositories:

curl https://MY.REGISTRY/v2/_catalog
...

Note: local development registries often do not have proper TLS certificates. For trusted sources and assuming the associated risks, one can bypass certificates and use an insecure connection by adding the curl flag -k/--insecure to the commands shown below.

To list available tags for a given image (e.g. myteam/myapp):
 
curl https://MY.REGISTRY/v2/myrepo/myapp/tags/list

To retrieve the manifest of a given image: (e.g. myteam/myapp):

curl https://MY.REGISTRY/v2/myrepo/myapp/manifests/latest

A common application of manifest queries is to catalog images and use lineage and other metadata on those images for automation. Such metadata is found in image manifests, which are hard to inspect visually due to their complexity. Using a JSON parser like jq can be used to produce a readable report.

Image registry summary report

The following script will produce a simple summary listing every tag for a given image along with SHA identifier and creation date. Temporary files are used to cache intermediate results.

#=== Configure repo and image
REPO_URL=https://my.registry
IMAGE_REPO=myrepo/myimage
BASE_URL=$REPO_URL/v2/$IMAGE_REPO

#=== Download tags

curl -ks $BASE_URL/tags/list > /tmp/tags
#=== Download each tag's manifest, all concatenated
for tag in $(jq -r .tags[] /tmp/tags)
do
  curl -ks $BASE_URL/manifests/$tag
done > /tmp/manifests
#=== Parse manifests and print metadata
cat /tmp/manifests |
  jq -r '{tag:.tag, info:.history[0].v1Compatibility |
    fromjson |
    {created:.created, sha:.config.Image}}' |
  tee /tmp/repo.data.json

 The output can be sorted by timestamp thus:

cat /tmp/repo.data.json | jq -s 'sort_by(.info.created)'