check-circle-line exclamation-circle-line close-line

<

After you have deployed the management cluster to either vSphere or to Amazon EC2, you can use the Tanzu Kubernetes Grid CLI to deploy Tanzu Kubernetes clusters. In Tanzu Kubernetes Grid, Tanzu Kubernetes clusters are the Kubernetes clusters in which your applications run.

To deploy Tanzu Kubernetes clusters, you run the tkg create cluster command, specifying different options to deploy the Tanzu Kubernetes clusters with different configurations.

Tanzu Kubernetes Grid automatically deploys clusters to the platform on which you deployed the management cluster. You cannot deploy clusters to Amazon EC2 from a management cluster that is running in vSphere, or the reverse. Tanzu Kubernetes Grid automatically deploys clusters from whichever management cluster you have set as the focus for the CLI by using the tkg set management-cluster command. For information about tkg set management-cluster, see Connect tkg and kubectl to Management Clusters.

To deploy clusters to a vSphere 7.0 instance on which the vSphere with Kubernetes feature is enabled, you must connect the Tanzu Kubernetes Grid CLI to the vSphere with Kubernetes Supervisor Cluster. For information about how to do this, see Connect the Tanzu Kubernetes Grid CLI to a vSphere 7.0 Supervisor Cluster.

IMPORTANT:

  • Do not change context or edit the kubeconfig file while Tanzu Kubernetes Grid operations are running.
  • By default, unless you specify the --config option to save the kubeconfig for a cluster to a specific file, all clusters that you deploy from the Tanzu Kubernetes Grid CLI are added to a shared kubeconfig file. If you delete the shared kubeconfig file, all clusters become unusable.

Prerequisites for Cluster Deployment

You have followed the procedures in Installing Tanzu Kubernetes Grid to deploy a management cluster to either vSphere or Amazon EC2, or you have a vSphere 7.0 instance on which a vSphere with Kubernetes Supervisor Cluster is running.

Tanzu Kubernetes Cluster Networking

When you use the Tanzu Kubernetes Grid CLI to deploy a Tanzu Kubernetes cluster, by default Calico networking is automatically enabled in the cluster. If you have Tanzu Kubernetes Grid Plus, other container networking interfaces (CNI) are supported.

Tanzu Kubernetes Cluster Plans

Tanzu Kubernetes Grid provides standard templates for clusters, known as plans. In this release, there are two plans for Tanzu Kubernetes clusters:

  • By default, the dev plan deploys a cluster with one control plane node and one worker node.
  • By default, the prod plan deploys a cluster with three control plane nodes and one worker node.

You can specify options to deploy clusters with different numbers of control plane and worker nodes. If you deploy a cluster with multiple control plane nodes, Tanzu Kubernetes Grid automatically enables stacked HA on the control plane. You can also change the number of nodes in a cluster after deployment by running the tkg scale cluster command on the cluster. For more information, see Scale Tanzu Kubernetes Clusters.

Tanzu Kubernetes Grid creates the individual nodes of the clusters according to the settings that you provided when you deployed the management cluster.

  • If you deployed the management cluster from the Tanzu Kubernetes Grid installer interface, nodes are created with the configuration that you set in the Control Plane Settings > Instance Type drop-down menu.
  • If you deployed the management cluster from the Tanzu Kubernetes Grid CLI, nodes are created with the configuration that you set in the following options:
    • vSphere: VSPHERE_DISK_GIB, VSPHERE_NUM_CPUS, and VSPHERE_MEM_MIB
    • Amazon EC2: CONTROL_PLANE_MACHINE_TYPE and NODE_MACHINE_TYPE

Deploy a Default Tanzu Kubernetes Cluster

To deploy a Tanzu Kubernetes cluster with the minimum default configuration, you run tkg create cluster, specifying the cluster name and the --plan=dev option.

tkg create cluster my-cluster --plan=dev

This command deploys a Tanzu Kubernetes cluster that runs the default version of Kubernetes for this Tanzu Kubernetes Grid release. The cluster consists of the following VMs or instances:

  • vSphere:
    • One control plane VM, with a name similar to my-cluster-control-plane-nj4z6.
    • One loadbalancer VM, with a name similar to my-cluster-default-lb, where default is the name of the namespace in which the cluster is running.
    • One worker node, with a name similar to my-cluster-md-0-6ff9f5cffb-jhcrh.
  • Amazon EC2:
    • One control plane instance, with a name similar to my-cluster-control-plane-d78t5.
    • One EC2 bastion instance, with the name my-cluster-bastion.
    • One worker node, with a name similar to my-cluster-md-0-2vsr4.

Preview the YAML for a Tanzu Kubernetes Cluster

To see a preview of the YAML file that Tanzu Kubernetes Grid will create when it deploys a Tanzu Kubernetes cluster, you can run the tkg create cluster command with the --dry-run option. If you specify --dry-run, Tanzu Kubernetes Grid displays the full YAML file for the cluster, but does not create the cluster.

tkg create cluster my-cluster --plan=dev --dry-run

You can add --dry-run to any of the commands described in the following sections, to see a preview of the YAML before you deploy the cluster. If you are satisfied with the displayed configuration file, run the command again without the --dry-run option, to create the cluster.

If you specify --dry-run, Tanzu Kubernetes Grid sends the YAML file for the cluster to stdout, so that you can save it for repeated future use.

