Deploy Workload Clusters with Different Kubernetes Versions

Tanzu Kubernetes Grid can create workload clusters that run on:

  • A Kubernetes version that Tanzu Kubernetes Grid ships with, including the default version that the management cluster runs, or
  • A Kubernetes version that comes out after the current version of Tanzu Kubernetes Grid, and that VMware publishes a Bill of Materials (BoM) for in a public registry.

Tanzu Kubernetes Grid manages Kubernetes versions with Tanzu Kubernetes release (TKr) objects, as described in Tanzu Kubernetes Releases.

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:

  • tanzu kubernetes-release get: list all releases
  • tanzu kubernetes-release get v1.23.8: list all releases matching v1.23.8
  • tanzu kubernetes-release get v1.23.8+vmware.1: list the v1.23.8+vmware.1 release

Sample output:

$ tanzu kubernetes-release get
NAME                       VERSION                  COMPATIBLE  ACTIVE  UPDATES AVAILABLE
v1.21.14---vmware.1-tkg.1  v1.21.14+vmware.1-tkg.1  True        True    True
v1.22.11---vmware.1-tkg.1   v1.22.11+vmware.1-tkg.1   True        True    True
v1.23.8---vmware.1-tkg.1   v1.23.8+vmware.1-tkg.1   True        True    False

Note: After you have installed the v1.6 CLI but before a management cluster has been deployed or upgraded, all context-specific CLI command groups (tanzu cluster, tanzu kubernetes-release) plus all of the management-cluster plugin commands except for tanzu mc upgrade and tanzu mc create are unavailable and not included in Tanzu CLI --help output.

List Available Upgrades

To list the available upgrades for a Kubernetes release, run tanzu cluster available-upgrades get with the full name of the cluster, for example:

tanzu cluster available-upgrades get my-cluster
NAME                                   VERSION
v1.22.11---vmware.1-tkg.1               v1.22.11+vmware.1-tkg.1
v1.23.8---vmware.1-tkg.1               v1.23.8+vmware.1-tkg.1

Note: The tanzu kubernetes-release available-upgrades get command is still available and its usage is not recommended.

Activate or Deactivate a Tanzu Kubernetes release

A TKr can be deactivated or reactivated to exercise maximum control of which TKr versions are supported on the Tanzu deployment

tanzu kubernetes-release activate TKR_NAME
tanzu kubernetes-release activate v1.22.11---vmware.1-tkg.1 -v 6
Applying patch to resource v1.22.11---vmware.1-tkg.1 of type *v1alpha1.TanzuKubernetesRelease ...
tanzu kubernetes-release get v1.22.11---vmware.1-tkg.1
  NAME                              VERSION                         COMPATIBLE  ACTIVE  UPDATES AVAILABLE  
  v1.22.11---vmware.1-tkg.1          v1.22.11+vmware.1-tkg.1          True        True                       
  v1.22.11---vmware.1-tkg.1-zlatest  v1.22.11+vmware.1-tkg.1-zlatest  False       True
tanzu kubernetes-release deactivate TKR_NAME
tanzu kubernetes-release deactivate v1.22.11---vmware.1-tkg.1 -v 6
Applying patch to resource v1.22.11---vmware.1-tkg.1 of type *v1alpha1.TanzuKubernetesRelease ...

tanzu kubernetes-release get v1.22.11---vmware.1-tkg.1
  NAME                              VERSION                         COMPATIBLE  ACTIVE  UPDATES AVAILABLE  
  v1.22.11---vmware.1-tkg.1          v1.22.11+vmware.1-tkg.1          True        False                      
  v1.22.11---vmware.1-tkg.1-zlatest  v1.22.11+vmware.1-tkg.1-zlatest  False       True

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 v1.6.0 is Kubernetes v1.23.8.

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 different from the default version, 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 a 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-1dot21dot8-ubuntu-2004, k8s-1dot23dot8-ubuntu-2004.
    2. Run az vm image terms accept. For example:

      az vm image terms accept --publisher vmware-inc --offer tkg-capi --plan k8s-1dot23dot8-ubuntu-2004
  • Amazon Web Services (AWS): No action required. The Amazon Linux 2 Amazon Machine Images (AMI) that includes the supported Kubernetes versions is 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

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.

  • Deploy a Kubernetes v1.22.11 cluster to vSphere:

    tanzu cluster create my-1-21-8-cluster --tkr v1.22.11---vmware.1-tkg.1-60d2ffd
  • Deploy a Kubernetes v1.22.11 cluster to AWS or Azure:

    tanzu cluster create my-1-21-8-cluster --tkr v1.22.11---vmware.1-tkg.1-60d2ffd

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

For information about Tanzu Kubernetes releases, see Tanzu Kubernetes Releases.

Deploy a Cluster with an Alternate OS or Custom Machine Image

With out-of-the-box Tanzu Kubernetes Grid, the --tkr option to tanzu cluster create supports common Kubernetes versions running on common base machine OSes. But you can build custom machine images and TKr to create new clusters with.

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.

To deploy a cluster with an alternate OS or custom machine image, you build a custom image, create a TKr for it, and deploy clusters with it as described in Build Machine Images.

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