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, Amazon EC2, or Azure.

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

  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.1 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 macOS, download VMware Tanzu Kubernetes Grid CLI Mac.
    • For Windows, download VMware Tanzu Kubernetes Grid CLI Windows.
  4. (Optional) Verify that your downloaded file is unaltered from the original. Tanzu Kubernetes Grid provides a SHA-1, a SHA-256, and an MD5 checksum for each download. To obtain these checksums, click Read more under the entry that you want to download. For more information, see Using Cryptographic Hashes.

  5. Unpack the Tanzu Kubernetes Grid CLI binary for your operating system. To unpack the binary, use the extraction tool of your choice. For example, the tar -xzvf command.

    • For Linux, unpack tkg-linux-amd64-v1.2.1-vmware.1.tar.gz.
    • For macOS, unpack tkg-darwin-amd64-v1.2.1-vmware.1.tar.gz.
    • For Windows, unpack tkg-windows-amd64-v1.2.1-vmware.1.tar.gz.

    In the tkg folder, the unpacked CLI file is tkg-darwin-amd64-v1.2.1+vmware.1, tkg-linux-amd64-v1.2.1+vmware.1, or tkg-windows-amd64-v1.2.1+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.

  6. Navigate to the Tanzu Kubernetes Grid CLI binary that you unpacked.

  7. Rename the CLI binary for your platform to tkg and make it available to the system:

    • For macOS and Linux platforms:

      1. Move the binary to /usr/local/bin:
        mv ./tkg-linux-amd64-v1.2.1+vmware.1 /usr/local/bin/tkg
        mv ./tkg-darwin-amd64-v1.2.1+vmware.1 /usr/local/bin/tkg
      2. Confirm that the binary is executable by running the ls command.
    • For Windows platforms:

      1. Rename tkg-windows-amd64-v1.2.1+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.

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

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 v1.2.1 adds support for Kubernetes v1.19.3, v1.18.10 and v1.17.13. You can also use Tanzu Kubernetes Grid v1.2.1 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.1.

  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.3: Photon v3 Kubernetes v1.19.3 OVA
    • Kubernetes v1.18.10: Photon v3 Kubernetes v1.18.10 OVA
    • Kubernetes v1.17.13: Photon v3 Kubernetes v1.17.13 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.

VMware Cloud on AWS SDDC Compatibility

If you are upgrading Tanzu Kubernetes clusters that are deployed on VMware Cloud on AWS, verify that the underlying Software-Defined Datacenter (SDDC) version used by your existing deployment is compatible with the version of Tanzu Kubernetes Grid you are upgrading to.

To view the version of an SDDC, select View Details on the SDDC tile in VMware Cloud Console and click on the Support pane.

To validate compatibility with Tanzu Kubernetes Grid, refer to the VMware Product Interoperablity Matrix.

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 Deploying Tanzu Kubernetes Grid in an Internet-Restricted 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.

Prepare to Upgrade Clusters on Azure

Before upgrading a Tanzu Kubernetes Grid deployment on Azure, you must accept the terms for the new default VM image and for each non-default VM image that you plan to use for your cluster VMs. You need to accept these terms once per subscription.

To accept the terms:

  1. List all available VM images for Tanzu Kubernetes Grid in the Azure Marketplace:

    az vm image list --publisher vmware-inc --offer tkg-capi --all
    
  2. 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 the default VM image in Tanzu Kubernetes Grid v1.2.1, k8s-1dot19dot3-ubuntu-1804, run:

    az vm image terms accept --urn vmware-inc:tkg-capi:k8s-1dot19dot3-ubuntu-1804:2020.11.05
    
  3. If you plan to upgrade any of your Tanzu Kubernetes Grid clusters to a non-default Kubernetes version, such as v1.18.10 or v1.17.13, accept the terms for each non-default version that you want to use for your cluster VMs.

Upgrade the Tanzu Kubernetes Grid Extensions

If you implemented any or all of the Tanzu Kubernetes Grid extensions in version v1.1.x, you must upgrade them to 1.2.x. For information about how to upgrade the extensions, see Upgrade Tanzu Kubernetes Grid Extensions from 1.1.x to 1.2.x.

If you implemented any or all of the Tanzu Kubernetes Grid extensions in version v1.2.0, no action is required to upgrade the extensions to v1.2.1. Any extensions that you deployed with v1.2.0 will continue to function normally after you upgrade the clusters to the new version of Kubernetes.

Upgrade Crash Recovery and Diagnostics

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, Amazon EC2, and Azure. 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