Upgrading Tanzu Kubernetes Grid Integrated Edition (NSX-T Networking)

Page last updated:

This topic explains how to upgrade Tanzu Kubernetes Grid Integrated Edition (TKGI) from v1.8 to v1.9 on vSphere with NSX-T networking.

For instructions on upgrading TKGI with Flannel networking, see Upgrading Tanzu Kubernetes Grid Integrated Edition (Flannel Networking).

Warning: Do not manually upgrade your Kubernetes version. TKGI includes the compatible Kubernetes version.

Overview

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 Ops Manager and the TKGI tile, importing an updated 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-T and vSphere.

Prerequisites

To see a list of NSX-T 2.5 versions compatible with TKGI v1.9, consult Product Snapshot in Release Notes for TKGI v1.9.

Prepare to Upgrade

If you have not already, complete all of the steps in Upgrade Preparation Checklist for Tanzu Kubernetes Grid Integrated Edition v1.9.

Perform the Upgrade

This section describes the steps required to upgrade to TKGI v1.9:

1. Upgrade Ops Manager
2. Download and Import TKGI v1.9
3. Download and Import Stemcells
4. Upgrade the TKGI Tile

Upgrade Ops Manager

Each version of TKGI is compatible with multiple versions of Ops Manager. See VMware Tanzu Network to determine if your Ops Manager version is compatible with TKGI v1.9.

To upgrade Ops Manager:

1. Log in to Ops Manager.

2. Click your username in the top right corner and navigate to Settings > Export Installation Settings.

3. Click Export Installation Settings.

   • Ops Manager exports an encrypted archive of your current installation configuration.
   • Later, you import this configuration into to your upgraded Ops Manager.

4. Log in to vCenter Server using the vSphere Client.

5. Shut down the Ops Manager VM.

6. Deploy the upgraded Ops Manager VM by following the first two steps of Deploying Ops Manager with NSX-T for TKGI:

   1. Step 1: Generate SSH Key Pair
   2. Step 2: Deploy Ops Manager for Tanzu Kubernetes Grid Integrated Edition

7. Using a browser, navigate to the newly-deployed Ops Manager web interface.

8. On the welcome page, select Import Existing Installation.

9. Browse to and select the installation configuration archive you exported.

10. Log in to Ops Manager

11. Click Apply Changes.

12. Verify that the BOSH Director for vSphere tile shows the target, updated version.

Download and Import TKGI v1.9

When you upgrade TKGI, your configuration settings typically migrate to the new version automatically. To download and import a TKGI version:

1. Download the target version of the product from VMware Tanzu Network.

2. Import the target version of the TKGI tile to the Ops Manager Installation Dashboard.

3. Click Review Pending Changes.

4. Expand the Errands dropdown and enable or disable Upgrade all clusters errand

   • See Deciding Between Full and Two-Phase Upgrade to decide whether to upgrade TKGI-provisioned Kubernetes clusters along with TKGI, or upgrade them later.
   • VMware recommends that you upgrade Kubernetes clusters along with TKGI if possible.
   • Enable the Upgrade all clusters errand to upgrade clusters along with TKGI.

     Warning: Disabling the Upgrade all clusters errand causes the TKGI version tagged in your Kubernetes clusters to fall behind the TKGI tile version. If you disable the Upgrade all clusters errand when upgrading the TKGI tile, you must upgrade all your Kubernetes clusters before the next TKGI upgrade.

     Note: If you are upgrading TKGI on NSX-T v2.5, you must select the Upgrade all clusters errand or plan to upgrade all clusters individually before upgrading to NSX-T v3.0.

5. Set the Run smoke tests errand to On. The errand uses the TKGI CLI to create a Kubernetes cluster and then delete it. If the creation or deletion fails, the errand fails and the installation of the TKGI tile is aborted.

Download and Import Stemcells

TKGI requires a Xenial stemcell. A stemcell for Windows 2019 is also required if you intend to create Windows worker-based clusters. For information about Windows stemcells, see Configuring Windows Worker-Based Clusters.

