Docker images are the basis of Docker containers. As images are the foundation, have you ever wondered how to update Docker containers when a new version of an image is released?
Not a reader? Watch this related video tutorial!Wonder no more! In this tutorial, you will learn how to update your local Docker image repository and update your containers to a new version without messing things up!
Prerequisites
This tutorial will be a hands-on demonstration. If you’d like to follow along, be sure you have the following:
- Linux environment – The tutorial uses Linux (Ubuntu Focal) to run Docker, but you can also apply the same general steps to Windows or macOS.
- Install Docker engine 20.10.8 (Linux) or Docker desktop 3.5.2 (macOS and Windows).
Running Idempotent Docker Images
A Docker image contains all the software required to run the application associated with it, including OS packages and dependencies. Docker assembles images through instructions within a file called a Dockerfile, which contains idempotent installation instructions.
An idempotent instruction implies that the image resulting from executing the installation instruction will always result in the same output.
The advantage of building idempotent images is that they are system-independent: the resulting image will always be the same. The container execution will always be the same, too, no matter where execution takes place.
A new image version usually implies some improvements on the instruction for building the Docker container base, for example:
- A newer version of the application source code can replace the old one;
- Better management of dependencies: less space required or better performance;
- Better security: the image has security patches to avoid vulnerabilities.
To get the last benefits from any update in Docker images, you need to know how to update them and apply those updates to your containers.
Updating Local Docker images
To begin with, start by updating a local Docker image. The application in the example python container runs Python code applications. Updating the local Docker image means that applications can rely on the newly updated image.
You first need to know which images are currently available in your local environment. Run the following command to check your local images. The TAG column indicates the available version of the image.
docker images
Now that you have your local version of the image, you then must find the latest available image on a remote registry. There are multiple remote Docker registries (repositories of Docker images) that the Docker engine queries to update your local images. Docker pulls images from DockerHub by default, but there are multiple alternatives, most of them private. Some alternative repositories are listed below.
Navigate through the repository page and look for your desired image: an official Python image that you will update as an example. Type python to find the desired image in DockerHub, and open it to find the available tags. The examples for this tutorial are of a Python image.
Every tag also has a push date. The push date is the date when the image was uploaded to the registry. Take note of the image tag and name, both of which you will need in the following steps.
Now that you have the newer version tag, it is time to update the image. To update to a newer image, you first need to pull the new version. Run the docker pull command followed by a colon and the name and the tag of the newer image: the name and tag that you took note of previously. The name and tag for the example is python:slim-buster. The full command and the resulting output are shown below.
docker pull python:slim-buster 
To pull the image from the non-default Docker image registry (DockerHub), you must provide the full image URI instead. For example: to pull Python from (AWS) ECR Public Gallery, run
dockerpull public.ecr.aws/bitnami/python:3.7
Learning How to Update Docker Containers
Once you create a container, the container image cannot change. Since the image cannot change, you cannot truly update a running container. What you do is recreate any running containers with replacement containers using the newer image version.
Since you already have the more recent version, it’s time to recreate the containers with the old images that need updating.
To find which containers you need to recreate, list any existing containers running the old image. The docker ps command lists containers. With the --filter flag, you specify which containers to list. There are multiple available options for filtering, and the ancestor flag filters by the image used as a base to build the container. The starting containers in the examples are for Python 3.7.2, which you will apply as a filter. The -a switch shows all available containers.
docker ps -a --filter "ancestor=python:3.7.2"
You can use the output of docker ps as an input to run the docker stop command on all the listed containers. The flag -q is included, so the listing command only returns the IDs of the containers. The output of the command is the list of IDs of the stopped containers.
docker stop $(docker ps -aq --filter "ancestor=python:3.7.2")
After stopping the containers, you need to ask Docker to effectively delete them from the system before removing the outdated image.
docker rm $(docker ps -aq --filter "ancestor=python:3.7.2")
After removing all the containers associated with the deprecated image, you can remove the old image with the docker rmi command.
docker rmi python:3.7.2
docker rmi command. Creating New Containers with the Update Images
Now it’s time to finally replace the old containers, those that were previously deleted, with new containers based on the updated image. This time, you’ll create the containers using the newer image version. Since the containers are idempotent, you can expect everything to work as before.
Run the new container with the docker run command and the name and the tag of the updated image that the container will need. In this example, the -it flag tells Docker to run the container in interactive mode, so you can run commands inside the container to verify any updated functionality.
docker run -it python:slim-buster
Notice that the new Docker container is running a newer Python version: version 3.9.7.
Conclusion
In this tutorial, you took a peek behind the covers and learned the magic behind how to update Docker containers: smoke and mirrors! There is no updating! Instead, remove all traces of the old version and replace them with new containers using a newer version. And, thanks to idempotency, containers keep working as usual: TA-DA!
So, what are the containers you are planning to update next?
