This topic describes how to use the Tanzu Kubernetes Grid CLI to deploy a management cluster to vSphere from a YAML file.

Prerequisites

  • Make sure that you have met the all of the requirements listed in Set Up the Bootstrap Environment for Tanzu Kubernetes Grid and Prepare to Deploy the Management Cluster to vSphere.
  • It is strongly recommended to use the Tanzu Kubernetes Grid installer interface rather than the CLI to deploy your first management cluster to vSphere. When you deploy a management cluster by using the installer interface, it populates the config.yaml file for the management cluster with the required parameters. You can use the created config.yaml as a model for future deployments from the CLI.

    If this is the first time that you are running Tanzu Kubernetes Grid commands on this machine, and you have not already deployed a management cluster to vSphere by using the Tanzu Kubernetes Grid installer interface, open a terminal and run the tkg get management-cluster command.

    tkg get management-cluster
    

    Running a tkg command for the first time creates the $HOME/.tkg folder, that contains the management cluster configuration file config.yaml.

Procedure

IMPORTANT:

Do not run multiple management cluster deployments on the same bootstrap environment machine at the same time. Do not change context or edit the kubeconfig file while Tanzu Kubernetes Grid operations are running.

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.

  1. Open the .tkg/config.yaml file in a text editor.

    If you have already deployed a management cluster to vSphere from the installer interface, you will see variables that describe your previous deployment.

    If you have not already deployed a management cluster to vSphere from the installer interface, copy and paste the following rows into the configuration file, after the end of the images section.

    VSPHERE_SERVER: 
    VSPHERE_USERNAME:
    VSPHERE_PASSWORD: 
    VSPHERE_DATACENTER:
    VSPHERE_DATASTORE:
    VSPHERE_NETWORK:
    VSPHERE_RESOURCE_POOL: 
    VSPHERE_FOLDER:
    VSPHERE_TEMPLATE:
    VSPHERE_HAPROXY_TEMPLATE:
    VSPHERE_DISK_GIB:
    VSPHERE_NUM_CPUS:
    VSPHERE_MEM_MIB: 
    VSPHERE_SSH_AUTHORIZED_KEY:
    SERVICE_CIDR:  
    CLUSTER_CIDR: 
    
  2. Edit the configuration file to update the information about the target vSphere environment and the configuration of the management cluster to deploy.

    The table below describes all of the configuration options that you must provide for deployment of the management cluster to vSphere. Leave a space between the colon (:) and the variable value. For example:

    VSPHERE_USERNAME: administrator@vsphere.local
    

    Option Value Description
    VSPHERE_SERVER: vCenter_Server_address The IP address or FQDN of the vCenter Server instance on which to deploy the management cluster.
    VSPHERE_USERNAME: administrator@vsphere.local A vSphere user account with administrator privileges.
    VSPHERE_PASSWORD: My_P@ssword! The password for the vSphere user account. This value is base64-encoded when you run tkg init.
    VSPHERE_DATACENTER: datacenter_name The name of the datacenter in which to deploy the management cluster, as it appears in the vSphere inventory.
    VSPHERE_DATASTORE: datastore_name The name of the vSphere datastore for the management cluster to use, as it appears in the vSphere inventory.
    VSPHERE_NETWORK: VM Network The name of an existing vSphere network to use as the Kubernetes service network, as it appears in the vSphere inventory.
    VSPHERE_RESOURCE_POOL: resource_pool_name The name of an existing resource pool in which to place this Tanzu Kubernetes Grid instance, as it appears in the vSphere inventory. To use the root resource pool for a cluster, enter the full path, for example for a cluster named cluster0 in datacenter dc0, the full path is /dc0/host/cluster0/Resources.
    VSPHERE_FOLDER: VM_folder_name The name of an existing VM folder in which to place Tanzu Kubernetes Grid VMs, as it appears in the vSphere inventory.
    VSPHERE_TEMPLATE: photon-3-v1.17.3+vmware.1 The VM template in the vSphere inventory from which to bootstrap management cluster VMs. In this release, it is photon-3-v1.17.3+vmware.1.
    VSPHERE_HAPROXY_TEMPLATE: photon-3-capv-haproxy-v0.6.2+vmware.1 The VM template in the vSphere inventory from which to bootstrap API server load balancer VMs. In this release, it is capv-haproxy-v0.6.1.
    VSPHERE_DISK_GIB: "30" The size in gigabytes of the disk for the control plane node VMs. Include the quotes ("").
    VSPHERE_NUM_CPUS: "1" The number of CPUs for the control plane node VMs. Include the quotes ("").
    VSPHERE_MEM_MIB: "2048" The amount of memory in megabytes for the control plane node VMs. Include the quotes ("").
    VSPHERE_SSH_AUTHORIZED_KEY: "ssh-rsa AAAAB3NzaC1yc2EAA [...] lYImkx21vUu58cj" Paste in the contents of the SSH public key that you created in Prepare to Deploy the Management Cluster to vSphere.
    SERVICE_CIDR: 100.64.0.0/13 The CIDR range to use for the Kubernetes services. The recommended range is 100.64.0.0/13. Change this value only if the recommended range is unavailable.
    CLUSTER_CIDR: 100.96.0.0/11 The CIDR range to use for pods. The recommended range is 100.96.0.0/11. Change this value only if the recommended range is unavailable.

  3. Save the configuration file.

  4. Run the tkg init command.

    • You must specify at least the --infrastructure=vsphere option. If you do not specify a name, Tanzu Kubernetes Grid automatically generates a unique name for the cluster.
      tkg init --infrastructure=vsphere
    • You can optionally specify a name for the management cluster in the --name option.
      tkg init --infrastructure=vsphere --name=management_cluster_name
    • To deploy a management cluster with a single control plane node, add the --plan=dev option. If you do not specify --plan, the dev plan is used by default.
      tkg init --infrastructure=vsphere --name management_cluster_name --plan=dev
    • To deploy a highly available management cluster with three control plane nodes, specify the --plan=prod option.
      tkg init --infrastructure=vsphere --name=management_cluster_name --plan=prod
    • By default Tanzu Kubernetes Grid creates $HOME/.tkg and creates the cluster configuration file, config.yaml in that folder. To create config.yaml in a different location or with a different name, specify the --config option. If you specify the --config option, Tanzu Kubernetes Grid only creates the YAML file in the specified location. Other files are still created in the $HOME/.tkg folder.
      tkg init --infrastructure=vsphere --name=management_cluster_name --config path_to_file/my-config.yaml

    NOTES:

    • If you connect to a vSphere 7.0 instance and the vSphere with Kubernetes feature is enabled, the CLI informs you that deploying a Tanzu Kubernetes Grid management cluster is not possible and exits.
    • If you connect to a vSphere 7.0 instance and the vSphere with Kubernetes feature is not enabled, the CLI informs you that deploying a Tanzu Kubernetes Grid management cluster is possible but not recommended. You can either quit the installation and enable the vSphere with Kubernetes feature, or you can choose to continue with this unsupported installation configuration.
  5. Follow the progress of the deployment of the management cluster in the terminal.

    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 environment. Subsequent runs do not require this step, so are faster.

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.

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