Deploying Standalone Management Clusters

This section summarizes how to deploy a standalone Tanzu Kubernetes Grid management cluster. Deploying a management cluster completes the Tanzu Kubernetes Grid installation process and makes Tanzu Kubernetes Grid operational.

Important
For TKG deployments to vSphere, VMware recommends that you use the vSphere with Tanzu Supervisor. Using TKG with a standalone management cluster is only recommended for the use cases listed in When to Use a Standalone Management Cluster in About TKG.

After you have performed the steps described in Install the Tanzu CLI and Kubernetes CLI for Use with Standalone Management Clusters, you can deploy management clusters to vSphere 7, vSphere 8, AWS, or Azure.

Important
On vSphere with Tanzu in vSphere 8, you can use the Tanzu CLI to connect to the built-in Supervisor and deploy TKG 2.x workload clusters, so deploying a management cluster is not required. For information, see vSphere with Tanzu Supervisor is a Management Cluster. Deploying a standalone management cluster to vSphere 8 when vSphere with Tanzu is not enabled is supported, but the preferred option is to enable vSphere with Tanzu and use the Supervisor if possible.

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.

Note
VMware recommends never deploying workloads to a standalone management cluster itself because:

Standalone management clusters and workload clusters have separate concerns.

Standalone management clusters are not backed up like workload clusters. To ensure resilience, standalone management cluster configuration is best managed as code.

Cluster Deployment Process

The following diagram shows the high-level steps for deploying management clusters and workload clusters for different IaaS providers, such as vSphere 7 and 8, AWS, and Azure, and the interfaces you use to perform them.

Deploy management cluster and workload clusters, Install Tanzu CLI, select UI or file configuration, select IaaS

Installer UI vs. CLI

You can deploy a management cluster 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 a YAML configuration file, and use it to deploy a management cluster with just the Tanzu CLI.
- This deployment method is required for management cluster configurations such as:
  - IPv6 networking
  - Dual-stack networking
  - Custom storage policies, as set by VSPHERE_STORAGE_POLICY_ID
  - Node IPAM for the management cluster
- You can create a YAML configuration file anew, or else run the installer interface, click Review Configuration > Export Configuration, and modify the configuration file that the installer interface generates.

Platforms

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

vSphere 7, if the Supervisor Cluster is not enabled.
vSphere 8, if the Supervisor is not enabled.
Amazon Web Services (AWS)
Microsoft Azure

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.

For information about the required setup for management cluster deployment to your infrastructure of choice, see Standalone Management Cluster Requirements.
When you have set up your infrastructure, see Deploy Management Clusters with the Installer Interface or Deploy Management Clusters from a Configuration File.
After you have deployed a management cluster to the platform of your choice, to check the your deployment and to register your deployed management cluster with Tanzu Mission Control, see Examine and Register a Newly-Deployed Standalone Management Cluster.
After you have deployed one or more management clusters to one or more platforms, use the Tanzu CLI to Managing Your Management Clusters.
If necessary, you can Back Up and Restore Management and Workload Cluster Infrastructure.

Management Clusters and Their Configuration Files

You deploy your management cluster by running the tanzu mc create command on the bootstrap machine. To deploy a management cluster, you must specify the --ui or --file option with tanzu mc create.

Installer Interface: tanzu mc create --ui creates the management cluster with the installer interface and saves the settings from your installer input into a cluster configuration file ~/.config/tanzu/tkg/clusterconfigs/UNIQUE-ID.yaml, where UNIQUE-ID is a generated filename. The installer also generates a Kubernetes-style, class-based object spec for the management cluster’s Cluster object, that is saved in a file with the same name as the management cluster. This class-based object spec is provided for information only. Deploying management clusters from a class-based object spec is not yet supported. For more information about cluster types in TKG 2.x, see Workload Clusters in About Tanzu Kubernetes Grid.
CLI: tanzu mc create --file creates the management cluster using a cluster configuration file. Before running tanzu mc create, you set configuration parameters, like INFRASTRUCTURE_PROVIDER, in the cluster configuration file and then pass it to the --file option. The recommended practice is to use a dedicated configuration file for every management cluster that you deploy.

You can also set configuration parameters as environment variables. If you set conflicting parameters, environment variables override configuration parameters set in the file passed to the --file option:

Local environment variables: Persist over a terminal session. These variables also override environment variables in the Tanzu CLI configuration file, ~/.config/tanzu/config.yaml.
Environment variables in ~/.config/tanzu/config.yaml, set by running tanzu config set: Persist until you unset them by running tanzu config unset.

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

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

What Happens When You Create a Management Cluster

Running tanzu mc 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 mc 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. This file also lists discovery sources for Tanzu CLI plugins, environment variables set by `tanzu config set`, and features that are activated or deactivated by default in the Tanzu CLI.	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 mc 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`	Flat cluster configuration file that `tanzu mc 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/clusterconfigs/MGMT-CLUSTER-NAME.yaml`	Class-based cluster configuration file that `tanzu mc create –ui` generates based on the flat configuration file.	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.