Docker Images Version Tagging Best Practices

Docker Images Version Tagging Best Practices

In this post, I will share some best practices for tagging Docker images. Proper versioning and tagging of Docker images are crucial for maintaining a clean and manageable container registry. Here are some best practices to follow:

1. Use Semantic Versioning

Semantic Versioning (SemVer) is a widely accepted versioning scheme that uses a three-part version number: MAJOR.MINOR.PATCH. This format allows you to communicate the nature of changes in your images clearly. For example:

• 1.0.0 - Initial release
• 1.1.0 - New features added
• 1.1.1 - Bug fixes
• 2.0.0 - Breaking changes introduced

Using SemVer helps in understanding the impact of changes at a glance. It also allows for better dependency management when using images in different environments.

2. Use Tags With different names based on priority

When tagging images, use different unique tags based on the priority of the image with semantic version. For example:

• 1.0.0-dev - The latest development version
• 1.0.0-alpha - The latest alpha version
• 1.0.0-beta - The latest beta version
• 1.0.0-release or 1.0.0-rc 1.0.0-prod - stable version which is ready for production

This approach allows you to easily identify the purpose of each image and helps in managing different stages of development and deployment.

This approach also helps in cleaning up the registry by allowing you to remove older images based on their tags. For example, you can set up a retention policy to keep only the last 5 release images and the last 3 beta images.

3. Avoid Using latest Tag

Using the latest tag can lead to confusion and unexpected behavior. It is better to use specific version tags to ensure that you are using the correct version of an image. If you need to use the latest version, consider using a tag like alpha or beta instead. This way, you can still have a clear understanding of which version is being used in production while avoiding the pitfalls of the latest tag.

4. Clean Up Old Images

Regularly clean up old images to free up space in your container registry. You can set up a retention policy to automatically delete images that are older than a certain number of days or that have not been used in a while. This helps keep your registry organized and reduces storage costs. You can use Azure CLI to delete old images from your Azure Container Registry (ACR) using the following command:

az acr repository delete --name <registry-name> --image <repository-name>:<tag> --yes

Replace <registry-name>, <repository-name>, and <tag> with the appropriate values for your registry and image. You can also use the --filter option to delete images based on specific criteria, such as age or size.

Use ACR Tasks to cleanup old images

You can use Azure Container Registry (ACR) Tasks to automate the cleanup of old images in your ACR. ACR Tasks allow you to run containerized tasks on a schedule or in response to events. You can create a task that runs a script to delete old images based on your retention policy.

Here is an example of how to create an ACR Task to delete old images:

az acr task create \
  --registry <registry-name> \
  --name <task-name> \
  --image <repository-name>:<tag> \
  --context <repository-url> \
  --file <Dockerfile-path> \
  --schedule "0 0 * * *" \
  --cpu 1 \
  --memory 1.5

Replace <registry-name>, <task-name>, <repository-name>, <tag>, <repository-url>, and <Dockerfile-path> with the appropriate values for your registry and image. The --schedule option specifies when the task should run, in this case, every day at midnight.

5. Use Powershell or Bash Scripts for Automation

Setup cleanup tasks based on your retention policy for different tags based on priority. You can use PowerShell or Bash scripts to automate the cleanup process. For example, you can create a script that runs periodically to delete images that are older than a certain number of days or that have not been used in a while.

Here is an example of a PowerShell script that deletes old images from an ACR:

Cleanup images with dev tag older than 15 days and always keep the latest 5 images with dev tag:

$registryName = "<registry-name>"
$repositoryName = "<repository-name>"
$tag = "dev"
$daysToKeep = 15
$maxImagesToKeep = 5

# create purge command
$purgeCommand = "acr purge --ago${daysToKeep}d --filter '${repositoryName}:*${tag}*' --keep $maxImagesToKeep --untagged"

# run purge command
az acr run --registry $registryName --cmd "$purgeCommand" /dev/null

Replace <registry-name> and <repository-name> with the appropriate values for your registry and image. This script uses the az acr run command to execute the purge command in the context of your ACR.

Conclusion

Proper versioning and tagging of Docker images are essential for maintaining a clean and manageable container registry. By following these best practices, you can ensure that your images are easy to understand, manage, and deploy. Regularly cleaning up old images and automating the process will help keep your registry organized and reduce storage costs.