To upgrade Tanzu Kubernetes Grid, you download and install the new version of the Tanzu Kubernetes Grid CLI on the machine that you use as the bootstrap machine. You must also download and install other components, depending on whether you are upgrading clusters that you previously deployed to vSphere or Amazon EC2.

After you have installed the new versions of the components, you use the tkg upgrade management-cluster and tkg upgrade cluster CLI commands to upgrade clusters that you deployed with a previous version of Tanzu Kubernetes Grid.

For information about the supported upgrade paths for a Tanzu Kubernetes Grid release, see the release notes for that release.

Download and Install the New Version of the CLI

This procedure assumes that you are upgrading to Tanzu Kubernetes Grid v1.2.0.

  1. Go to https://www.vmware.com/go/get-tkg and log in with your My VMware credentials.
  2. Under Product Downloads, click Go to Downloads.
  3. Scroll to the VMware Tanzu Kubernetes Grid 1.2.0 CLI entries and click the Download Now button for the type of machine that you use as the bootstrap machine.

    • For Linux, download VMware Tanzu Kubernetes Grid CLI Linux.
    • For Mac OS, download VMware Tanzu Kubernetes Grid CLI Mac.
    • For Windows, download VMware Tanzu Kubernetes Grid CLI Windows.
  4. Use either the tar -xzvf command or the extraction tool of your choice to unpack the Tanzu Kubernetes Grid CLI binaries for your operating system:

    • For Linux, unpack tkg-linux-amd64-v1.2.0-vmware.1.tar.gz.
    • For Mac OS, unpack tkg-darwin-amd64-v1.2.0-vmware.1.tar.gz.
    • For Windows, unpack tkg-windows-amd64-v1.2.0-vmware.1.tar.gz.

    In the tkg folder, the unpacked files are tkg-darwin-amd64-v1.2.0+vmware.1, tkg-linux-amd64-v1.2.0+vmware.1, or tkg-windows-amd64-v1.2.0+vmware.1. The other files in the tkg folder, such as ytt, kapp, and kbld, are required by the Tanzu Kubernetes Grid extensions. You will need them later when you install the extensions.

  5. Navigate to the executable for the Tanzu Kubernetes Grid CLI that you unpacked.

  6. Rename the CLI binary for your platform to tkg, make sure that it is executable, and add it to your PATH.

    • Mac OS and Linux platforms:

      1. Move the binary to the /usr/local/bin folder and rename it to tkg. For example:
        mv ./tkg-linux-amd64-v1.2.0+vmware.1 /usr/local/bin/tkg
        mv ./tkg-darwin-amd64-v1.2.0+vmware.1 /usr/local/bin/tkg
      2. Make sure that the file is executable.
        chmod +x /usr/local/bin/tkg
    • Windows platforms:

      1. Rename tkg-windows-amd64-v1.2.0+vmware.1 to tkg.exe.
      2. Copy the tkg.exe binary into the Program Files\tkg folder that you created when you installed the previous release.

      The Program Files\tkg folder should already be in your path, from when you installed the previous release.

  7. Run tkg version to check that the correct version of the binary is properly installed.

    You should see information about the installed Tanzu Kubernetes Grid CLI version.

    Client:
      Version: v1.2.0
      Git commit: 05b233e75d6e40659247a67750b3e998c2d990a5
    

For information about the new commands and options that are available in the new version of the CLI, see the release notes for that release.

IMPORTANT: Due to changes in implementation betweeen Tanzu Kubernetes Grid 1.1.x and 1.2, you must upgrade all management clusters that you connect to with the upgraded instance of the Tanzu Kubernetes Grid CLI. You cannot use version 1.2 of the CLI to deploy Tanzu Kubernetes clusters from management clusters that are still on version 1.1.x.

Prepare to Upgrade Clusters on vSphere

If you are upgrading a Tanzu Kubernetes Grid deployment on vSphere, you must deploy the new versions of the Base OS Image Template OVAs into vSphere.

NOTE: Tanzu Kubernetes Grid 1.2.0 adds support for Kubernetes v1.19.1, v1.18.8 and v1.17.11. You can also use Tanzu Kubernetes Grid 1.2 to deploy clusters that run Kubernetes versions that were supported in previous releases of Tanzu Kubernetes Grid. If you want to deploy clusters with older versions of Kubernetes, do not delete the previous versions of the base OS image templates and API Server Load Balancer OVAs from your vSphere inventory. For information about the versions of Kubernetes that each Tanzu Kubernetes Grid release supports, see the release notes for that release.

