You can use the Tanzu CLI to deploy a management cluster to vSphere, Amazon Elastic Compute Cloud (Amazon EC2), and Microsoft Azure with a configuration that you specify in a YAML configuration file.


Before you can deploy a management cluster, you must make sure that your environment meets the requirements for the target infrastructure provider.

General Prerequisites

  • Make sure that you have met the all of the requirements and followed all of the procedures in Install the Tanzu CLI and Other Tools.
  • For production deployments, it is strongly recommended to enable identity management for your clusters. For information about the preparatory steps to perform before you deploy a management cluster, see Prepare External Identity Management.
  • If you want to register your management cluster with Tanzu Mission Control, follow the procedure in Register Your Management Cluster with Tanzu Mission Control.
  • If you are deploying clusters in an internet-restricted environment to either vSphere or Amazon EC2, you must also perform the steps in Prepare an Internet-Restricted Environment. These steps include setting TKG_CUSTOM_IMAGE_REPOSITORY as an environment variable.
  • It is strongly recommended to use the Tanzu Kubernetes Grid installer interface rather than the CLI to deploy your first management cluster to a given infrastructure provider. When you deploy a management cluster by using the installer interface, it populates a cluster configuration file for the management cluster with the required parameters. You can use the created configuration file as a model for future deployments from the CLI to this infrastructure provider.
  • If you plan on registering the management cluster with Tanzu Mission Control, ensure that your Tanzu Kubernetes clusters meet the requirements listed in Requirements for Registering a Tanzu Kubernetes Cluster with Tanzu Mission Control in the Tanzu Mission Control documentation.
  • Read the Tanzu Kubernetes Grid 1.3.1 Release Notes for updates related to security patches.

vSphere Prerequisites

Amazon EC2 Prerequisites

Create IAM Resources

Before you deploy a management cluster to Amazon EC2 for the first time, you must create a CloudFormation stack for Tanzu Kubernetes Grid, tkg-cloud-vmware-com, in your AWS account. This CloudFormation stack includes the identity and access management (IAM) resources that Tanzu Kubernetes Grid needs to create and run clusters on Amazon EC2. For more information, see Required IAM Resources in Prepare to Deploy Management Clusters to Amazon EC2.

  1. If you have already created the CloudFormation stack for Tanzu Kubernetes Grid in your AWS account, skip the rest of this procedure.

  2. If you have not already created the CloudFormation stack for Tanzu Kubernetes Grid in your AWS account, ensure that AWS authentication variables are set either in the local environment or in your AWS default credential provider chain. For instructions, see Configure AWS Account Credentials and SSH Key.

    If you have configured AWS credentials in multiple places, the credential settings used to create the CloudFormation stack are applied in the following order of precedence:

    • Credentials set in the local environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN and AWS_REGION are applied first.
    • Credentials stored in a shared credentials file as part of the default credential provider chain. You can specify the location of the credentials file to use in the local environment variable AWS_SHARED_CREDENTIAL_FILE. If this environment variable in not defined, the default location of $HOME/.aws/credentials is used. If you use credential profiles, the command uses the profile name specified in the AWS_PROFILE local environment configuration variable. If you do not specify a value for this variable, the profile named default is used.

    For an example of how the default AWS credential provider chain is interpreted for Java apps, see Working with AWS Credentials in the AWS documentation.

  3. Run the following command:

    tanzu management-cluster permissions aws set

    For more information about this command, run tanzu management-cluster permissions aws set --help.

IMPORTANT: The tanzu management-cluster permissions aws set command replaces the clusterawsadm command line utility that existed in Tanzu Kubernetes Grid v1.1.x and earlier. For existing management and Tanzu Kubernetes clusters initially deployed with v1.1.x or earlier, continue to use the CloudFormation stack that was created by running the clusterawsadm alpha bootstrap create-stack command. For Tanzu Kubernetes Grid v1.2 and later clusters, use the tkg-cloud-vmware-com stack.

Microsoft Azure Prerequisites

Create the Cluster Configuration File

Before creating a management cluster using the Tanzu CLI, you must define its configuration in a YAML configuration file that provides the base configuration for the cluster. When you deploy the management cluster from the CLI, you specify this file by using the --file option of the tanzu management-cluster create command.

Running tanzu config init command for the first time creates the ~/.config/tanzu/tkg subdirectory that contains the Tanzu Kubernetes Grid configuration files.

