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.
