Kubernetes¶
This documentation describes how to perform the version upgrade operation of a Traefik Enterprise cluster in Kubernetes.
Do not attempt upgrading using kubectl or Helm for a major version ugprade
Do not try to upgrade your Traefik Enterprise cluster manually by using kubectl apply
or helm upgrade
and changing the version of Traefik Enterprise in the deployed files. 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 Version Upgrade¶
Upgrading a Manual Installation¶
To upgrade a cluster to a new major version, install a new cluster 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.
- Run the
teectl setup
andteectl setup gen
commands but with a different cluster name and apply the generated manifest file(s). - Run
teectl restore --backup=path/to/your/backup.tar
to restore your cluster configuration in the new cluster. - Wait for the new cluster to have an external IP attributed to its internal load balancer service and make sure that the new cluster is fully operational.
- 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.
- 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.
Upgrading a GitOps Installation¶
If you installed your cluster using GitOps, do the following:
- Install a new cluster in a different namespace.
- Connect
teectl
to your cluster. - Restore your backup using the
teectl restore
command. - Wait for the new cluster to have an external IP attributed to its internal load balancer service and make sure that the new cluster is fully operational.
- 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.
- Ensure that your applications are reachable through the new cluster.
You can now safely delete the resources from the old cluster, but be careful not to delete the CRDs as well while doing so.
Split GitOps Manifest Between CRDs and Resources
You can use the withoutcrds
and withoutresources
options when using the Traefik Enterprise Installation web service to generate your installation manifest, in order to split the CRDs and Resources into two different files.
curl "https://install.enterprise.traefik.io/vx.y?withoutresources" > crds.yaml
curl "https://install.enterprise.traefik.io/vx.y?withoutcrds" > resources.yaml
Minor and Hotfix Version Upgrades¶
To upgrade a cluster to a new minor or hotfix version, get the new manifest from the installation service and apply it over your current cluster, and update your version of teectl
if you use it.
If you made changes to the original manifest before applying it, you will need to do so again. It's recommended to combine those changes into a patch.yaml
file that you can then re-apply to any Traefik Enterprise installation.