Skip to main content

Upgrading and Maintaining Docker Deployments

Introduction​

Upgrading and maintaining Docker deployments is a critical aspect of ensuring the stability, security, and performance of your containerized applications. Whether you manage a single host or a cluster of Docker nodes, having a robust process for upgrades and routine maintenance will help you avoid downtime, security vulnerabilities, and inconsistencies across environments. This lesson covers best practices, strategies, and hands-on steps for safely upgrading Docker and performing ongoing maintenance.

Table of Contents​

  1. Why Upgrade and Maintain Docker Deployments?
  2. Planning for Docker Upgrades
  3. Upgrading Docker Engine
  4. Upgrading Docker Compose
  5. Upgrading Docker Swarm and Multi-Node Clusters
  6. Routine Maintenance Tasks
  7. Common Mistakes and Pitfalls
  8. Summary
  9. Quiz

Why Upgrade and Maintain Docker Deployments?​

  • Security: New versions fix vulnerabilities and patch exploits.
  • Performance: Upgrades can bring optimizations and new features.
  • Compatibility: Ensures support for new OS versions and dependencies.
  • Stability: Bug fixes reduce crashes and unpredictable behavior.

Use Case:
A team running Docker containers on Ubuntu needs to upgrade Docker Engine to address a recently discovered security vulnerability. Delaying the upgrade could expose their applications to attacks.

Planning for Docker Upgrades​

Proper planning minimizes risks and downtime:

1. Read Release Notes and Changelogs​

2. Back Up Critical Data​

  • Backup volumes, configuration files, and images.
  • For example, to backup all volumes: 
    docker run --rm -v myvolume:/volume -v $(pwd):/backup alpine tar czvf /backup/myvolume-backup.tar.gz -C /volume .

3. Test the Upgrade in Staging​

  • Replicate your production environment and perform the upgrade.
  • Verify that all containers and orchestrators (Swarm, Compose) work as expected.

4. Schedule Downtime or Rolling Upgrades​

  • For critical production systems, schedule a maintenance window or use a rolling upgrade process to avoid total downtime.

Upgrading Docker Engine​

The process may differ by platform.

On Ubuntu/Debian​

  1. Update the apt package index: 
    sudo apt-get update
  2. Upgrade Docker Engine: 
    sudo apt-get install --only-upgrade docker-ce docker-ce-cli containerd.io
  3. Verify the Upgrade: 
    docker version
    docker info

On CentOS/RHEL​

sudo yum update docker-ce docker-ce-cli containerd.io

On Windows and macOS​

  • Use the Docker Desktop app’s built-in update feature.

Post-Upgrade:​

  • Restart containers if needed. Usually, running containers are not interrupted, but using new features may require a restart.

Pro Tip:
Pin your Docker version in production environments and only upgrade after verifying compatibility with your stack.

Upgrading Docker Compose​

Docker Compose is released independently from Docker Engine.

Upgrade Steps​

  1. Check current version: 
    docker-compose --version
  2. Download the latest version: 
    sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
  3. Apply executable permissions: 
    sudo chmod +x /usr/local/bin/docker-compose
  4. Verify: 
    docker-compose --version

Note:
For Docker Compose V2 (docker compose), the upgrade is usually tied to Docker CLI upgrades.

Upgrading Docker Swarm and Multi-Node Clusters​

Upgrading a Docker Swarm requires coordination to maintain cluster health.

Rolling Upgrade Procedure​

  1. Upgrade Manager Nodes One at a Time:

    • Drain the node: 
      docker node update --availability drain <NODE-ID>
    • Upgrade Docker Engine as above.
    • Set node back to active: 
      docker node update --availability active <NODE-ID>

  2. Upgrade Worker Nodes:

    • Upgrade one at a time to avoid service disruption.

  3. Verify Cluster Health:

    docker node ls
    docker service ls

Blue-Green Deployment (Advanced)​

  • Stand up a new set of hosts with the upgraded version.
  • Migrate workloads and traffic to the new cluster.
  • Roll back if issues discovered.

Routine Maintenance Tasks​

1. Prune Unused Objects​

Remove unused containers, images, networks, and volumes:

docker system prune -a

2. Monitor Disk Usage​

Check disk space used by Docker:

docker system df

3. Update Images​

Regularly pull updated base images:

docker pull <image>:<tag>

Then, recreate containers with the new image.

4. Audit Security​

Scan images for vulnerabilities (example with docker scan):

docker scan <image>

5. Rotate Logs​

Prevent logs from consuming all disk space. Use log rotation options in daemon.json:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Common Mistakes and Pitfalls​

  • Skipping Backups:
    Not backing up volumes or configuration before upgrades can result in data loss.

  • Ignoring Release Notes:
    Upgrades may introduce breaking changes; always review the official documentation.

  • Upgrading All Nodes at Once:
    In a clustered environment, this can lead to downtime or service loss.

  • Neglecting Image Updates:
    Keeping old, vulnerable images exposes your deployment to risk.

  • Disk Space Exhaustion:
    Not pruning unused images and volumes can fill disks, causing Docker to fail.

Summary​

Upgrading and maintaining Docker deployments is crucial for security, stability, and performance. Always plan carefully, back up critical data, test upgrades in non-production environments, and follow a rolling or blue-green upgrade strategy for clusters. Routine maintenance, such as pruning unused resources and regularly updating images, helps keep your environment healthy and secure.

Quiz​

  1. Why should you back up Docker volumes before upgrading Docker Engine?
    a) To speed up the upgrade
    b) To prevent data loss in case of an upgrade failure
    c) To comply with Docker licensing
    d) It is not necessary

    Answer: b) To prevent data loss in case of an upgrade failure

  2. What is the recommended way to upgrade Docker Engine on a Docker Swarm cluster?
    a) Upgrade all nodes at once
    b) Upgrade manager and worker nodes one at a time
    c) Delete the entire cluster and recreate
    d) No upgrade is needed for Swarm

    Answer: b) Upgrade manager and worker nodes one at a time

  3. Which command can help you clean up unused Docker objects?
    a) docker clean
    b) docker system prune -a
    c) docker remove all
    d) docker clean-all

    Answer: b) docker system prune -a

  4. Where can you find information about breaking changes or new features in Docker releases?
    a) Docker Hub
    b) Docker release notes and changelogs
    c) Dockerfile
    d) Container logs

    Answer: b) Docker release notes and changelogs

  5. What is a common pitfall when upgrading Docker in a production environment?
    a) Upgrading in a testing environment first
    b) Backing up data
    c) Not reading release notes or skipping backups
    d) Using rolling upgrade strategy

    Answer: c) Not reading release notes or skipping backups