Deploy Management Clusters

This topic summarizes how to deploy a Tanzu Kubernetes Grid management cluster or designate one from vSphere with Tanzu. Deploying or designating a management cluster completes the Tanzu Kubernetes Grid installation process and makes Tanzu Kubernetes Grid operational.


After you have performed the steps described in Install the Tanzu CLI and Other Tools, you can deploy management clusters to the platforms of your choice.

NOTE: On vSphere with Tanzu, available on vSphere 7 and later, VMware recommends configuring the built-in Supervisor Cluster as a management cluster instead of using the tanzu CLI to deploy a new management cluster. Deploying a Tanzu Kubernetes Grid management cluster to vSphere 7 when vSphere with Tanzu is not enabled is supported, but the preferred option is to enable vSphere with Tanzu and use the Supervisor Cluster. For details, see vSphere with Tanzu Provides Management Cluster.

The management cluster is a Kubernetes cluster that runs Cluster API operations on a specific cloud provider to create and manage workload clusters on that provider. The management cluster is also where you configure the shared and in-cluster services that the workload clusters use.

Installer UI vs. CLI

You can deploy management clusters in two ways:

  • Run the Tanzu Kubernetes Grid installer, a wizard interface that guides you through the process of deploying a management cluster. This is the recommended method.
  • Create and edit YAML configuration files, and use them to deploy a management cluster with the CLI commands.


You can deploy and manage Tanzu Kubernetes Grid management clusters on:

You can deploy the management cluster as either a single-node control plane, for development, or as a highly-available multi-node control plane, for production environments.

Configuring the Management Cluster

You deploy your management cluster by running the tanzu management-cluster create command on the bootstrap machine. You configure the management cluster in different ways, depending on whether you specify --ui to launch the installer interface:

  • Installer Interface: UI input
  • CLI: Set configuration parameters, like AZURE_NODE_MACHINE_TYPE:
    • As local environment variables
    • In the cluster configuration file passed to the --file option

The tanzu management-cluster create command uses these sources and inputs in the following order of increasing precedence:

  1. ~/.config/tanzu/tkg/providers/config_default.yaml: This file contains system defaults, and should not be changed.
  2. With the --file option: The cluster configuration file, which defaults to ~/.config/tanzu/tkg/cluster-config.yaml. This file configures specific invocations of tanzu management-cluster create and other tanzu commands. Use different --file files to save multiple configurations.
  3. Local environment variables: Parameter settings in your local environment override settings from config files. Use them to make quick config choices without having to search and edit a config file.
  4. With the --ui option: Installer UI input. When you run tanzu management-cluster create --ui, the installer sets all management cluster configuration values from user input and ignores all other CLI options.

What Happens When You Create a Management Cluster

Running tanzu management-cluster create creates a temporary management cluster using a Kubernetes in Docker (kind) cluster on the bootstrap machine. After creating the temporary management cluster locally, Tanzu Kubernetes Grid uses it to provision the final management cluster in the platform of your choice.

In the process, tanzu management-cluster create creates or modifies CLI configuration and state files in the user’s home directory on the local bootstrap machine:

Location Content Change
/.config/tanzu/tkg/bom/ Bill of Materials (BoM) files that list specific versions of all of the packages that Tanzu Kubernetes Grid requires when it creates a cluster with a specific OS and Kubernetes version. Tanzu Kubernetes Grid adds to this directory as new Tanzu Kubernetes release versions are published. Add if not already present
/.config/tanzu/tkg/providers/ Configuration template files for Cluster API, cloud providers, and other dependencies, organized with ytt overlays for non-destructive modification. Add if not already present
/.config/tanzu/tkg/providers-TIMESTAMP-HASH/ Backups of /providers directories from previous installations. Add if not first installation
/.config/tanzu/config.yaml Names, contexts, and certificate file locations for the management clusters that the tanzu CLI knows about, and which is the current one. Add new management cluster information and set it as current.
/.config/tanzu/tkg/cluster-config.yaml Default cluster configuration file that the tanzu cluster create and tanzu management-cluster create commands use if you do not specify one with –file.
Best practice is to use a configuration file unique to each cluster.
Add empty file if not already present.
/.config/tanzu/tkg/clusterconfigs/IDENTIFIER.yaml Cluster configuration file that tanzu management-cluster create –ui writes out with values input from the installer interface.
IDENTIFIER is an unique identifier generated by the installer.
Create file
/.config/tanzu/tkg/config.yaml List of configurations and locations for the Tanzu Kubernetes Grid core and all of its providers. Add if not already present
/.config/tanzu/tkg/providers/config.yaml Similar to /.config/tanzu/tkg/config.yaml, but only lists providers and configurations in the /.config/tanzu/tkg/providers directory, not configuration files used by core Tanzu Kubernetes Grid. Add if not already present
/.config/tanzu/tkg/providers/config_default.yaml System-wide default configurations for providers.
Best practice is not to edit this file, but to change provider configs through ytt overlay files.
Add if not already present
/.kube-tkg/config Management cluster kubeconfig file containing names and certificates for the management clusters that the tanzu CLI knows about. Location overridden by the KUBECONFIG environment variable. Add new management cluster info and set the cluster as the current-context.
~/.kube/config Configuration and state for the kubectl CLI, including all management and workload clusters, and which is the current context. Add new management cluster name, context, and certificate info. Do not change current kubectl context to new cluster.

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