Documentation
Upgrade Management & Workload Cluster ¶
The management cluster upgrade process first upgrades the Cluster API providers for vSphere, Amazon EC2, or Azure that are running in the management cluster. Then, it upgrades the version of Kubernetes in all of the control planes and worker nodes of the management cluster.
Prerequisites ¶
vSphere: If you are upgrading clusters that run on vSphere, the appropriate base image template OVAs must be available in vSphere as VM templates. For more information, see steps 1, and 2 in the Prepare to Deploy a Management Cluster to vSphere.
Amazon EC2: If you are upgrading clusters that run on Amazon EC2, the Amazon Linux 2 Amazon Machine Images (AMI) that include the supported Kubernetes versions are publicly available to all Amazon EC2 users, in all supported AWS regions. Tanzu Community Edition automatically uses the appropriate AMI for the Kubernetes version that you specify during an upgrade.
Azure: If you are upgrading clusters that run on Azure, you must accept the terms for the new default VM image and each non-default VM image that you plan to use for your cluster VMs. To accept the terms, complete the following steps:
List all available VM images in the Azure Marketplace:
az vm image list --publisher vmware-inc --offer tkg-capi --all
Accept the terms for the new default VM image:
az vm image terms accept --urn publisher:offer:sku:version
For example, to accept the terms for k8s-1dot21dot2-ubuntu-2004, run:
az vm image terms accept --urn vmware-inc:tkg-capi:k8s-1dot21dot2-ubuntu-2004:2021.05.17
Upgrade Management Cluster ¶
Run the tanzu login command to see an interactive list of management clusters available for upgrade.
tanzu login
To change your current login context, use your up and down arrow keys to highlight a management cluster and then press Enter.
The
tanzu login
command does not automatically set the kubectl context, run the following commands to set the context.First, capture the management cluster’s kubeconfig and take note of the command for accessing the cluster in the output message:
tanzu management-cluster kubeconfig get <MGMT-CLUSTER-NAME> --admin
Set your kubectl context to the management cluster:
kubectl config use-context <MGMT-CLUSTER-NAME>-admin@<MGMT-CLUSTER-NAME>
Run the
tanzu management-cluster upgrade
command:tanzu management-cluster upgrade
--namespace #The namespace where the workload cluster was created. --os-arch #OS architecture to use during cluster upgrade. --os-name #OS name to use during cluster upgrade. --os-version #OS version to use during cluster upgrade. --timeout #Time duration to wait for an operation before timeout. --tkr #TanzuKubernetesRelease(TKr) to upgrade to.
Options for the different cloud providers are:
vSphere:
--os-name ubuntu --os-version 20.04 --os-arch amd64 --os-name photon --os-version 3 --os-arch amd64
AWS:
--os-name ubuntu --os-version 20.04 --os-arch amd64 --os-name amazon --os-version 2 --os-arch amd64
Azure:
--os-name ubuntu --os-version 20.04 --os-arch amd64 --os-name ubuntu --os-version 18.04 --os-arch amd64
When the upgrade finishes, run the
tanzu cluster list
command with the--include-management-cluster
option again to check that the management cluster has been upgraded.tanzu cluster list --include-management-cluster
You should see the management cluster is now running the new version of Kubernetes, but the workload clusters are still running previous versions of Kubernetes.
Regenerate the kubeconfig by running:
tanzu cluster kubeconfig get <MANAGEMENT-CLUSTER-NAME>
Upgrade Workload Clusters ¶
After you have upgraded a management cluster, you can upgrade workload clusters.
Run the
tanzu login
command to see an interactive list of available management clusters.tanzu login
Select a management cluster to switch the context of the Tanzu CLI. You should select the management cluster that manages the clusters you want to upgrade.
Run the
tanzu cluster list
command with the--include-management-cluster
option.tanzu cluster list --include-management-cluster
The
tanzu cluster list
command 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.22.3, but the workload clusters are running older versions of Kubernetes.NAME NAMESPACE STATUS CONTROLPLANE WORKERS KUBERNETES ROLES PLAN k8s-1-20-8-cluster default running 1/1 1/1 v1.20-8+vmware.1 <none> dev k8s-1-21-2-cluster default running 1/1 1/1 v1.21-2+vmware.1 <none> dev mgmt-cluster tkg-system running 1/1 1/1 v1.22.3+vmware.1 management dev
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 (tkr
).UPGRADEAVAILABLE
: Thistkr
is not the most current in its Kubernetes version line. Any workload clusters running thistkr
version can be upgraded to newer versions.
For example:
NAME VERSION COMPATIBLE UPGRADEAVAILABLE v1.19.16---vmware.1-tkg.1 v1.19.16+vmware.1-tkg.1 True False v1.20.8---vmware.1-tkg.1 v1.20.8+vmware.1-tkg.1 True True v1.20.12---vmware.1-tkg.1 v1.20.12+vmware.1-tkg.1 True True v1.21.2---vmware.1-tkg.1 v1.21.2+vmware.1-tkg.1 True True v1.21.6---vmware.1-tkg.1 v1.21.6+vmware.1-tkg.1 True False v1.22.3---vmware.1-tkg.1 v1.22.3+vmware.1-tkg.1 True False
To discover the newer
tkr
versions you can upgrade to, run thetanzu kubernetes-release available-upgrades get
command, specifying the current version of the cluster.tanzu kubernetes-release available-upgrades get v1.20.8---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.
NAME VERSION v1.20.12---vmware.1-tkg.1 v1.20.12+vmware.1-tkg.1 v1.21.2---vmware.1-tkg.1 v1.21.2+vmware.1-tkg.1 v1.21.6---vmware.1-tkg.1 v1.21.6+vmware.1-tkg.1
You can also discover the
tkr
versions that are available for a specific workload cluster by specifying the cluster name in thetanzu cluster available-upgrades get
command.tanzu cluster available-upgrades get k8s-1-20-8-cluster
This command lists all of the Kubernetes versions that are compatible with the specified cluster.
NAME VERSION COMPATIBLE v1.20.8---vmware.1-tkg.1 v1.20.8+vmware.1-tkg.1 True v1.20.12---vmware.1-tkg.2 v1.20.12+vmware.1-tkg.2 True v1.21.2---vmware.1-tkg.1 v1.21.2+vmware.1-tkg.1 True v1.21.6---vmware.1-tkg.1 v1.21.6+vmware.1-tkg.1 True v1.22.3---vmware.1-tkg.1 v1.22.3+vmware.1-tkg.1 True
You cannot skip minor versions when upgrading your
tkr
version. For example, you cannot upgrade a cluster directly from v1.20.x to v1.22.x. You must upgrade a v1.20.x cluster to v1.21.x before upgrading the cluster to v1.22.x.Run the
tanzu cluster upgrade
command with the following optionstanzu cluster upgrade <WORKLOAD-CLUSTER-NAME>
--namespace #The namespace where the workload cluster was created. --os-arch #OS arch to use during cluster upgrade. --os-name #OS name to use during cluster upgrade. --os-version #OS version to use during cluster upgrade. --timeout #Time duration to wait for an operation before timeout. --tkr string #TanzuKubernetesRelease(TKr) to upgrade to.
Options for the different cloud providers are:
vSphere:
--os-name ubuntu --os-version 20.04 --os-arch amd64 --os-name photon --os-version 3 --os-arch amd64
AWS:
--os-name ubuntu --os-version 20.04 --os-arch amd64 --os-name amazon --os-version 2 --os-arch amd64
Azure:
--os-name ubuntu --os-version 20.04 --os-arch amd64 --os-name ubuntu --os-version 18.04 --os-arch amd64
When the upgrade finishes, run the
tanzu cluster list
command with the--include-management-cluster
option again, to check that the workload cluster has been upgraded.tanzu cluster list --include-management-cluster
You see that the
k8s-1-20-8-cluster
andk8s-1-21-2-cluster
workload clusters are now running Kubernetes v1.21.6 and v1.22.3 respectively.NAME NAMESPACE STATUS CONTROLPLANE WORKERS KUBERNETES ROLES PLAN k8s-1-20-8-cluster default running 1/1 1/1 v1.21.6+vmware.1 <none> dev k8s-1-21-2-cluster default running 1/1 1/1 v1.22.3+vmware.1 <none> dev mgmt-cluster tkg-system running 1/1 1/1 v1.22.3+vmware.1 management dev
Regenerate the
kubeconfig
by running:tanzu cluster kubeconfig get <WORKLOAD-CLUSTER-NAME>