How to use docker image tag command to manage image aliases

Introduction

In this lab, you will learn how to effectively manage Docker image aliases using the docker image tag command. We will begin by understanding the structure and components of Docker image references, which are essential for identifying and locating specific image versions.

Following the foundational understanding of image references, you will gain hands-on experience tagging images using various methods: by their ID, by their existing name, and by their name and tag combination. Finally, you will learn how to tag an image specifically for use with a private Docker registry, enabling you to push and pull images from custom locations.

Skills Graph

Understand Docker image references

In this step, we will learn about Docker image references. A Docker image reference is a name that points to a specific version of a Docker image. It's how you tell Docker which image you want to use when running a container or performing other image-related operations.

A full image reference typically consists of several parts:

[registry_hostname[:port]/]image_name[:tag]

Let's break down these parts:

• registry_hostname[:port]: This is the hostname and optional port of the Docker registry where the image is stored. If this part is omitted, Docker defaults to Docker Hub (docker.io).
• image_name: This is the name of the image. It can include a namespace (e.g., library/ubuntu or myuser/myapp). If no namespace is specified for official images on Docker Hub, the library/ namespace is implied (e.g., ubuntu is equivalent to library/ubuntu).
• tag: This is an optional tag that specifies a specific version or variant of the image. If no tag is specified, Docker defaults to the latest tag.

Let's look at some examples:

• ubuntu: This refers to the latest tag of the official ubuntu image on Docker Hub.
• ubuntu:20.04: This refers to the 20.04 tag of the official ubuntu image on Docker Hub.
• myuser/myapp: This refers to the latest tag of the myapp image in the myuser repository on Docker Hub.
• myuser/myapp:v1.0: This refers to the v1.0 tag of the myapp image in the myuser repository on Docker Hub.
• myregistry.example.com:5000/myuser/myapp:v1.0: This refers to the v1.0 tag of the myapp image in the myuser repository on the private registry located at myregistry.example.com on port 5000.

To see how image references work in practice, let's pull an image using its reference. We will pull the hello-world image, which is a very small image used for testing Docker installations.

docker pull hello-world

You should see output indicating that Docker is pulling the image.

Using default tag: latest
latest: Pulling from library/hello-world
...
Status: Downloaded newer image for hello-world:latest
docker.io/library/hello-world:latest

This command pulled the latest tag of the hello-world image from Docker Hub. The output confirms the full reference docker.io/library/hello-world:latest.

Now, let's list the images you have downloaded.

docker images

You should see the hello-world image listed.

REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
hello-world   latest    <image_id>     <created_time>   <size>

The output shows the REPOSITORY (image name), TAG, IMAGE ID, CREATED time, and SIZE of the image. The IMAGE ID is a unique identifier for the image content.

Understanding image references is crucial for working with Docker, as it allows you to specify exactly which image you want to use.

Tag an image using its ID

In this step, we will learn how to tag a Docker image using its Image ID. Tagging an image allows you to give it a new name and/or tag, creating a new reference that points to the same image content. This is useful for creating aliases, versioning, or preparing an image to be pushed to a different registry.

The basic command to tag an image is docker tag. The syntax is:

docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]

You can specify the source image using its Image ID, its name, or its name and tag. In this step, we will use the Image ID.

First, let's list the images again to get the Image ID of the hello-world image we pulled in the previous step.

docker images

Find the hello-world image in the output and note its IMAGE ID. It will be a string of hexadecimal characters, for example, bf756fb1cdb1. You only need to use the first few characters of the ID, as long as they are unique among your images.

Now, let's tag the hello-world image using its Image ID. We will tag it with a new name, my-hello-world, and a tag v1.0. Replace <image_id> with the actual Image ID you noted from the docker images output.

docker tag < image_id > my-hello-world:v1.0

There will be no output if the command is successful.

Now, let's list the images again to see the new tag.

docker images

You should now see a new entry with the repository my-hello-world and tag v1.0. Notice that it has the same IMAGE ID as the original hello-world image. This confirms that the new tag is just a pointer to the same image content.

REPOSITORY       TAG       IMAGE ID       CREATED        SIZE
hello-world      latest    <image_id>     <created_time>   <size>
my-hello-world   v1.0      <image_id>     <created_time>   <size>

You have successfully tagged an image using its Image ID. This is a fundamental operation in managing Docker images.

