This topic describes how to use the Tanzu Kubernetes Grid installer interface to deploy a management cluster to a vSphere instance. The Tanzu Kubernetes Grid installer interface guides you through the deployment of the management cluster, and provides different configurations for you to select or reconfigure. If this is the first time that you are deploying a management cluster, it is recommended to use the installer interface.


Make sure that you have met the all of the requirements listed in Install the Tanzu Kubernetes Grid CLI and Deploy Management Clusters to vSphere. If you are deploying clusters in an internet-restricted environment, you must also perform the steps in Deploying Tanzu Kubernetes Grid in an Internet-Restricted Environment.


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

  1. On the machine on which you downloaded and installed the Tanzu Kubernetes Grid CLI, run the tkg init command with the --ui option.

    tkg init --ui

    The installer interface launches in a browser and takes you through steps to configure the management cluster.

    • To make the installer interface appear locally if you are SSH-tunneling in to the bootstrap machine or X11-forwarding its display, you may need to run tkg init --ui with the –-browser none option described in Installer Interface Options below.

    The tkg init command uses and modifies settings in a cluster configuration file, which defaults to $HOME/.tkg/config.yaml. The command may overwrite values from previous invocations of tkg init unless you specify a file with a different name or location by using the --config option. For more information, see Management Clusters and config.yaml in the Manage Your Management Clusters topic.

    tkg init --ui --config /path/my-config.yaml

    By default Tanzu Kubernetes Grid saves the kubeconfig for all management clusters in the $HOME/.kube-tkg/config.yaml file. If you want to keep the kubeconfig file for a management cluster separate from the kubeconfig file for other management clusters, for example so that you can share it, specify the --kubeconfig command.

    tkg init --ui --kubeconfig /path/my-kubeconfig.yaml

    Specifying the --kubeconfig flag does not modify the location of the kubeconfig file of the bootstrap cluster created by kind. The default location of the kubeconfig file for the temporary cluster is a uniquely generated filename under $HOME/.kube-tkg/tmp/. If you want to use an existing bootstrap cluster to create a management cluster, see Use an Existing Boostrap Cluster.

    When you run the tkg init --ui command, it validates that your system meets the prerequisites:

    • NTP is running on the bootstrap machine on which you are running tkg init and on the hypervisor.
    • A DHCP server is available.
    • The CLI can connect to the location from which it pulls the required images.
    • Docker is running.

    If the prerequisites are met, tkg init --ui launches the Tanzu Kubernetes Grid installer interface.

    By default, tkg init --ui opens the installer interface locally, at in your default browser. The Installer Interface Options section below explains how you can change where the installer interface runs, including running it on a different machine from the tkg CLI.

    Tanzu Kubernetes Grid installer interface welcome page with Deploy to vSphere button

  2. Click the Deploy button for vSphere.

  3. In the IaaS Provider section, enter the IP address or fully qualified domain name (FQDN) for the vCenter Server instance on which to deploy the management cluster.

    Tanzu Kubernetes Grid does not support IPv6 addresses. This is because upstream Kubernetes only provides alpha support for IPv6. Always provide IPv4 addresses in the procedures in this topic.

  4. Enter the vCenter Single Sign On username and password for a user account that has the required privileges for Tanzu Kubernetes Grid operation, and click Connect.

    Configure the connection to vSphere

    Tanzu Kubernetes Grid Service on vSphere 7

    On vSphere 7, the Supervisor Cluster deployable with the vSphere with Tanzu option provides a better experience than a management cluster deployed by Tanzu Kubernetes Grid, and you can use the TKG CLI to connect to the Supervisor Cluster. For information, see Use the Tanzu Kubernetes Grid CLI with a vSphere with Tanzu Supervisor Cluster.

    To reflect the recommendation for Tanzu Kubernetes Grid Service, the Tanzu Kubernetes Grid installer behaves as follows:

    • With vSphere with Tanzu enabled: The installer informs you that deploying a management cluster is not possible, and exits.
    • Without vSphere with Tanzu enabled: The installer informs you that deploying a Tanzu Kubernetes Grid management cluster is possible but not recommended, and presents a choice:
      • Configure vSphere with Tanzu opens the vSphere Client so you can configure your Supervisor Cluster as described in Enable the Workload Management Platform with the vSphere Networking Stack in the vSphere documentation.
      • Deploy the Management Cluster deploys a management cluster, against recommendation for vSphere 7, but as required for VMware Cloud on AWS and Azure VMware Solution.

    Deploy management cluster to vSphere 7

  5. Select the datacenter in which to deploy the management cluster from the Datacenter drop-down menu.

  6. Paste the contents of your SSH public key into the text box and click Next.

    Select datacenter and provide SSH public key

  7. In the Management Cluster Settings section, select the Development or Production tile.

    • If you select Development, the installer deploys a management cluster with a single control plane node.
    • If you select Production, the installer deploys a highly available management cluster with three control plane nodes. Select Production if you plan on registering the management cluster with Tanzu Mission Control.
  8. In either of the Development or Production tiles, use the Instance type drop-down menu to select from different combinations of CPU, RAM, and storage for the control plane node VM or VMs.

    Choose the configuration for the control plane node VMs depending on the expected CPU, memory, and storage consumption of the workloads that it will run. For example, some workloads might require a large compute capacity but relatively little storage, while others might require a large amount of storage and less compute capacity. If you select an instance type in the Production tile, the instance type that you selected is automatically selected for the Worker Node Instance Type. If necessary, you can change this.

    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 Controlin the Tanzu Mission Control documentation.

    Select the control plane node configuration

  9. Optionally enter a name for your management cluster.

    If you do not specify a name, Tanzu Kubernetes Grid automatically generates a unique name. If you do specify a name, that name must be compliant with DNS hostname requirements as outlined in RFC 952 and amended in RFC 1123.

  10. Under Control Plane Endpoint, enter a static virtual IP address or FQDN for API requests to the management cluster.

    Ensure that this IP address is not in your DHCP range, but is in the same subnet as the DHCP range. If you mapped an FQDN to the VIP address, you can specify the FQDN instead of the VIP address. For more information, see Load Balancers for vSphere.

  11. Use the Worker Node Instance Type drop-down menu to select the VM instance type for the management cluster worker nodes.

    Select the configuration for the worker nodes depending on the expected CPU, memory, and storage consumption of the workloads that the cluster will run.

  12. Optionally, deselect the Machine Health Checks checkbox if you want to disable MachineHealthCheck and click Next.

    MachineHealthCheck provides node health monitoring and node auto-repair on the clusters that you deploy with this management cluster. You can enable or disable MachineHealthCheck on clusters after deployment by using the CLI. For instructions, see Configure Machine Health Checks for Tanzu Kubernetes Clusters.

    Select the cluster configuration

  13. In the Metadata section, optionally provide descriptive information about this management cluster.

    Any metadata that you specify here applies to the management cluster and to the Tanzu Kubernetes clusters that it manages, and can be accessed by using the cluster management tool of your choice.

    • Location: The geographical location in which the clusters run.
    • Description: A description of this management cluster. The description has a maximum length of 63 characters and must start and end with a letter. It can contain only lower case letters, numbers, and hyphens, with no spaces.
    • Labels: Key/value pairs to help users identify clusters, for example release : beta, environment : staging, or environment : production. For more information, see Labels and Selectors in the Kubernetes documentation.
      You can click Add to apply multiple labels to the clusters.

    Add cluster metadata

  14. In the Resources section, select vSphere resources for the management cluster to use, and click Next.

    • Select the VM folder in which to place the management cluster VMs.
    • Select a vSphere datastore for the management cluster to use.
    • Select the cluster, host, or resource pool in which to place the management cluster.

    If appropriate resources do not already exist in vSphere, without quitting the Tanzu Kubernetes Grid installer, go to vSphere to create them. Then click the refresh button so that the new resources can be selected.

    Select vSphere resources

  15. In the Kubernetes Network Settings section, configure the networking for Kubernetes services and click Next.

    • Under Network Name, select a vSphere network to use as the Kubernetes service network.
    • Review the Cluster Service CIDR and Cluster Pod CIDR ranges. If the recommended CIDR ranges of and are unavailable, update the values under Cluster Service CIDR and Cluster Pod CIDR.

    Configure the Kubernetes service network

  16. In the OS Image section, use the drop-down menu to select the OS image template to use for deploying Tanzu Kubernetes Grid VMs, and click Next.

    The drop-down menu includes all of the OS image templates that are present in your vSphere instance that meet the criteria for use as Tanzu Kubernetes Grid base OS images. The OS image template must include the correct version of Kubernetes for this release of Tanzu Kubernetes Grid. If you have not already imported a suitable OS image template to vSphere, you can do so now without quitting the Tanzu Kubernetes Grid installer. After you import it, use the Refresh button to make it available in the drop-down menu.

    Select the base OS image template

  17. In the CEIP Participation section, optionally deselect the check box to opt out of the VMware Customer Experience Improvement Program.

    You can also opt in or out of the program after the deployment of the management cluster. For information about the CEIP, see Opt in or Out of the VMware CEIP and

  18. Click Review Configuration to see the details of the management cluster that you have configured.

    When you click Review Configuration, Tanzu Kubernetes Grid populates the cluster configuration file, .tkg/config.yaml by default, with the settings that you specified in the interface. You can optionally copy the cluster configuration file without completing the deployment. You can copy the cluster configuration file to another bootstrap machine and deploy the management cluster from that machine. For example, you might do this so that you can deploy the management cluster from a bootstrap machine that does not have a Web browser.

    Review the management cluster configuration

  19. (Optional) Under CLI Command Equivalent, click the Copy button to copy the CLI command for the configuration that you specified.

    Copy CLI command

    Copying the CLI command allows you to reuse the command at the command line to deploy management clusters with the configuration that you specified in the interface. This can be useful if you want to automate management cluster deployment.

  20. (Optional) Click Edit Configuration to return to the installer wizard to modify your configuration.

  21. Click Deploy Management Cluster.

    Deployment of the management cluster can take several minutes. The first run of tkg init 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. You can follow the progress of the deployment of the management cluster in the installer interface or in the terminal in which you ran tkg init --ui. If the machine on which you run tkg init shuts down or restarts before the local operations finish, the deployment will fail. If you inadvertently close the browser or browser tab in which the deployment is running before it finishes, the deployment continues in the terminal.

    Monitor the management cluster deployment