tkg create cluster my-cluster --plan=dev --dry-run > my-cluster-config.yaml

NOTE: Running tkg create cluster with the --dry-run option works in the same way as running the tkg config cluster command. You can save the output of --dry-run and use it to create clusters by using kubectl apply. For information how to deploy clusters from saved YAML files and enable Calico, see Create Tanzu Kubernetes Cluster Configuration Files.

Deploy a Cluster with Multiple Worker Nodes

By default, a Tanzu Kubernetes cluster has one control plane node and one worker node. To deploy clusters with multiple worker nodes, specify the --worker-machine-count option.

tkg create cluster my-dev-cluster --plan=dev --worker-machine-count 3

This command deploys a Tanzu Kubernetes cluster that consists of the following VMs or instances:

  • vSphere:
    • One control plane VM, with a name similar to my-dev-cluster-control-plane-nj4z6.
    • One loadbalancer VM, with a name similar to my-dev-cluster-default-lb, where default is the name of the namespace in which the cluster is running.
    • Three worker nodes, with names similar to my-dev-cluster-md-0-6ff9f5cffb-jhcrh.
  • Amazon EC2:
    • One control plane instance, with a name similar to my-dev-cluster-control-plane-d78t5.
    • One EC2 bastion instance, with the name my-dev-cluster-bastion.
    • Three worker nodes, with names similar to my-dev-cluster-md-0-2vsr4.

Deploy a Cluster with a Highly Available Control Plane

If you specify --plan=prod, Tanzu Kubernetes Grid deploys a cluster with three control plane nodes and automatically implements stacked control plane HA for the cluster.

tkg create cluster my-prod-cluster --plan=prod

This command deploys a Tanzu Kubernetes cluster that consists of the following VMs or instances:

  • vSphere
    • Three control plane VMs, with names similar to my-prod-cluster-control-plane-nj4z6.
    • One loadbalancer VM, with a name similar to my-prod-cluster-default-lb, where default is the name of the namespace in which the cluster is running.
    • Three worker nodes, with names similar to my-prod-cluster-md-0-6ff9f5cffb-jhcrh.
  • Amazon EC2:
    • Three control plane instances, with names similar to my-prod-cluster-control-plane-d78t5.
    • One EC2 bastion instance, with the name my-prod-cluster-bastion.
    • Three worker nodes, with names similar to my-prod-cluster-md-0-2vsr4.

You can deploy a Tanzu Kubernetes cluster with more control plane nodes by specifying the --controlplane-machine-count option. The number of control plane nodes that you specify in --controlplane-machine-count must be uneven.

tkg create cluster cluster_name --plan=prod --controlplane-machine-count 5 --worker-machine-count 10

Deploy a Cluster in a Specific Namespace

If you have created namespaces in your Tanzu Kubernetes Grid instance, you can deploy Tanzu Kubernetes clusters to those namespaces by using the --namespace option. If you do not specify the --namespace option, Tanzu Kubernetes Grid places clusters in the default namespace. Any namespace that you identify in the --namespace option must exist in the management cluster before you run the command. For example, you might want to create different types of clusters in dedicated namespaces. For information about creating namespaces in the management cluster, see Create Namespaces in the Management Cluster.

tkg create cluster my-cluster --plan=dev --namespace my_namespace

This command deploys a default Tanzu Kubernetes cluster and places it in the designated namespace. For example, if you specify --namespace production, Tanzu Kubernetes Grid creates the Tanzu Kubernetes cluster in an existing namespace named production.

NOTE: If you have created namespaces, you must provide a unique name for all Tanzu Kubernetes clusters across all namespaces. If you provide a cluster name that is in use in another namespace in the same instance, the deployment fails with an error.

Deploy a Cluster that Runs a Different Version of Kubernetes

Each release of Tanzu Kubernetes Grid provides a default version of Kubernetes. As upstream Kubernetes releases patches or new versions, VMware makes these patches and versions available in Tanzu Kubernetes Grid patch and update releases. Each Tanzu Kubernetes Grid release supports a defined set of Kubernetes versions. For the list of Kubernetes versions that the Tanzu Kubernetes Grid 1.0.x releases support, see the Tanzu Kubernetes Grid 1.0 Release Notes.

To deploy a Tanzu Kubernetes cluster with a version of Kubernetes that is not the default for your Tanzu Kubernetes Grid release, specify the version in the --kubernetes-version option.

NOTES:

  • If you are deploying to vSphere, before you can deploy clusters that use a non-default version of Kubernetes for your version of Tanzu Kubernetes Grid, you must import the appropriate base OS OVA into vSphere and convert it to a VM template. For information about importing base OVA files into vSphere, see Import the Base Image Template into vSphere.
  • If you are deploying to AWS, the updated Amazon Linux 2 Amazon Machine Image (AMI) that includes the new Kubernetes version will be made publicly available to all Amazon EC2 users, in all supported AWS regions.
  • You can only specify a version of Kubernetes that is provided with and supported by a Tanzu Kubernetes Grid release.

tkg create cluster my-cluster --plan=dev --kubernetes-version=v1.17.y

This command deploys a Tanzu Kubernetes cluster that runs Kubernetes 1.17.y, even though by default this version of Tanzu Kubernetes Grid runs Kubernetes 1.17.x.