Why

I've lost count of the times I did docker pull, docker push commands but I never really understood how the standard Docker protocol works in order to allow the container images movement.

In the last weeks I tried to search documentation regarding Docker Registry HTTP standard API v2 but I didn't find anything juicy for my brain so I started digging to understand how tipical pull/tag/push commands work.

Well, it was not the really first time I played with Docker registry HTTP API.
I already played with them in Urunner open source project (https://github.com/texano00/urunner/tree/main) but I dealed mainly with get manifest api GET /v2/{name]/manifests/{reference}

I bumped in many documentations, starting from the official one https://docs.docker.com/registry/spec/api/ but I didn't find any sequence diagrams, any swagger API documentations and any Python snippets that works at all.

So I started producing what was missing.
The following materials could be really useful for many intents:

• Adopt Docker API v2 for make integrations between different systems.
  The huge advantage is beeing vendor agnostic.
  Tomorrow you will change your container registry vendor? Your integration could continuosly work withtout many changes.
• Create your custom container registry OR extend a vendor container registry
• Fun <– best thing ever 😎

Intro

Most vendors container registries implement Docker API v2 in order to basically allow common operations like:

docker pull <image>
docker push <image>

Vendors than usually create their products with dedicated features on top of these standard APIs. For example:

• AWS ECR
• Azure ACR
• Dockerhub
• Google Container Registry

But they all have in common the availability of basic pull / push standard operations (for example using podman or docker) thanks to Docker registry API v2.

Postman collection

I collected  the main Docker API v2 apis in the following postman collection

Link below 👇👇👇

Postman

Use cases

Pull image

The following sequence diagram is what it usually happens when you do docker pull {name} command.

Push image

The following sequence diagram is what it usually happens when you do docker push {name} command.

Python snippet on pull-tag-push operation

The following python script instead put together PULL&PUSH, basically it does the same stuff of

docker pull <source>
docker tag <source> <dest>
docker push <dest>

Keep in mind that there are some ready to use tools better than the above script, like crane copy .. from Google (https://github.com/google/go-containerregistry/tree/main/cmd/crane)

Note also that the above script and PUSH diagram does not manage the case of (some) layers already uploaded which is a very common use case. It is essential to address it to improve performance and avoid to generate useless network traffic.

Basically, you could decide to upload a new blob layer based on the response of the following call

HEAD /v2/<name>/blobs/<digest>

Conclusions

All these stuff helped me a lot to understand better what behind the Docker standard API v2 and what are the challanges that, maybe, could be addressed with a potential v3!

Now I feel better.

Credits

• https://swimlanes.io/ for sequence diagrams
• https://github.com/google/go-containerregistry/tree/main/cmd/crane