Installer Interface Options

By default, tkg init --ui opens the installer interface locally, at in your default browser. You can use the --browser and --bind options to control where the installer interface runs:

  • --browser specifies the local browser to open the interface in.
    • Supported values are chrome, firefox, safari, ie, edge, or none.
    • Use none with --bind to run the interface on a different machine, as described below.
  • --bind specifies the IP address and port to serve the interface from.

Warning: Serving the installer interface from a non-default IP address and port could expose the tkg CLI to a potential security risk while the interface is running. VMware recommends passing in to the --bind option an IP and port on a secure network.

Use cases for --browser and --bind include:

  • If another process is already using, use --bind to serve the interface from a different local port.
  • To make the installer interface appear locally if you are SSH-tunneling in to the bootstrap machine or X11-forwarding its display, you may need to use –-browser none.
  • To run the tkg CLI and create management clusters on a remote machine, and run the installer interface locally or elsewhere:
    1. On the remote, bootstrap machine, run tkg init --ui with the following options and values:
      • --bind: an IP address and port for the remote machine
      • --browser: none
      tkg init --ui --bind --browser none
    2. On the local UI machine, browse to the remote machine's IP address to access the installer interface.

What to Do Next

  • 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.
  • For information about how to create namespaces in the management cluster, see Create Namespaces in the Management Cluster.
  • If you need 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, and how to opt in or out of the CEIP.
check-circle-line exclamation-circle-line close-line
Scroll to top icon