Kratik Jain
Kratik's What Notes!💡

Kratik's What Notes!💡

How to check if a Docker image already exists?

Hey, Image 👋 Are you there? (Obviously not like this)

How to check if a Docker image already exists?
Kratik Jain's photo
Kratik Jain

Published on May 22, 2021

3 min read

Subscribe to my newsletter and never miss my upcoming articles

1_7a8Qffxkg7WuePBZUebYSw.png

Hello World!

Excited to share my first-ever blog here. This is about how you can check if a docker image (with a specific tag) already exists or not.

We'll divide this article into two parts (based on Types of Images):

  1. Public Images
  2. Private Docker Hub Images

Let's start.

1. Public Images

As we know this is the URL of Docker Hub. https://hub.docker.com

Like every other application, Docker Hub also gives us an API to fetch some details. for our use case the endpoint is:

https://hub.docker.com/v2/repositories/$YourRepoName/tags/$YourTag

When you hit the above Endpoint with the appropriate Repo name and Tag and we get a response like below:

{
  "creator": 7313837,
  "id": 120961274,
  "image_id": null,
  "images": [
    {
      "architecture": "amd64",
      "features": "",
      "variant": null,
      "digest": "sha256:42cdec39185034eb978e30633fc724295cc1f8c5e56c72d14d2c22279ce05fe3",
      "os": "linux",
      "os_features": "",
      "os_version": null,
      "size": 566752686,
      "status": "active",
      "last_pulled": "2021-05-16T23:18:11.632024Z",
      "last_pushed": "2020-10-12T01:39:07.219803Z"
    }
  ],
  "last_updated": "2020-10-12T01:39:07.219803Z",
  "last_updater": 7313837,
  "last_updater_username": "k4kratik",
  "name": "latest",
  "repository": 10006849,
  "full_size": 566752686,
  "v2": true,
  "tag_status": "active",
  "tag_last_pulled": "2021-05-16T23:18:11.632024Z",
  "tag_last_pushed": "2020-10-12T01:39:07.219803Z"
}

👨‍💻 Tip - There are official Docker images that do not require us to put a username while pulling those images, for Example - ubuntu, Postgres, etc.

For example, The link of one of my Repo: hub.docker.com/r/k4kratik/chromedriver-sele..
The link to the official Ubuntu repo is: hub.docker.com/_/ubuntu

ℹ️Notice is the _ here (instead of username)

https://hub.docker.com/v2/repositories/_/ubuntu/tags/latest

So If you use _ in API you will get an error.

🤔 Then what should we use for public images?
The answer is: use library at the place of the username in the API. Like below:

https://hub.docker.com/v2/repositories/library/ubuntu/tags/latest

2. Private Docker Hub Images

Now Comes the Complex Part, As you can assume, We need to authenticate ourselves first before making any request for private repositories.

Let's find out How do we do that?

To Authorize yourself for your private repos on Docker Hub, first, you need to login to Docker Hub programmatically(using API) and it will give you a JWT token. Now use this fresh token in the above-discussed API.

The below command will give you the token

export DOCKER_HUB_USERNAME="my_docker_hub_username"
export DOCKER_HUB_PASSWORD="docker_hub_access_token" 
# You can use your password here but for security purposes, I'll recommend you to use token only
DHUB_TOKEN=$(curl -sSLd "username=${DOCKER_HUB_USERNAME}&password=${DOCKER_HUB_PASSWORD}" https://hub.docker.com/v2/users/login | jq -r ".token")

ℹ️ If you don't know How you can generate a token, check this.

Now we can hit our Previous API with little changes, we will pass our token as Authorization header. In Action: (continuing the above commands)

export DOCKER_REPO="my_username/my_repo_name"
export DOCKER_TAG="v1.2.1"
curl -sH "Authorization: JWT $DHUB_TOKEN" "https://hub.docker.com/v2/repositories/${DOCKER_REPO}/tags/${DOCKER_TAG}/"

This will give you the details about the existence of your specified image.

Sample Output for non-existent image:

{
  "txnid": "REPOSREQ-4d578bda-cc28-4c0d-b2a8-a0634c4e70fe",
  "message": "tag 'v1' not found",
  "errinfo": {
    "api_call_docker_id": "6e1f600164b947b6b69e6266a50a4d40",
    "api_call_name": "GetRepositoryTag",
    "api_call_start": "2021-05-22T08:39:58.506130526Z",
    "api_call_txnid": "REPOSREQ-4d578bda-cc28-4c0d-b2a8-a0634c4e70fe",
    "namespace": "k4kratik",
    "repository": "my-repo",
    "tag": "v1"
  }
}

Sample Output for an image and tag that exist:

{
  "creator": 7313837,
  "id": 118139141,
  "image_id": null,
  "images": [
    {
      "architecture": "amd64",
      "features": "",
      "variant": null,
      "digest": "sha256:0776a3a40c0223f03edaff3f9f20684b71eaa34a64f0ac9285766baced2c392f",
      "os": "linux",
      "os_features": "",
      "os_version": null,
      "size": 44840737,
      "status": "active",
      "last_pulled": "2021-05-16T23:19:04.068998Z",
      "last_pushed": "2020-09-20T15:18:16.510109Z"
    }
  ],
  "last_updated": "2020-09-20T15:18:16.510109Z",
  "last_updater": 7313837,
  "last_updater_username": "k4kratik",
  "name": "latest",
  "repository": 9869685,
  "full_size": 44840737,
  "v2": true,
  "tag_status": "active",
  "tag_last_pulled": "2021-05-16T23:19:04.068998Z",
  "tag_last_pushed": "2020-09-20T15:18:16.510109Z"
}

I have created a GitHub Gist which has the script for the same. Check below:


Drop Some Emojis if you find this useful. Or leave a comment.

Thanks for Reading! 🙇‍♂️


Wanna buy me a Coffee ☕ ?

buy-me-a-coffee.jpeg

 
Share this
Proudly part of