If you have previously deployed a management cluster by running tanzu management-cluster create --ui, the ~/.config/tanzu/tkg/clusterconfigs directory contains management cluster configuration files with settings saved from each invocation of the installer interface. Depending the infrastructure on which you deployed the management cluster, you can use these files as templates for cluster configuration files for new deployments to the same infrastructure. Alternatively, you can create management cluster configuration files from the templates that are provided in this documentation.

  • To use the configuration file from a previous deployment that you performed by using the installer interface, make a copy of the configuration file with a new name, open it in a text editor, and update the configuration. For information about how to update all of the settings, see the Tanzu CLI Configuration File Variable Reference.
  • To create a new configuration file, see Create a Management Cluster Configuration File. This section provides configuration file templates for each infrastructure provider.

VMware recommends using a dedicated configuration file for each management cluster, with configuration settings specific to a single infrastructure.

Run the tanzu management-cluster create Command

After you have created or updated the cluster configuration file and downloaded the most recent BOM, you can deploy a management cluster by running the tanzu management-cluster create --file CONFIG-FILE command, where CONFIG-FILE is the name of the configuration file. If your configuration file is the default ~/.config/tanzu/tkg/cluster-config.yaml, you can omit the --file option. If you would like to review the Kubernetes manifest that the tanzu management-cluster create command will apply you can optionally use the --dry-run flag to print the manifest without making changes. This invocation will still run the validation checks described below before generating the Kubernetes manifest.

Warning: The tanzu management-cluster create command takes time to complete. While tanzu management-cluster create is running, do not run additional invocations of tanzu management-cluster create on the same bootstrap machine to deploy multiple management clusters, change context, or edit ~/.kube-tkg/config.

To deploy a management cluster, run the tanzu management-cluster create command. For example:

tanzu management-cluster create --file path/to/cluster-config-file.yaml

Validation Checks

When you run tanzu management-cluster create, the command performs several validation checks before deploying the management cluster. The checks are different depending on the infrastructure to which you are deploying the management cluster.

  • vSphere

    The command verifies that the target vSphere infrastructure meets the following requirements:

    • The vSphere credentials that you provided are valid.
    • Nodes meet the minimum size requirements.
    • Base image template exists in vSphere and is valid for the specified Kubernetes version.
    • Required resources including the resource pool, datastores, and folder exist in vSphere.
  • Amazon EC2

    The command verifies that the target Amazon EC2 infrastructure meets the following requirements:

    • The AWS credentials that you provided are valid.
    • Cloud Formation stack exists.
    • Node Instance type is supported.
    • Region and AZ match.
  • Azure

    The command verifies that the target Azure infrastructure meets the following requirements:

    • The Azure credentials that you provided are valid.
    • The public SSH key is encoded in base64 format.
    • The node instance type is supported.

If any of these conditions are not met, the tanzu management-cluster create command fails.

Monitoring Progress

When you run tanzu management-cluster create, you can follow the progress of the deployment of the management cluster in the terminal. The first run of tanzu management-cluster create takes longer than subsequent runs because it has to pull the required Docker images into the image store on your bootstrap machine. Subsequent runs do not require this step, so are faster.

If tanzu management-cluster create fails before the management cluster deploys, you should clean up artifacts on your bootstrap machine before you re-run tanzu management-cluster create. See the Troubleshooting Tips topic for details. If the machine on which you run tanzu management-cluster create shuts down or restarts before the local operations finish, the deployment will fail.

If the deployment succeeds, you see a confirmation message in the terminal:

Management cluster created! You can now create your first workload cluster by running tanzu cluster create [name] -f [file]

What to Do Next

  • Configure identity management: If you enabled OIDC or LDAP identity management for the management cluster, you must perform the post-deployment steps described in Configure Identity Management After Management Cluster Deployment to enable access.
  • Deploy workload clusters: Once your management cluster is created, you can deploy Tanzu Kubernetes (workload) clusters as described in Deploy Tanzu Kubernetes Clusters.
  • Deploy another management cluster: To deploy more than one management cluster, on any or all of vSphere, Azure, and Amazon EC2, see Manage Your Management Clusters. This topic also provides information about how to add existing management clusters to your CLI instance, obtain credentials, scale and delete management clusters, add namespaces, and how to opt in or out of the CEIP.

For information about what happened during the deployment of the management cluster, how to connect kubectl to the management cluster, and how to create namespaces see Examine the Management Cluster Deployment.

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