This topic describes how to upgrade VMware Tanzu Kubernetes Grid Integrated Edition (TKGI) from v1.16 to v1.17 on vSphere with NSX networking.
For instructions on upgrading TKGI with Flannel networking, see Upgrading Tanzu Kubernetes Grid Integrated Edition (Antrea and Flannel Networking).
Warning: Do not manually upgrade your Kubernetes version. TKGI includes the compatible Kubernetes version.
Before you upgrade, follow the procedures in Prepare to Upgrade below to plan and prepare your upgrade.
After you complete the preparation steps, continue to the procedures in Perform the Upgrade below. These steps guide you through the process of upgrading VMware Tanzu Operations Manager (Ops Manager) and the TKGI tile, importing a new stemcell, and applying the changes to your deployment.
After you complete the upgrade, follow the procedures in After the Upgrade below to verify that your upgraded TKGI deployment is running properly and to optionally upgrade NSX and vSphere.
To see a list of NSX versions compatible with TKGI v1.17, consult Product Snapshot in Release Notes for TKGI v1.17.
To prepare for upgrading Tanzu Kubernetes Grid Integrated Edition from TKGI v1.16 to TKGI v1.17:
This section describes the steps required to upgrade to TKGI v1.17:
Tanzu Kubernetes Grid Integrated Edition v1.17 supports running on NSX-T Data Center v3.2.3 or later and NSX v4.0 or later.
You cannot upgrade directly from NSX-T v3.2.2 and earlier to NSX v4.0+, but you can upgrade stepwise by following the supported upgrade paths listed in the NSX-T and NSX upgrade documentation linked below.
Note: For v4.0+, VMware NSX-T Data Center is renamed to “VMware NSX.”
To upgrade NSX to NSX-T v3.2.3 or later:
Confirm that you are upgrading NSX to a version compatible with TKGI v1.17. For a list of NSX versions compatible with TKGI v1.17, see Product Snapshot in Release Notes for TKGI v1.17.
Warning: Refer to the Release Notes for current version support, known issues, and other important information.
Confirm that your vSphere installation is on the supported version and patch for NSX.
Upload the NSX upgrade bundle using the NSX Manager and proceed with the upgrade process by following the instructions in the UI.
For more information, refer to the Upgrading NSX-T Data Center documentation.
If you made architectural changes to your NSX environment that affect TKGI, such as adding or changing a VIP address, or a load balancer for the NSX Management Cluster, update the BOSH Director and TKGI tiles with the new or updated IP addresses:
To upgrade an NSX-T v3.2 deployment to NSX v4.0 or later:
If your NSX-T v3.2 deployment uses an N-VDS host switch, as described in NSX Virtual Distributed Switch, you need to migrate your host switch to vSphere Distributed Switch (VDS) before you can upgrade to NSX v4.0 or later.
Upgrade to NSX as described in the NSX Upgrade Guide.
Each version of TKGI is compatible with multiple versions of Ops Manager. See Retrieve Product Version Compatibilities from the Tanzu API in the Broadcom Support KB to determine if your Ops Manager version is compatible with TKGI v1.17.
Warning: If you use an automated pipeline to upgrade TKGI, see Configure Automated Ops Manager and Ubuntu Jammy Stemcell for Tanzu Downloading in Configuring the Upgrade Pipeline.
To upgrade Ops Manager:
Log in to Ops Manager.
Click your user name in the top right corner and navigate to Settings > Export Installation Settings.
Click Export Installation Settings.
Log in to vCenter Server using the vSphere Client.
Shut down the Ops Manager VM.
Deploy the upgraded Ops Manager VM by following the first two steps of Deploying Ops Manager with NSX for TKGI:
Using a browser, navigate to the newly-deployed Ops Manager web interface.
On the welcome page, select Import Existing Installation.
Browse to and select the installation configuration archive you exported.
Log in to Ops Manager
Click Apply Changes.
Verify that the BOSH Director for vSphere tile shows the upgrade version.
When you upgrade TKGI, your configuration settings typically migrate to the new version automatically. To download and import a TKGI version:
Download the target version of the product from Broadcom Support.
Import the target version of the TKGI tile to the Ops Manager Installation Dashboard.
Click Review Pending Changes.
Expand the Errands dropdown and activate or deactivate Upgrade all clusters errand
Warning: Deactivating the Upgrade all clusters errand causes the TKGI version tagged in your Kubernetes clusters to fall behind the TKGI tile version. If you deactivate the Upgrade all clusters errand when upgrading the TKGI tile, you must upgrade all your Kubernetes clusters before the next TKGI upgrade.
Set the Run smoke tests errand to On. The Smoke Test errand smoke tests the TKGI upgrade by creating and deleting a test Kubernetes cluster. For more information, see Errands in Installing Tanzu Kubernetes Grid Integrated Edition on vSphere with VMware NSX.
(Optional) Configure the Smoke Test errand to use a network profile instead of the default configuration settings on the TKGI tile. For more information, see Errands in Installing Tanzu Kubernetes Grid Integrated Edition on vSphere with VMware NSX.
TKGI requires an Ubuntu Jammy Stemcell for VMware Tanzu. A Windows 2019 Windows Stemcell for VMware Tanzu is also required if you intend to create Windows worker-based clusters. For information about Windows stemcells, see Configuring Windows Worker-Based Clusters.
Warning: If you use an automated pipeline to upgrade TKGI, see Configure Automated Ops Manager and Ubuntu Jammy Stemcell for Tanzu Downloading in Configuring the Upgrade Pipeline.
If Ops Manager does not have the Ubuntu Jammy Stemcell for VMware Tanzu required for TKGI v1.17, the TKGI tile displays the message Missing stemcell. To download and import a new Ubuntu Jammy Stemcell for VMware Tanzu, follow the steps below:
On the TKGI tile, click the Missing stemcell link.
Find the compatible stemcell versions for your TKGI version as described in Retrieve Product Version Compatibilities from the Tanzu API in the Broadcom Support KB.
Navigate to the Stemcells (Ubuntu Jammy) page on Broadcom Support and download the required Stemcell for VMware Tanzu version for your IaaS.
Return to the Installation Dashboard in Ops Manager and click Stemcell Library.
On the Stemcell Library page, click Import Stemcell and select the stemcell file you downloaded from Broadcom Support.
Select the TKGI tile and click Apply Stemcell to Products.
Verify that Ops Manager successfully applied the stemcell. The stemcell version you imported and applied appears in the Staged column for TKGI.
Return to the Installation Dashboard.
To complete the upgrade of the TKGI tile:
Return to the Installation Dashboard in Ops Manager.
Click Review Pending Changes. For more information about this Ops Manager page, see Reviewing Pending Product Changes.
Click Apply Changes.
(Optional) If you activated the Upgrade all clusters errand, you can use the BOSH CLI to monitor its progress:
bosh -e MY-ENVIRONMENT log-in
from a VM that can access your TKGI deployment. For more information, see Using BOSH Diagnostic Commands in Tanzu Kubernetes Grid Integrated Edition.bosh -e MY-ENVIRONMENT tasks
.bosh task TASK-NUMBER
, replacing TASK-NUMBER
with the task number you located in the previous step.Verify that the TKGI tile shows the target version.
After you complete the upgrade to TKGI v1.17, complete the following verifications and upgrades:
Upgrade the TKGI and Kubernetes CLIs on any local machine where you run commands that interact with your upgraded version of TKGI.
To upgrade the CLIs, download and re-install the TKGI and Kubernetes CLI distributions that are provided with TKGI on Broadcom Support.
For more information about installing the CLIs, see the following topics:
If you upgraded TKGI with the Upgrade all clusters errand deactivated, the next step is to upgrade the Kubernetes clusters individually using the TKGI CLI.
Log in to the TKGI environment using the TKGI CLI.
Run the command tkgi clusters
to list all Kubernetes clusters with their current versions and status:
TKGI Version Name k8s Version Plan Name UUID
1.16.8 tkgi-cluster-1-small 1.25.16 small 0bea03c8-af47-48e8-b249-814c0bc407b9
1.16.8 tkgi-cluster-2-medium 1.25.16 medium 5d9f4501-70cb-460b-9d78-0afbc074cb8c
1.16.8 tkgi-cluster-3-large 1.25.16 large b448117a-bb6f-49de-bc9b-452588bd44ef
Upgrade each cluster one-by-one using the command tkgi upgrade-cluster CLUSTER-NAME
.
When the cluster upgrades are complete, run the command tkgi clusters
and verify that they list the target version:
TKGI Version Name k8s Version Plan Name UUID Status Action
1.17.6 tkgi-cluster-1-small 1.26.15 small 0bea03c8-af47-48e8-b249-814c0bc407b9 succeeded UPGRADE
1.17.6 tkgi-cluster-2-medium 1.26.15 medium 5d9f4501-70cb-460b-9d78-0afbc074cb8c succeeded UPGRADE
1.17.6 tkgi-cluster-3-large 1.26.15 large b448117a-bb6f-49de-bc9b-452588bd44ef succeeded UPGRADE
To verify successful upgrade, create a test cluster:
tkgi create-cluster tkgi-cluster-4-test --external-hostname tkgi-cluster-test --plan medium --num-nodes 3
Note: Use only lowercase characters when naming your cluster if you manage your clusters with Tanzu Mission Control (TMC). Clusters with names that include an uppercase character cannot be attached to TMC.
Run tkgi clusters
to verify that the new cluster is created with the appropriate version of TKGI and Kubernetes:
$ tkgi clusters
TKGI Version Name k8s Version Plan Name UUID Status Action
1.17.6 tkgi-cluster-4-test 1.26.15 medium 5d9f4501-70cb-460b-9d78-0afbc074cb8c succeeded CREATE
1.17.6 tkgi-cluster-1-small 1.26.15 small 0bea03c8-af47-48e8-b249-814c0bc407b9 succeeded UPGRADE
1.17.6 tkgi-cluster-2-medium 1.26.15 medium 5d9f4501-70cb-460b-9d78-0afbc074cb8c succeeded UPGRADE
1.17.6 tkgi-cluster-3-large 1.26.15 large b448117a-bb6f-49de-bc9b-452588bd44ef succeeded UPGRADE
After upgrading TKGI and its Kubernetes clusters to v1.17, you can upgrade vSphere to v8. This upgrade includes upgrading the vCenter Server Appliance and each ESXi host, in that order.
See Verifying Deployment Health for how to verify the health of your TKGI environment and gather information for troubleshooting cluster upgrades.