If Ops Manager does not have the Xenial stemcell required for TKGI v1.9, the TKGI tile displays the message Missing stemcell. To download and import a new Xenial stemcell, follow the steps below:

1. On the TKGI tile, click the Missing stemcell link.

   

2. In the Stemcell Library, locate the TKGI tile and note the required stemcell version.

3. Navigate to the Stemcells (Ubuntu Xenial) page on VMware Tanzu Network and download the required stemcell version for your IaaS.

4. Return to the Installation Dashboard in Ops Manager and click Stemcell Library.

5. On the Stemcell Library page, click Import Stemcell and select the stemcell file you downloaded from VMware Tanzu Network.

6. Select the TKGI tile and click Apply Stemcell to Products.

7. Verify that Ops Manager successfully applied the stemcell. The stemcell version you imported and applied appears in the Staged column for TKGI.

8. Return to the Installation Dashboard.

Upgrade the TKGI Tile

To complete the upgrade of the TKGI tile:

1. Return to the Installation Dashboard in Ops Manager.

2. Click Review Pending Changes. For more information about this Ops Manager page, see Reviewing Pending Product Changes.

3. Click Apply Changes.

4. (Optional) If you enabled the Upgrade all clusters errand, you can use the BOSH CLI to monitor its progress:

   1. Log in to the BOSH Director by running 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.
   2. Run bosh -e MY-ENVIRONMENT tasks.
   3. Locate the task number for the errand in the # column of the BOSH output.
   4. Run bosh task TASK-NUMBER, replacing TASK-NUMBER with the task number you located in the previous step.

5. Verify that the TKGI tile is updated to the target version.

After the Upgrade

After you complete the upgrade to TKGI v1.9, complete the following verifications and upgrades:

• Update the TKGI and Kubernetes CLIs
• Upgrade Kubernetes Clusters if Needed
• Verify TKGI Upgrade
• (Optional) Upgrade NSX-T Data Center v2.5 to v3.0
• (Optional) Upgrade to vSphere 7

Update the TKGI and Kubernetes CLIs

Update the TKGI and Kubernetes CLIs on any local machine where you run commands that interact with your upgraded version of TKGI.

To update your CLIs, download and re-install the TKGI and Kubernetes CLI distributions that are provided with TKGI on VMware Tanzu Network.

For more information about installing the CLIs, see the following topics:

• Installing the TKGI CLI

• Installing the Kubernetes CLI

Upgrade Kubernetes Clusters if Needed

If you upgraded TKGI with the Upgrade all clusters errand disabled, the next step is to upgrade the Kubernetes clusters individually using the TKGI CLI.

1. Log in to the TKGI environment using the TKGI CLI.

2. Run the command tkgi clusters to list all Kubernetes clusters with their current versions and status:

   TKGI Version     Name                      k8s Version  Plan Name  UUID                                  Status     Action
   1.8.0  tkgi-cluster-1-small       1.17.5       small      0bea03c8-af47-48e8-b249-814c0bc407b9  succeeded  CREATE
   1.8.0  tkgi-cluster-2-medium      1.17.5       medium     5d9f4501-70cb-460b-9d78-0afbc074cb8c  succeeded  CREATE
   1.8.0  tkgi-cluster-3-large       1.17.5       large      b448117a-bb6f-49de-bc9b-452588bd44ef  succeeded  CREATE
   

3. Update each cluster one-by-one using the command tkgi upgrade-cluster CLUSTER-NAME.

   • You do not have to wait for each upgrade to complete before upgrading the next one.
   • The advantage of running each upgrade separately is that it makes troubleshooting easier. BOSH assigns a unique task ID to each cluster upgrade.

4. 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.9.0  tkgi-cluster-1-small       1.18.8       small      0bea03c8-af47-48e8-b249-814c0bc407b9  succeeded  UPGRADE
   1.9.0  tkgi-cluster-2-medium      1.18.8       medium     5d9f4501-70cb-460b-9d78-0afbc074cb8c  succeeded  UPGRADE
   1.9.0  tkgi-cluster-3-large       1.18.8       large      b448117a-bb6f-49de-bc9b-452588bd44ef  succeeded  UPGRADE
   

