Chapter 6. Tagging Images
In This Chapter:
Name container images
Assign tags to images
Attach user names to images
Attach repository names to images
After you have created an image using docker build or by committing a container to an image with docker commit, you can add additional tags to the image using docker tag. Using images named ubuntu and fedora from the Docker Hub to illustrate, here are some reasons that you might want to add tags at the end of an image name to further identify that image:
Version number: A version number can help identify which version of a product was used to build the image. For example, an ubuntu image might be tagged 15.04 (to indicate the Ubuntu release) and also 15.04.2 (to identify a specific point release). Likewise, the Fedora project tags its base fedora images 20, 21, 22, and so forth, to match its releases.
Version name: A name is sometimes assigned to a particular version of an image. For example, Ubuntu version 15.04 is also named vivid (for the release name Vivid Vervet). Fedora 20 also includes the tag name heisenbug on the fedora:20 image.
latest: When someone runs an image without specifically identifying a tag, the docker command looks for the image of that name with the :latest tag. For example, running docker run ubuntu pulls and runs the ubuntu:latest image. So setting the latest tag on an image identifies that image as the one to use when only the basic part of the image name is requested.
By attaching text to the beginning part of an image name, you can identify the registry where the image can be found (when running a docker pull) or into which the image will be put (when running a docker push). Here are a couple of types of images you can apply to the front part of an image name:
Registry name and port: One of the most important uses of image tagging is to add a name of a registry. With a registry name (and optionally a port number) added to the first part of an image name (separated by a slash), a docker pull or docker push knows exactly where to put or get the image you are looking for. When a user name is identified as the registry name, Docker looks to the registry on the docker.io hub associated with the user account.
User name: When a user account is created on the docker.io registry, that account’s user name can be added to the front of an image name to identify that the image should be part of that user’s registry on docker.io. For example, if I pushed an image named docker.io/cricket/hangman, the hangman image would be directed to the personal storage area for the user named cricket at the docker.io registry (Docker Hub).
This chapter teaches you to use the docker tag command to add tags to existing images, essentially enabling the images to be identified by different names.
Assigning Names to Images
An image name is assigned to a Docker image when that image is first created. There are several ways of creating an image. These include the following:
Building an image: When you first build an image from a Dockerfile file, you can assign a name to it. Here’s an example of building an image from a Dockerfile file in the current directory and assigning it the name fedweb:
# docker build -t fedweb .
Committing a container: After you have run a container and changed it in some way that you want to keep, you can commit those changes back to a container image using docker commit. In this example, I ran the fedweb image and called the container newfedweb. Then I committed newfedweb to a new image called myfedweb:
# docker run -d -p 80:80 --name=newfedweb fedweb
# docker stop newfedweb
# docker commit -m "Web server with extra data"
-a "Chris Negus" newfedweb myfedweb
Exporting and Importing an image: You can save an image as a tarball to your file system using docker export. You can name an image when you import it from a previously exported tarball to your system. For example, my friend Joe exports his own container (joefedweb) to a tarball and sends it to me. Then I import the container image.
# docker export joefedweb > joefedweb.tar
# cat joefedweb.tar | docker import - joefedweb
At this point, I have three new images on my system. Notice that without adding a tag to the image name, each image is assigned “latest” as its tag. For example:
# docker images *web
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
joefedweb latest 88abf604cfcc 12 minutes ago 526.6 MB
myfedweb latest 8340292d5467 3 hours ago 706.5 MB
fedweb latest f583b458b447 4 hours ago 696.7 MB
Using these three images, the next sections illustrate how the docker tag command can add tags and additional repository information to an image name in ways that make the images more usable.
Assigning Tags to Images
By adding tags to images you can be more specific about what an image contains. The most common use of tags is to add version information to an image. As a new version of an image becomes available, it can replace the “latest” instance of an image and still retain tags (which act as aliases to the same image) to other defining information on the image.
Say that you want to add tags to images you created earlier to identify version names and numbers for those images. Here are examples of how you might do that:
# docker tag fedweb fedweb:1.5
# docker tag fedweb fedweb:monkey
# docker images fedweb
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
fedweb 1.5 f583b458b447 12 hours ago 696.7 MB
fedweb latest f583b458b447 12 hours ago 696.7 MB
fedweb monkey f583b458b447 12 hours ago 696.7 MB
You can tell that the three fedweb images are actually the same image by the fact that the image IDs for all three are the same (f583b458b447). Next, say that you want to use myfedweb as a later release of fedweb. You could tag myfedweb to indicate that the image is also known by the name fedweb:1.7 and fedweb:giraffe, along with being the latest version of fedweb. Because fedweb:latest already exists, you need to force the name (-f).
# docker tag myfedweb fedweb:1.7
# docker tag myfedweb fedweb:giraffe
# docker images *fedweb
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
fedweb 1.5 f583b458b447 13 hours ago 696.7 MB
fedweb latest f583b458b447 13 hours ago 696.7 MB
fedweb monkey f583b458b447 13 hours ago 696.7 MB
fedweb giraffe 8340292d5467 12 hours ago 706.5 MB
fedweb 1.7 8340292d5467 12 hours ago 706.5 MB
# docker tag myfedweb fedweb:latest
FATA[0000] Error response from daemon: Conflict: Tag latest is already
set to image f583b458b447..., if you want to replace it, please use -f
option
# docker tag -f myfedweb fedweb:latest
# docker images *fedweb
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
fedweb latest 8340292d5467 12 hours ago 706.5 MB
fedweb 1.5 f583b458b447 13 hours ago 696.7 MB
fedweb monkey f583b458b447 13 hours ago 696.7 MB
fedweb giraffe 8340292d5467 12 hours ago 706.5 MB
fedweb 1.7 8340292d5467 12 hours ago 706.5 MB
Notice that forcing (-f) the fedweb:latest image name and tag on the myfedweb image not only makes that image the default when someone requests fedweb but also removes the latest designation from the original image (f583b458b447). As an alternative, you can remove the tag for any image with multiple names without removing the image itself. For example:
# docker rmi fedora:latest
Untagged: fedora:latest
Assigning Repository Names to Images
While the image_name:tag portion of an image name identifies what the image is, information attached to the front of that name can identify the repository that stores the image. While no repository information is required when you name a container image, the syntax for adding that information is as follows:
[repository]:[port#]/[username]/image_name:tag
The username can be replaced with the name of a user account name on the Docker Hub (docker.io). Identifying a user name makes it easy to push an image to the repository under your user account at the Docker Hub. You can skip the user name and instead identify the location of a private repository (either by IP address or hostname), along with an optional port number, if you want to push an image to a registry located on a particular host and, optionally, a specific port on that host.
Attaching a User Name to an Image
If you have a user account at the Docker Hub, you can replace username with the user account name that you choose. For example, if I had a user account at docker.io named cricket, I could add that user name to an image that I want to push to docker.io. I might do the following to indicate that an image named fedweb:latest is destined for that domain:
# docker tag fedweb:latest cricket/fedweb:latest
# docker images *fedweb
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
cricket/fedweb latest 8340292d5467 12 hours ago 706.5 MB
fedweb latest 8340292d5467 12 hours ago 706.5 MB
Notice that now two names are associated with the same Image ID. With the user name attached to the image, you can push that image to the docker.io repository. Assuming the user name cricket again, here’s how to authenticate to docker.io as you push an image up to that account on the docker.io repository:
# docker push cricket/fedweb
The push refers to a repository [cricket/fedweb] (len: 1)
Sending image list
Pushing repository cricket/fedweb (1 tags)
...
Pushing tag for rev [8340292d5467] on {https://cdn-registry-1.
docker.io/v1/repositories/cricket/fedweb/tags/1.5}
Because only the user name is added to the image and not a separate repository name, the image is pushed to the repository associated with the cricket user account on docker.io. If you were to log in as cricket at https://hub.docker.com/, you could see the pushed image as shown in Figure 6.1.
If you want the image to be available from another tag name, you can tag the image again and push it. In this example, I add the tag cricket/fedweb:monkey to the existing image. Notice that when I push the name with the new tag to the docker registry for cricket at docker.io it shows that the layers that make up the image have already been pushed to docker.io:
# docker push cricket/fedweb:monkey
The push refers to a repository [cricket/fedweb] (len: 1)
Sending image list
Pushing repository cricket/fedweb (1 tags)
511136ea3c5a: Image already pushed, skipping
00a0c78eeb6d: Image already pushed, skipping
...
Upon returning to cricket’s account, clicking on the Tag tab lets you see all the images and aliases (tags) to each image available within the user account. In Figure 6.2 you can see that the cricket/fedweb image has two tags on it (1.5 and monkey).
At this point, because I have not restricted the image, anyone who wanted to use my cricket/fedweb image could do so using the docker pull cricket/fedweb command, as shown in the Pull this repository box in Figure 6.2. Anyone can also find that image by searching for cricket/fedweb on the docker.io hub.
# docker search cricket/fedweb
NAME DESCRIPTION STARS OFFICIAL AUTOMATED
cricket/fedweb 0
With the container entry displayed on docker.io, you can add a description of the image. Select the edit icon on the Information tab and you can add a short description and full description of the image. After you save that information, the short description is displayed when someone searches for the image. For example:
# docker search cricket/fedweb
NAME DESCRIPTION STARS OFFICIAL...
cricket/fedweb Test apache web server container 0
Attaching a Repository Name to an Image
By attaching a repository name to an image, you can use docker push on that image to direct it to be pushed to a docker registry you identify. You can set up your own private docker registry by installing the docker-registry package, starting up the docker-registry service, and making that service available on a particular port on an accessible system.
If you had the docker-registry service set up at a host named myregistry.example.com, listening on the default port (TCP 5000), you could tag an image so you could push it to that registry. For example, here’s how to tag the fedweb:1.5 image we were working with earlier so it could be pushed to myregistry.example.com:
# docker tag fedweb:1.5 myregistry.example.com:5000/fedweb:1.5
# docker images myregistry.example.com:5000/fedweb
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
myreg.example.com:5000/fedweb 1.5 f583b458b447 1 day ago 696.7 MB
To actually push the image to the registry, you could type the following:
# docker push myregistry.example.com:5000/fedweb:1.5
The push refers to a repository [myregistry.example.com:5000/fedweb]
(len: 1)
Sending image list
Pushing repository myregistry.example.com:5000/fedweb (1 tags)
511136ea3c5a: Image successfully pushed
...
f583b458b447: Image successfully pushed
Pushing tag for rev [f583b458b447] on {http://myregistry.example.com:5000/v1/repositories/fedweb/tags/1.5}
In fact, you could apply multiple image names and tags to the same image so that the same image (identified by the image ID) could be pushed to different registries. Returning to the previous example, at this point, anyone with access to your docker-registry system can pull the image to their local system. For example:
# docker pull myregistry.example.com:5000/fedweb:1.5
Pulling repository myregistry.example.com:5000/fedweb
f583b458b447: Download complete
511136ea3c5a: Download complete
...
Status: Downloaded newer image for myregistry.example.com:5000/fedweb:1.5
Summary
By tagging a Docker formatted container image you can identify not only what an image contains, but also where it should be stored and possibly which user account repository is associated with it. It is typical to add tags that identify version number and version names of the software in the image. Images can also be tagged with hostnames and IP addresses, so the images can be pushed to and pulled from a docker-registry service running on a host.