Skip to content

Swarm

This documentation describes how to perform the version upgrade operation of a Traefik Enterprise cluster in Swarm.

Do not attempt upgrading using docker service update

Do not try to upgrade your Traefik Enterprise cluster manually by using docker service update. Using the method described in this documentation instead will allow you to smoothly upgrade your cluster.

Backing Up the Outdated Cluster

First, follow the documentation on backing up a cluster to generate a backup archive, which will be used to configure a new cluster.

Upgrading teectl

The teectl tool must be upgraded before starting the cluster version upgrade: follow the installing teectl guide to install the latest version of the binary.

Run teectl version to ensure the correct version is installed.

Major and Minor Version Upgrades

To upgrade a cluster, install a new one running in parallel with the outdated cluster. Once the new cluster is reachable, the outdated cluster can be uninstalled.

In order to install a second cluster without conflicting with the existing one, it has to be installed under a different cluster name. This means all teectl commands must specify the --cluster option with the new cluster name.

Version upgrade from v1 to v2

To update a v1 cluster to v2, first make sure that the existing cluster is running at least version v1.3. Back it up and then use the cluster migration tool to transform the v1 backup into a v2 backup that can be used in the upgrade procedure.

  1. Run the teectl setup and teectl setup gen commands with a different cluster name and by specifying different values for the --swarm.http, --swarm.https, --swarm.dashboard and --swarm.ctlapi options. Then, deploy the manifest files.
  2. Wait for the new cluster to be fully operational.
  3. Redirect the traffic to the new cluster's external IP, with the new HTTP and HTTPS ports of the replacement cluster. This might be done by modifying your L4 load balancer for example. Redirect the traffic to the new cluster's external IP. You could do this by updating the external DNS entry to point to the new load balancer service's IP, for example, or by editing your L4 load balancer configuration.
  4. Ensure that your applications are reachable through the new cluster.

The new cluster should now be operating properly, and the upgrade process should not have dropped any application traffic. The outdated cluster can safely be removed.

Hotfix Version Upgrades

To upgrade a cluster to a new hotfix version, update teectl to the latest version and rerun the teectl setup gen commands that you ran to install your cluster the first time, to generate updated files for the proxies and controllers. Deploy those files, and Docker Swarm will smoothly upgrade the existing services to the latest version.