Verify TKGI Upgrade

1. 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.

2. 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.9.0  tkgi-cluster-4-test        1.18.8       medium     5d9f4501-70cb-460b-9d78-0afbc074cb8c  succeeded  CREATE
   1.9.0  tkgi-cluster-1-small       1.18.8       small      0bea03c8-af47-48e8-b249-814c0bc407b9  succeeded  UPGRADE
   1.9.0  tkgi-cluster-2-medium      1.18.8       medium     5d9f4501-70cb-460b-9d78-0afbc074cb8c  succeeded  UPGRADE
   1.9.0  tkgi-cluster-3-large       1.18.8       large      b448117a-bb6f-49de-bc9b-452588bd44ef  succeeded  UPGRADE
   

Upgrade NSX-T Data Center v2.5 to v3.0

Warning: Refer to the Release Notes for current version support, known issues, and other important information.

If you are using NSX-T v2.5, you can upgrade to NSX-T v3.0. For a list of NSX-T 2.5 and 3.0 versions compatible with TKGI v1.9, see Product Snapshot in Release Notes for TKGI v1.9.

1. Confirm that you have upgraded all TKGI-provisioned Kubernetes clusters to TKGI v1.9 using Upgrade all clusters errand in Ops Manager or using the TKGI CLI.

   Note: This updates your Kubernetes clusters to the version of Kubernetes and version of NCP that are included with TKGI v1.9.

2. Confirm that your vSphere v6.5, v6.7, or v7.0 installation is on the supported version and patch for NSX-T v3.0.

   • Refer to the VMware Product Interoperability Matrices.
   • If necessary, update to the required vSphere version or patch before proceeding with the upgrade of NSX-T.

3. Upload the NSX-T upgrade bundle using the NSX-T Manager and proceed with the upgrade process by following the instructions in the UI.

   

   For more information, refer to the NSX-T Data Center Upgrade Guide documentation.

4. If you made architectural changes to your NSX-T environment that affect TKGI, such as adding or updating a VIP address, or a load balancer for the NSX-T Management Cluster, update the BOSH Director and TKGI tiles with the new or updated IP addresses:

   • In the BOSH Director tile > vCenter Configuration pane, update NSX Address and NSX CA Cert.
   • In the TKGI tile > Networking pane, update NSX Manager hostname and NSX Manager CA Cert.
   • After making any updates to the BOSH Director or TKGI tiles:
     1. On the Installation Dashboard in Ops Manager, click Review Pending Changes.
     2. Expand the Errands list for TKGI.
     3. Ensure that the Upgrade all clusters errand is selected.
     4. Click Apply Changes.

Upgrade to vSphere 7

After upgrading TKGI and its Kubernetes clusters to v1.9 and NSX-T to v3.0, you can upgrade vSphere to v7. This upgrade includes upgrading the vCenter Server Appliance and each ESXi host, in that order.

1. Upgrade vCenter. Refer to Upgrading the vCenter Server Appliance in the vCenter documentation.
2. Upgrade each ESXi host, one at a time.
   • Put the ESXi host into maintenance mode.
   • Upgrade the ESXi host. Refer to Upgrading ESXi hosts in the vSphere documentation.
   • Using the NSX-T Manager web interface for Transport Nodes, install the vSphere 7.0 VIBS onto the ESXi host.
   • Using the NSX Manage web interface, verify that the ESXi host is in a “Success” state. If it is not, click the Resolve button.
   • Remove the ESXi host from maintenance mode.
   • Repeat the process for each ESXi host in your vCenter cluster that is part of your TKGI domain.

Troubleshoot the Upgrade

See Verifying Deployment Health for how to verify the health of your TKGI environment and gather information for troubleshooting cluster upgrades.