Upgrade Standalone Management Clusters

To upgrade Tanzu Kubernetes Grid with a standalone management cluster, you must first upgrade the standalone management cluster. You cannot upgrade workload clusters until you have upgraded the management cluster that manages them.

If you are running TKG with vSphere with Tanzu Supervisor, you do not follow this procedure. Instead, you upgrade the Supervisor as part of vSphere and update the Supervisor’s Kubernetes version by upgrading its TKrs.


Upgrading the management cluster automatically upgrades the auto-managed packages that it runs.


After you have installed the Tanzu CLI but before a standalone management cluster has been upgraded, all context-specific CLI command groups (tanzu cluster, tanzu kubernetes-release) are unavailable and not included in Tanzu CLI --help output.

Management clusters and workload clusters use client certificates to authenticate clients. These certificates are valid for one year. To renew them, upgrade your clusters at least once a year or rotate them manually as described in Renew Cluster Certificates (Standalone MC) or the VMware Knowledge Base article How to rotate certificates in a Tanzu Kubernetes Grid cluster.


(LDAP Only) Update LDAP Settings

Starting in Tanzu Kubernetes Grid v2.3, you must set the LDAP_BIND_DN and LDAP_BIND_PASSWORD variables when configuring an LDAP identity provider. Before upgrading a management cluster configured to use an LDAP identity provider to Tanzu Kubernetes Grid v2.5, set these variables if you have not already done so. Upgrading your management cluster without setting LDAP_BIND_DN and LDAP_BIND_PASSWORD causes the Pinniped App to fail to deploy and the App custom resource returns an error. For more information about these configuration variables, see Identity Providers - LDAP in Configuration File Variable Reference.

To update LDAP_BIND_DN and LDAP_BIND_PASSWORD, you must use the version of the management-cluster CLI plugin that corresponds to the version of your management cluster. Perform these steps before upgrading the management cluster:

  1. Add LDAP_BIND_DN and LDAP_BIND_PASSWORD to the configuration file for your management cluster.

  2. Confirm that the correct version of the management-cluster plugin is installed on your machine. For Tanzu Kubernetes Grid v2.5.1, the correct version is v0.32.2.

    tanzu plugin list

    If the correct version of the management-cluster plugin is not installed, do the following:

    1. In the list of all available versions, locate the version of the management-cluster plugin that corresponds to the version of your management cluster:

      tanzu plugin search -n management-cluster --show-details
    2. Install the plugin:

      tanzu plugin install management-cluster --version PLUGIN-VERSION

      Where PLUGIN-VERSION is the version that you located in the previous step.

  3. Generate a new secret for the Pinniped package by running:

    FILTER_BY_ADDON_TYPE=authentication/pinniped tanzu management-cluster create --dry-run -f YOUR-MANAGEMENT-CLUSTER-CONFIG-FILE.yaml > PINNIPED-PACKAGE-SECRET.yaml

    Where YOUR-MANAGEMENT-CLUSTER-CONFIG-FILE.yaml is the configuration file you updated in the previous step and PINNIPED-PACKAGE-SECRET.yaml is the new secret for the Pinniped package.

  4. Confirm that the resulting secret includes your updated settings, set the kubectl context to the management cluster, and apply the secret:

    kubectl apply -f PINNIPED-PACKAGE-SECRET.yaml


This procedure assumes that you are upgrading to Tanzu Kubernetes Grid v2.5.1.

  1. Run the tanzu context use command to see an interactive list of management clusters available for upgrade.

    tanzu context use
  2. Select the management cluster that you want to upgrade. See List Management Clusters and Change Context for more information.

  3. Get the admin credentials of the cluster. The Tanzu CLI alias mc is short for management-cluster.

    tanzu mc kubeconfig get --admin
  4. Connect kubectl to the management cluster.

    kubectl config use-context MGMT-CLUSTER-NAME-admin@MGMT-CLUSTER-NAME.

    You can copy the exact command, including the name of the management cluster context, from the output of the tanzu mc kubeconfig get --admin command that you ran in the preceding step.

  5. Run the tanzu mc upgrade command and enter y to confirm.


    After you run this command, non-admin users cannot log in to the associated workload clusters until the Pinniped pods finish restarting.

    tanzu mc upgrade

    If multiple base VM images in your IaaS account have the same version of Kubernetes that you are upgrading to, you can include --os-name and other options to specify the target OS as described in Select an OS to Upgrade To:

    tanzu mc upgrade --os-name ubuntu

    On vSphere, you can use the --vsphere-vm-template-name option to specify a target OVA template for cluster nodes as described in Select an OVA Template to Upgrade To:

    tanzu mc upgrade --vsphere-vm-template-name "/dc0/vm/tanzu/ubuntu-2204-kube-v1.28.7-vmware.1"

    To skip the confirmation step when you upgrade a cluster, specify the --yes option.

    tanzu mc upgrade --yes

    The upgrade process first upgrades the Cluster API provider for vSphere that is running in the management cluster. Then, it upgrades the version of Kubernetes in all of the control plane and worker nodes of the management cluster.


    While a management cluster is upgrading, do not run tanzu cluster or tanzu mc commands against it or the workload clusters that it manages, for example from another bootstrap machine or shell window.

    If the upgrade times out before it completes, run tanzu mc upgrade again and specify the --timeout option with a value greater than the default of 30 minutes.

    tanzu mc upgrade --timeout 45m0s

    After you have installed the v2.5.x CLI but before a management cluster has been 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.

  6. After the upgrade finishes, run the tanzu cluster list command with the --include-management-cluster -A options again to check that the management cluster has been upgraded.

    tanzu cluster list --include-management-cluster -A

    You see that the management cluster is now running the new version of Kubernetes, but that the workload clusters are still running previous versions of Kubernetes.

     k8s-1-26-8-cluster   default     running   1/1           1/1      v1.26.8+vmware.1  <none>      dev   v1.26.8---vmware.1-tkg.1
     k8s-1-27-5-cluster   default     running   1/1           1/1      v1.27.5+vmware.1  <none>       dev   v1.27.5---vmware.1-tkg.1
     mgmt-cluster         tkg-system  running   1/1           1/1      v1.28.7+vmware.1  management  dev   v1.28.7---vmware.1-tkg.1
  7. Regenerate the admin kubeconfig:

    tanzu management-cluster kubeconfig get --admin

    The following is sample output of the command:

    Credentials of cluster 'mgmt' have been saved
    You can now access the cluster by running 'kubectl config use-context mgmt-admin@mgmt'

    If you don’t renew the kubeconfig after upgrading, you won’t be able to access the cluster once it expires.

What to Do Next

You can now:

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