Multiple Kubernetes Versions

This topic explains how to list available Kubernetes versions and deploy a workload cluster with a non-default Kubernetes version.

About Kubernetes Versions

Each version of Tanzu Kubernetes Grid with a standalone management cluster provides a default and two non-default versions of Kubernetes, which you can list by running tanzu kubernetes-release get.

Tanzu Kubernetes Grid manages Kubernetes versions with Tanzu Kubernetes release (TKr) objects. A TKr specifies the OS images, core Kubernetes components, and bootstrap packages that are compatible with the Kubernetes version that is defined in the TKr. When you run tanzu cluster create with a default or a non-default TKr, Tanzu Kubernetes Grid uses the components and bootstrap packages specified in the TKr to create the cluster. It also reads your cluster configuration file to determine which of the compatible OS images to use when creating the cluster.

For a full list of supported Kubernetes versions, see Supported Kubernetes Versions in Tanzu Kubernetes Grid v2.2 in VMware Tanzu Kubernetes Grid 2.2 Release Notes.

List Available Versions

To list all available Kubernetes releases with their current compatibility and upgrade status, run tanzu kubernetes-release get with an optional version match argument, for example:

  • To list all releases, run tanzu kubernetes-release get.
  • To list all releases matching v1.24.11, run tanzu kubernetes-release get v1.23.10.
tanzu kubernetes-release get
NAME                       VERSION                  COMPATIBLE  ACTIVE  UPDATES AVAILABLE
v1.23.17---vmware.1-tkg.1  v1.23.17+vmware.1-tkg.1  True        True
v1.24.11---vmware.1-tkg.1  v1.24.11+vmware.1-tkg.1  True        True
v1.25.7---vmware.1-tkg.1  v1.25.7+vmware.1-tkg.1  True        True

List Available Upgrades

To discover the TKr versions that are available for a specific workload cluster, run tanzu cluster available-upgrades get with the full name of the cluster, for example:

tanzu cluster available-upgrades get my-cluster

Activate or Deactivate a Tanzu Kubernetes Release

A TKr can be activated or deactivated. To activate a TKr:

tanzu kubernetes-release activate TKR-NAME

For example:

tanzu kubernetes-release activate v1.22.11---vmware.1-tkg.1

To deactivate a TKr:

tanzu kubernetes-release deactivate TKR-NAME

For example:

tanzu kubernetes-release deactivate v1.22.11---vmware.1-tkg.1

Deploy a Cluster with a Non-Default Kubernetes Version

Each release of Tanzu Kubernetes Grid provides a default version of Kubernetes. The default version for Tanzu Kubernetes Grid v2.2 is Kubernetes v1.25.7.

As upstream Kubernetes releases patches or new versions, VMware publishes them in a public registry and the Tanzu Kubernetes release controller imports them into the management cluster. This lets the tanzu CLI create clusters based on the new versions.

  • To list available Kubernetes versions, see Available Kubernetes Versions above.
  • To deploy clusters that run a non-default version of Kubernetes, follow the steps below.

Publish the Kubernetes Version to your Infrastructure

On vSphere and Azure, you need to take an additional step before you can deploy clusters that run non-default versions of Kubernetes:

  • vSphere: Import the appropriate base image template OVA file into vSphere and convert it to a VM template. For information about importing base OVA files into vSphere, see Import the Base Image Template into vSphere.

  • Azure: Run the Azure CLI command to accept the license for the base OS version. Once you have accepted a license, you can skip this step in the future:

    1. Convert your target Kubernetes version listed in the output of the tanzu kubernetes-release get command into its Azure image SKU as follows:
      • Change leading v to k8s-.
      • Change . to dot in the version number.
      • Change trailing +vmware.* to -ubuntu-2004, to designate Ubuntu v20.04, the default OS version for all Tanzu Kubernetes Grid VMs on Azure.
      • Examples: k8s-1dot25dot7-ubuntu-2004, k8s-1dot23dot16-ubuntu-2004.

    2. Run az vm image terms accept. For example:

      az vm image terms accept --publisher vmware-inc --offer tkg-capi-2022-06-24 --plan k8s-1dot25dot7-ubuntu-2004

  • Amazon Web Services (AWS): No action required. The Amazon Linux 2 Amazon Machine Images (AMI) that include the supported Kubernetes versions are publicly available to all AWS users, in all supported AWS regions. Tanzu Kubernetes Grid automatically uses the appropriate AMI for the Kubernetes version that you specify.

Deploy the Kubernetes Cluster

If you are deploying a plan-based cluster, set an environment variable ALLOW_LEGACY_CLUSTER to true:

export ALLOW_LEGACY_CLUSTER=true

To deploy a workload cluster with a version of Kubernetes that is not the default for your version of Tanzu Kubernetes Grid, specify the Tanzu Kubernetes release in the --tkr option. For example, to deploy a Kubernetes v1.23.17 cluster, run:

tanzu cluster create my-1-23-17-cluster --tkr v1.23.17---vmware.1-tkg

For more details on how to create a workload cluster, see Create Workload Clusters.

Deploy a Cluster with a Custom Machine Image

For common combinations of OS version, Kubernetes version, and target infrastructure, Tanzu Kubernetes Grid with a standalone management cluster provides default machine images. You can optionally build custom machine images and TKrs.

Reasons to do this include:

  • To create clusters on a base OS that VMware supports but does not distribute, such as Red Hat Enterprise Linux (RHEL) v8.
  • To install additional packages into the base machine image, or otherwise customize it as described in Customization in the Image Builder documentation.

For instructions, see Build Machine Images.

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