This topic explains how to upgrade Tanzu Kubernetes Grid (TKG) workload clusters. For TKG with a standalone management cluster, you first need to upgrade the management cluster that manages the workload clusters.
- If you are upgrading workload clusters that you deployed with Supervisor in vSphere 8, see Upgrading Clusters Deployed by Supervisor (vSphere 8 Only) in Creating and Managing TKG 2.2 Workload Clusters with the Tanzu CLI.
- Standalone management clusters and workload clusters use client certificates to authenticate clients. These certificates are valid for one year. To renew them, upgrade your clusters at least once a year.
- TKG does not support upgrading clusters running previous versions of
tinyTKr. To update a minimal single-node cluster to the latest
tinyTKr version, you need to delete the old cluster and create a new one. See Single-Node Clusters on vSphere for information about
The upgrade process upgrades the version of Kubernetes in all of the control plane and worker nodes of your workload clusters.
To see an interactive list of available management clusters and select the management cluster that manages the clusters that you want to upgrade, run the
tanzu login command:
To list your workload clusters, run:
tanzu cluster list --include-management-cluster -A
tanzu cluster list command with the
--include-management-cluster -A options shows the version of Kubernetes that is running in the management cluster and all of the clusters that it manages. In this example, you can see that the management cluster has already been upgraded to v1.25.7, but the workload clusters are running older versions of Kubernetes.
NAME NAMESPACE STATUS CONTROLPLANE WORKERS KUBERNETES ROLES PLAN TKR k8s-1-23-16-cluster default running 1/1 1/1 v1.23.16+vmware.1 <none> dev v1.23.16---vmware.1-tkg.1 k8s-1-24-10-cluster default running 1/1 1/1 1.24.10+vmware.1 <none> dev 1.24.10---vmware.1-tkg.1 mgmt-cluster tkg-system running 1/1 1/1 v1.25.7+vmware.1 management dev v1.25.7---vmware.1-tkg.1
To discover which versions of Kubernetes are made available by a management cluster, run the
tanzu kubernetes-release get command:
tanzu kubernetes-release get
The output lists all of the versions of Kubernetes that you can use to deploy clusters, with the following notes:
COMPATIBLE: The current management cluster can deploy workload clusters with this Tanzu Kubernetes release (
UPDATES AVAILABLE: This
tkris not the most current in its Kubernetes version line. Any workload clusters running this
tkrversion can be upgraded to newer versions.
NAME VERSION COMPATIBLE ACTIVE UPDATES AVAILABLE v1.23.16---vmware.1-tkg.1 v1.23.16+vmware.1-tkg.1 True True v1.24.11---vmware.1-tkg.1 v1.24.11+vmware.1-tkg.1 True True v1.25.7---vmware.1-tkg.1 v1.25.7+vmware.1-tkg.1 True True
To discover the newer
tkr versions to which you can upgrade a workload cluster running an older
tkr version, run the
tanzu kubernetes-release available-upgrades get command, specifying the current
tanzu kubernetes-release available-upgrades get 1.22.17---vmware.1-tkg.1
This command lists all of the available Kubernetes versions to which you can upgrade clusters that are running the specified version.
You can also discover the
tkr versions that are available for a specific workload cluster by specifying the cluster name in the
tanzu cluster available-upgrades get command:
tanzu cluster available-upgrades get k8s-1-23-16-cluster
This command lists all of the Kubernetes versions that are compatible with the specified cluster.
You cannot skip minor versions when upgrading your
tkr version. For example, you cannot upgrade a cluster directly from v1.23.x to v1.25.x. You must upgrade a v1.23.x cluster to v1.24.x before upgrading the cluster to v1.25.x.
If the cluster is running on Azure, set the
AZURE_CLIENT_SECRET environment variable before upgrading the cluster:
tanzu cluster upgrade CLUSTER-NAME command and enter
y to confirm. To skip the confirmation step, specify the
To upgrade the cluster to the default version of Kubernetes for this release of Tanzu Kubernetes Grid, run the
tanzu cluster upgrade command without any options. In this release, the default version is
v1.25.7. For example:
tanzu cluster upgrade k8s-1-24-10-cluster
If the cluster is not running in the
default namespace, specify the
tanzu cluster upgrade CLUSTER-NAME --namespace NAMESPACE-NAME
If an upgrade times out before it completes, run
tanzu cluster upgrade again and specify the
--timeout option with a value greater than the default of 30 minutes:
tanzu cluster upgrade CLUSTER-NAME --timeout 45m0s
Operations on Azure sometimes take longer than on other platforms. If you are upgrading clusters on Azure, routinely set the
--timeoutoption in order to avoid failures.
If multiple base VM images in your IaaS account have the same version of Kubernetes that you are upgrading to, use the
--os-name option to specify the OS you want. See Selecting an OS During Cluster Upgrade for more information.
For example, on vSphere if you have uploaded both Photon and Ubuntu OVA templates with Kubernetes v1.25.7, specify
--os-name ubuntu to upgrade your workload cluster to run on Ubuntu.
tanzu cluster upgrade CLUSTER-NAME --os-name ubuntu
Since you cannot skip minor versions of
tkr, the upgrade command fails if you try to upgrade a cluster that is more than one minor version behind the default version. For example, you cannot upgrade directly from v1.23.x to v1.25.x. To upgrade a cluster to a version of Kubernetes that is not the default version for this release of Tanzu Kubernetes Grid, specify the
--tkr option with the
NAME of the chosen version, as listed by
tanzu kubernetes-release get above. For example, to upgrade the cluster
k8s-1-23-16-cluster from v1.23.16 to v1.24.11.
tanzu cluster upgrade k8s-1-23-16-cluster --tkr v1.24.11---vmware.1-tkg.1
When the upgrade finishes, run the
tanzu cluster list command to check that the workload cluster has been upgraded:
tanzu cluster list --include-management-cluster -A
Regenerate the admin
tanzu cluster kubeconfig get CLUSTER-NAME --admin
CLUSTER-NAME is the name of the workload cluster.
If you are using an LDAP or OIDC identity provider, confirm that you can authenticate to the cluster with
kubectl. For example:
kubectl get pods -A --kubeconfig my-cluster-credentials
Upgrade any CLI-managed packages such as Contour, Fluent Bit or Prometheus that are running on your workload clusters. For more information on upgrading CLI-managed packages, see Update a Package.
If you are have installed Prometheus on a workload cluster and you upgrade the workload cluster to Kubernetes v1.25, you must upgrade Prometheus to version
2.37.0+vmware.3-tkg.1. Earlier versions of the Prometheus package, for example version
2.37.0+vmware.1-tkg.1, are not compatible with Kubernetes 1.25.
You can now continue to use the Tanzu CLI to manage your clusters. For more information, see Creating and Managing TKG 2.2 Workload Clusters with the Tanzu CLI.