Tag an image using its Name

In this step, we will learn how to tag a Docker image using its Name. This is another common way to reference an image when tagging. When you use only the image name without a tag, Docker assumes you are referring to the image with the latest tag.

The syntax for tagging using the image name is the same as before:

docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]

This time, our SOURCE_IMAGE will be the name of the image. We will use the hello-world image again. Since we don't specify a tag for the source, Docker will use hello-world:latest.

Let's tag the hello-world image with a new name, another-hello-world, and a tag v2.0.

docker tag hello-world another-hello-world:v2.0

Again, there will be no output if the command is successful.

Now, let's list the images to see the new tag.

docker images

You should now see a new entry with the repository another-hello-world and tag v2.0. Like the previous step, this new tag also points to the same IMAGE ID as the original hello-world image.

REPOSITORY          TAG       IMAGE ID       CREATED        SIZE
hello-world         latest    <image_id>     <created_time>   <size>
my-hello-world      v1.0      <image_id>     <created_time>   <size>
another-hello-world v2.0      <image_id>     <created_time>   <size>

You have successfully tagged an image using its name. This is a convenient way to create new tags for the latest version of an image.

Tag an image using its Name and Tag

In this step, we will learn how to tag a Docker image using its Name and Tag. This is the most specific way to reference a particular version of an image when tagging.

The syntax remains the same:

docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]

This time, our SOURCE_IMAGE will be specified with both its name and tag. We will use the my-hello-world:v1.0 image that we created in a previous step.

Let's tag the my-hello-world:v1.0 image with a new name, yet-another-hello-world, and a tag release.

docker tag my-hello-world:v1.0 yet-another-hello-world:release

There will be no output if the command is successful.

Now, let's list the images to see the new tag.

docker images

You should now see a new entry with the repository yet-another-hello-world and tag release. This new tag also points to the same IMAGE ID as the original hello-world image and the other tags we created.

REPOSITORY              TAG       IMAGE ID       CREATED        SIZE
hello-world             latest    <image_id>     <created_time>   <size>
my-hello-world          v1.0      <image_id>     <created_time>   <size>
another-hello-world     v2.0      <image_id>     <created_time>   <size>
yet-another-hello-world release   <image_id>     <created_time>   <size>

You have successfully tagged an image using its name and tag. This method is useful when you want to create a new tag based on a specific existing tagged version of an image.

Tag an image for a private registry

In this step, we will learn how to tag a Docker image so that it can be pushed to a private registry. When tagging an image for a private registry, you need to include the registry's hostname and optional port in the target image reference.

The syntax for tagging remains:

docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]

The TARGET_IMAGE will now include the registry information:

[registry_hostname[:port]/]image_name[:tag]

Let's imagine we have a private registry running at myregistry.example.com on port 5000. We will tag the hello-world image (using its latest tag) to prepare it for pushing to this hypothetical registry. We will give it the name my-hello-world and the tag prod.

docker tag hello-world:latest myregistry.example.com:5000/my-hello-world:prod

There will be no output if the command is successful.

Now, let's list the images to see the new tag with the registry name.

docker images

You should now see a new entry with the repository myregistry.example.com:5000/my-hello-world and tag prod. This tag also points to the same IMAGE ID as the original hello-world image.

REPOSITORY                                TAG       IMAGE ID       CREATED        SIZE
hello-world                               latest    <image_id>     <created_time>   <size>
my-hello-world                            v1.0      <image_id>     <created_time>   <size>
another-hello-world                       v2.0      <image_id>     <created_time>   <size>
yet-another-hello-world                   release   <image_id>     <created_time>   <size>
myregistry.example.com:5000/my-hello-world prod      <image_id>     <created_time>   <size>

You have successfully tagged an image with a reference that includes a private registry hostname and port. This is a necessary step before you can push the image to that registry using the docker push command.

Summary

In this lab, we learned about Docker image references, understanding their structure including the optional registry hostname, image name, and tag. We saw how these references are used to uniquely identify and pull specific image versions from Docker registries.

We then explored how to use the docker image tag command to create aliases for existing images. We practiced tagging an image using its ID, its existing name, and its existing name and tag combination. Finally, we learned how to tag an image with a reference that includes a private registry hostname, preparing it for pushing to a custom registry.