This procedure assumes that you are upgrading to Tanzu Kubernetes Grid v1.2.0.

  1. Go to https://www.vmware.com/go/get-tkg and log in with your My VMware credentials.
  2. Download the new Tanzu Kubernetes Grid OVAs for node VMs.

    • Kubernetes v1.19.1: Photon v3 Kubernetes v1.19.1 OVA
    • Kubernetes v1.18.8: Photon v3 Kubernetes v1.18.8 OVA
    • Kubernetes v1.17.11: Photon v3 Kubernetes v1.17.11 OVA
  3. In the vSphere Client, right-click an object in the vCenter Server inventory and select Deploy OVF template.

  4. Select Local file, click the button to upload files, and navigate to a downloaded OVA file on your local machine.
  5. Follow the installer prompts to deploy a VM from the OVA projects-stg.registry.vmware.com/tkg.

    • Accept or modify the appliance name
    • Select the destination datacenter or folder
    • Select the destination host, cluster, or resource pool
    • Accept the end user license agreements (EULA)
    • Select the disk format and destination datastore
    • Select the network for the VM to connect to
  6. Click Finish to deploy the VM.
  7. When the OVA deployment finishes, right-click the VM and select Template > Convert to Template.
  8. In the VMs and Templates view, right-click the new template, select Add Permission, and assign your Tanzu Kubernetes Grid user, for example, tkg-user, to the template with the Tanzu Kubernetes Grid role, for example, TKG. You created this user and role in Deploy Management Clusters to vSphere.

Repeat the procedure for each of the Kubernetes versions for which you have downloaded the OVA file.

Previous versions of Tanzu Kubernetes Grid also required you to deploy an HA Proxy API server load balancer, named photon-3-haproxy-v1.x.x-vmware.1.ova. This is not required in Tanzu Kubernetes Grid v1.2.x. However, after you upgrade management clusters from 1.0.x or 1.1.x to 1.2.x, you must perform manual steps to Migrate Clusters from an HA Proxy Load Balancer to Kube-VIP.

Upgrading vSphere Deployments in an Internet-Restricted Environment

If you deployed the previous version of Tanzu Kubernetes Grid in an Internet-restricted environment, on a machine with an Internet connection, perform the steps in Prepare to Upgrade Clusters on vSphere above to install the new version of the CLI and deploy the new base OS image OVA files. Then, perform the steps in Deploy Tanzu Kubernetes Grid to an Offline Environment to run the gen-publish-images.sh and publish-images.sh scripts.

If you still have the publish-images.sh script from when you deployed the previous version of Tanzu Kubernetes Grid, you must regenerate it by running gen-publish-images.sh before you run publish-images.sh. Running gen-publish-images.sh updates publish-images.sh so that it pulls the correct versions of the components for the new version of Tanzu Kubernetes Grid and pushes them into your local private Docker registry. The gen-publish-images.sh script obtains the correct versions of the components from the YAML files that are created in the ~/.tkg/bom folder when you first run a tkg CLI command with a new version of Tanzu Kubernetes Grid.

Prepare to Upgrade Clusters on Amazon EC2

In Tanzu Kubernetes Grid versions before v1.2, Tanzu Kubernetes Grid uses the identity and access management (IAM) resources of the CloudFormation stack that you created by running the clusterawsadm command line utility. This CloudFormation stack must be present in your AWS account when you upgrade your existing clusters to Tanzu Kubernetes Grid v1.2. Do not delete the stack after upgrading the clusters.

For Tanzu Kubernetes Grid v1.2 and later, you create the required IAM resources by enabling the Automate creation of AWS CloudFormation Stack checkbox in the installer interface or by running the tkg config permissions aws command from the CLI. This replaces the clusterawsadm command line utility. For more information, see Deploy Management Clusters to Amazon EC2 with the Installer Interface or Deploy Management Clusters to Amazon EC2 with the CLI.

Upgrade the Tanzu Kubernetes Grid Extensions and Crash Recovery and Diagnostics

If you implemented any or all of the Tanzu Kubernetes Grid extensions in version 1.0.0 or 1.1.0, you upgrade the relevant management clusters and Tanzu Kubernetes clusters in the same way as you upgrade clusters without extensions. Any extensions for user authentication with Dex and Gangway, log forwarding with Fluentbit, and ingress control with Contour that you deployed with version 1.0 or 1.1.0 will continue to function normally after you upgrade the clusters. No additional action is required to upgrade the Dex, Gangway, Fluentbit, or Contour services that are running on those clusters.

For information about how to upgrade Crash Recovery and Diagnostics, see Install or Upgrade the Crash Recovery and Diagnostics Binary.

What to Do Next

Your environment is now ready for you to upgrade management clusters that you have deployed to vSphere and Amazon EC2. After you have upgraded the management cluster, you can upgrade the Tanzu Kubernetes clusters that it manages. If your deployment runs on vSphere, you must also perform manual steps to Migrate Clusters from an HA Proxy Load Balancer to Kube-VIP.

check-circle-line exclamation-circle-line close-line
Scroll to top icon