Hey, depending on what you’re trying to build it might happen that part of it involves inspecting a Docker image from a registry but you can’t afford to pull it. It turns out that that allows you to perform exactly that — be it DockerHub or a private registry. there’s an API The Docker Registry HTTP API is the protocol to facilitate distribution of images to the docker engine. It interacts with instances of the docker registry, which is a service to manage information about docker images and enable their distribution. Testing it locally The first step to test it locally is raising a registry from the image. library/registry Check that it’s definitely working: Having the local registry working, we can move to the script that inspects images right from the registry metadata. The following script contains all that it takes to retrieve it and relies only on two dependencies: and . bash jq ps.: It’s important to note that the API calls need to specify the type of content that it accepts ( _application/vnd.docker.distribution.manifest.v2+json_ ). Let’s now check if it’s working for real: Cool, it indeed works! While that does the job for registries that require no authentication, it’s not suitable for DockerHub. When checking a public image there, we need to perform an extra step before getting the digest of an image — retrieve a token. With such token in hand, we can then inspect either public or private images. Going back to scripting, let’s create a different one to deal with this case — call it (this is for brevity sake, using some other programming language you could place some conditionals and detect each case). get-public-image-config.sh The additional code can be placed in a method called which only takes as an argument: get_token image With the token in hands it’s just a matter of making use of it on the other calls. If we were targetting private images we’d modify a little bit: on the call to get the token from we’d need to do it with a DockerHub username and password pair (without authentication we can only have access to public images). To do so, specify in that call an authorization header ( flag in ): get_token auth.docker.io --user curl Now with this new token we can retrieve the digest of a given image and tag (pay attention to the extra header that we added): Authorization: Bearer $token With that we can have a full script that retrieves public images from DockerHub (check how in we first retrieve a token, then we pass that token to the following methods): main Note.: again, you must add the full name of the image (official images use the _library_ repository so _nginx_ should be referred as _library/nginx_ ). To make sure that it works, run it against an image like : nginx If you try to retrieve an image that is not very new (say, that has some 2 years) you’ll notice that the script I posted above might not work. The reason for that is that images that have been pushed to the docker registry a long time ago won’t use the second version of the V2 manifest. However, they still present the image configuration even though in a regular string. Bellow is a script that deals with that case: If you’re looking for the difference, look at . Essentially we abandon the idea of retrieving a and simply pick the “old config”. From the old config, we look at the first blob in the list which represents the uppermost layer - the layer that contains all the info altogether. From there we parse that plain-text JSON and then get the config. main digest Closing thoughts Interacting with DockerHub or a private registry is not all that hard, it’s just not very documented. Having these scripts it becomes pretty easy to get it working on any language you want — just add some checks, parse the image names and you should be good to go. Here are the resources mentioned in the article: Docker Registry API — Content Digests Docker Registry API — Pulling an Image Manifest Docker Registry API — Pulling a Layer Gist: all the scripts mentioned here I can't finish the article without mentioning some alternatives that people suggested after I first published the article in : ops.tips — — it looks pretty interesting but even though you can specify to an image when analyzing it, it looks like it always pulls the entire image. Maybe I got something wrong? https://github.com/GoogleCloudPlatform/container-diff "Diff your Docker containers" remote:// — — well, does exactly what it says! I totally recommend for the purpose of inspecting images or repositories without pulling them 👍 https://github.com/projectatomic/skopeo ”Work with remote images registries — retrieving information, images, signing content” By the way, if you wan’t to try Skopeo, building it from source is very easy on MacOS: Now inspecting an image or a repository from Dockerhub is one command away: Note that here I’m specifying the flag to the command. The reason is that otherwise it’ll try to inspect the image or repository filtering by digests marked with . If you’re using Linux you’d not need to use that flag. --override-os OS=darwin If you’re not willing to implement in your favorite language and just want to gather the configuration of an image, make sure you check Skopeo. Please let me know if I got anything wrong and/or if there’s an easier way to do it. Have a good one! finis Originally published at ops.tips on November 26, 2017.
