With many organizations moving to container-based workflows, keeping track of the different versions of your images can become a problem. Even smaller organizations can have hundreds of container images spanning from one-off development tests, through emergency variants to fix problems, all the way to core production images. This leads us to the question: How can we tame our image sprawl while still rapidly iterating our images?<\/p>\n
A common misconception is that by using the \u201clatest\u201d tag, you are guaranteeing that you are pulling the \u201clatest\u201d<\/em> version of the image. Unfortunately, this assumption is wrong \u2014 all latest means is \u201cthe last image pushed to this registry.\u201d <\/p>\n Read on to learn more about how to avoid this pitfall when using Docker and how to get a handle on your Docker images<\/a>.<\/p>\n One way to address this issue is to use tags when creating an image. Adding one or more tags to an image helps you remember what it is intended for and helps others as well. One approach is always to tag images with their semantic versioning (semver<\/a>), which lets you know what version you are deploying. This sounds like a great approach, and, to some extent, it is, but there is a wrinkle.<\/p>\n Unless you\u2019ve configured your registry for immutable tags, tags can be changed. For example, you could tag my-great-app as v1.0.0 and push the image to the registry. However, nothing stops your colleague from pushing their updated version of the app with tag v1.0.0 as well. Now that tag points to their image, not yours. If you add in the convenience tag latest, things get a bit more murky. <\/p>\n Let\u2019s look at an example:<\/p>\n # Create a script that outputs the version # Set the entrypoint to run the script We build the above with docker build -t tagexample:1.0.0 . and run it.<\/p>\n What if we run it without a tag specified?<\/p>\n Now we build with docker build . without specifying a tag and run it.<\/p>\n The latest tag is always applied to the most recent push that did not specify a tag. So, in our first test, we had one image in the repository with a tag of 1.0.0, but because we did not have any pushes without a tag, the latest tag did not point to an image. However, once we push an image without a tag, the latest tag is automatically applied to it.<\/p>\n Although it is tempting to always pull the latest tag, it\u2019s rarely a good idea. The logical assumption \u2014 that this points to the most recent version of the image \u2014 is flawed. For example, another developer can update the application to version 1.0.1, build it with the tag 1.0.1, and push it. This results in the following:<\/p>\n $ docker run –rm tagexample:latest If you made the assumption that latest pointed to the highest version, you\u2019d now be running an out-of-date version of the image.<\/p>\n The other issue is that there is no mechanism in place to prevent someone from inadvertently pushing with the wrong tag. For example, we could create another update to our code bringing it up to 1.0.2. We update the code, build the image, and push it \u2014 but we forget to change the tag to reflect the new version. Although it\u2019s a small oversight, this action results in the following:<\/p>\n Unfortunately, this happens all too frequently.<\/p>\n Because we can\u2019t trust tags, how should we ensure that we are able to identify our images? This is where the concept of adding metadata to our images becomes important.<\/p>\n The first attempt at using metadata to help manage images was the MAINTAINER instruction. This instruction sets the \u201cAuthor\u201d field (org.opencontainers.image.authors) in the generated image. However, this instruction has been deprecated in favor of the more powerful LABEL instruction. Unlike MAINTAINER, the LABEL instruction allows you to set arbitrary key\/value pairs that can then be read with docker inspect as well as other tooling.<\/p>\n Unlike with tags, labels become part of the image, and when implemented properly, can provide a much better way to determine the version of an image. To return to our example above, let\u2019s see how the use of a label would have made a difference.<\/p>\n To do this, we add the LABEL instruction to the Dockerfile, along with the key version and value 1.0.2.<\/p>\n LABEL version=”1.0.2″<\/p>\n # Create a script that outputs the version # Set the entrypoint to run the script Now, even if we make the same mistake above where we mistakenly tag the image as version 1.0.1, we have a way to check that does not involve running the container to see which version we are using.<\/p>\n Although you can use any key\/value as a LABEL, there are recommendations. The OCI<\/a> provides a set of suggested labels within the org.opencontainers.image namespace, as shown in the following table:<\/p>\n Label<\/strong>Content<\/strong>org.opencontainers.image.createdThe date and time on which the image was built (string, RFC 3339 date-time).org.opencontainers.image.authorsContact details of the people or organization responsible for the image (freeform string).org.opencontainers.image.urlURL to find more information on the image (string).org.opencontainers.image.documentationURL to get documentation on the image (string).org.opencontainers.image.sourceURL to the source code for building the image (string).org.opencontainers.image.versionVersion of the packaged software (string).org.opencontainers.image.revisionSource control revision identifier for the image (string).org.opencontainers.image.vendorName of the distributing entity, organization, or individual (string).org.opencontainers.image.licensesLicense(s) under which contained software is distributed (string, SPDX License List).org.opencontainers.image.ref.nameName of the reference for a target (string).org.opencontainers.image.titleHuman-readable title of the image (string).org.opencontainers.image.descriptionHuman-readable description of the software packaged in the image (string).<\/p>\n Because LABEL takes any key\/value, it is also possible to create custom labels. For example, labels specific to a team within a company could use the com.myorg.myteam namespace. Isolating these to a specific namespace ensures that they can easily be related back to the team that created the label.<\/p>\n Image sprawl is a real problem for organizations, and, if not addressed, it can lead to confusion, rework, and potential production problems. By using tags and labels in a consistent manner, it is possible to eliminate these issues and provide a well-documented set of images that make work easier and not harder.<\/p>\n Read the Docker Best Practices<\/a> collection.<\/p>\n Subscribe to the Docker Newsletter<\/a>.\u00a0<\/p>\n Get the latest release of Docker Desktop<\/a>.<\/p>\n Vote on what\u2019s next! Check out our public roadmap<\/a>.<\/p>\n Have questions? The Docker community is here to help<\/a>.<\/p>\nUsing tags<\/h2>\n
\nRUN echo -e “#!\/bin\/shn” > \/test.sh &&
\n echo “echo “This is version 1.0.0″” >> \/test.sh &&
\n chmod +x \/test.sh<\/p>\n
\nENTRYPOINT [“\/bin\/sh”, “\/test.sh”]\n<\/p><\/div>\n
\nThis is version 1.0.0\n<\/div>\n
\nUnable to find image ‘tagexample:latest’ locally
\ndocker: Error response from daemon: pull access denied for tagexample, repository does not exist or may require ‘docker login’.
\nSee ‘docker run –help’.\n<\/div>\n
\nThis is version 1.0.0\n<\/div>\n
\nThis is version 1.0.1\n
\nThis is version 1.0.0\n<\/p><\/div>\n
\nThis is version 1.0.2\n<\/div>\nUsing labels<\/h2>\n
\nRUN echo -e “#!\/bin\/shn” > \/test.sh &&
\n echo “echo “This is version 1.0.2″” >> \/test.sh &&
\n chmod +x \/test.sh<\/p>\n
\nENTRYPOINT [“\/bin\/sh”, “\/test.sh”]\n<\/p><\/div>\n
\n{“version”:”1.0.2″}\n<\/div>\nBest practices<\/h2>\n
Final thoughts<\/h2>\n
Learn more<\/h2>\n