Creating Clusters

Configure Cluster Access
- vSphere with NSX-T
- GCP, AWS, Azure, or vSphere without NSX-T
Create a Kubernetes Cluster
Identify Kubernetes Cluster Master VMs
Next Steps

Page last updated:

This topic describes how to create a Kubernetes cluster with Pivotal Container Service (PKS) using the PKS Command Line Interface (PKS CLI).

Configure Cluster Access

Cluster access configuration differs by the type of PKS deployment.

vSphere with NSX-T

PKS deploys a load balancer automatically when clusters are created. The load balancer is configured automatically when workloads are being deployed on these Kubernetes clusters. For more information, see Load Balancers in PKS Deployments with NSX-T.

Note: For a complete list of the objects that PKS creates by default when you create a Kubernetes cluster on vSphere with NSX-T, see vSphere with NSX-T Cluster Objects.

GCP, AWS, Azure, or vSphere without NSX-T

When you create a Kubernetes cluster, you must configure external access to the cluster by creating an external TCP or HTTPS load balancer. This load balancer allows you to run PKS CLI commands on the cluster from your local workstation. For more information, see Load Balancers in PKS Deployments without NSX-T.

You can configure any load balancer of your choice. If you use GCP, AWS, Azure, or vSphere without NSX-T, you can create a load balancer using your cloud provider console.

For more information about configuring a PKS cluster load balancer, see the following:

Create the PKS cluster load balancer before you create the cluster. Use the load balancer IP address as the external hostname, and then point the load balancer to the IP address of the master virtual machine (VM) after cluster creation. If the cluster has multiple master nodes, you must configure the load balancer to point to all master VMs for the cluster.

If you are creating a cluster in a non-production environment, you can choose to create a cluster without a load balancer. Create a DNS entry that points to the IP address of the cluster’s master VM after cluster creation.

To locate the IP addresses and VM IDs of the master VMs, see Identify the Kubernetes Cluster Master VM below.

Create a Kubernetes Cluster

Perform the following steps:

Grant cluster access to a new or existing user in UAA. See the Grant PKS Access to a User section of Managing Users in PKS with UAA for more information.
On the command line, run the following command to log in:
```
pks login -a PKS-API -u USERNAME -k
```
Where:
- PKS-API is the domain name for the PKS API that you entered in Ops Manager >Pivotal Container Service >PKS API >API Hostname (FQDN). For example, api.pks.example.com.
- USERNAME is your user name.
  
  See Logging in to PKS for more information about the pks login command.
To create a cluster run the following command :
```
pks create-cluster CLUSTER-NAME \
--external-hostname HOSTNAME \
--plan PLAN-NAME \
[--num-nodes WORKER-NODES] \
[--network-profile NETWORK-PROFILE-NAME]
```
Where:
- CLUSTER-NAME is your unique name for your cluster.
  Note: The CLUSTER-NAME must not contain special characters such as &. The PKS CLI does not validate the presence of special characters in the CLUSTER-NAME string, but cluster creation fails if one or more special characters are present.
- HOSTNAME is your external hostname for your cluster. You can use any fully qualified domain name (FQDN) or IP address you own. For example, my-cluster.example.com or 10.0.0.1. If you created an external load balancer, use its DNS hostname.
- PLAN-NAME is the plan for your cluster. Run pks plans to list your available plans.
- (Optional) WORKER-NODES is the number of worker nodes for the cluster.
- (Optional) (NSX-T only) NETWORK-PROFILE-NAME is the network profile to use for the cluster. See Using Network Profiles (NSX-T Only) for more information.
For example:
```
$ pks create-cluster my-cluster \
--external-hostname my-cluster.example.com \
--plan large --num-nodes 3
```
Note: It can take up to 30 minutes to create a cluster.

For high availability, create clusters with a minimum of three worker nodes, or two per AZ if you intend to use PersistentVolumes (PVs). For example, if you deploy across three AZs, you should have six worker nodes. For more information about PVs, see PersistentVolumes in Maintaining Workload Uptime. Provisioning a minimum of three worker nodes, or two nodes per AZ is also recommended for stateless workloads.

The maximum value you can specify is configured in the Plans pane of the Pivotal Container Service tile. If you do not specify a number of worker nodes, the cluster is deployed with the default number, which is also configured in the Plans pane. For more information, see the Installing PKS topic for your IaaS, such as Installing PKS on vSphere.

To track cluster creation, run the following command:

pks cluster CLUSTER-NAME

WhereCLUSTER-NAME is the unique name for your cluster.

For example:

$ pks cluster my-cluster
Name:                     my-cluster
Plan Name:                large
UUID:                     01a234bc-d56e-7f89-01a2-3b4cde5f6789
Last Action:              CREATE
Last Action State:        succeeded
Last Action Description:  Instance provisioning completed
Kubernetes Master Host:   my-cluster.example.com
Kubernetes Master Port:   8443
Worker Instances:         3
Kubernetes Master IP(s):  192.168.20.7

If the Last Action State value is error, troubleshoot by performing the following procedure:
1. Log in to the BOSH Director.
2. Run the following command:
```
bosh tasks
```
  For more information, see Advanced Troubleshooting with the BOSH CLI.
Depending on your deployment:
- For vSphere with NSX-T, choose one of the following:
  - Specify the hostname or FQDN and register the FQDN with the IP provided by PKS after cluster deployment. You can do this using resolv.conf or via DNS registration.
  - Specify a temporary placeholder value for FQDN, then replace the FQDN in the kubeconfig with the IP address assigned to the load balancer dedicated to the cluster.
    
    To retrieve the IP address to access the Kubernetes API and UI services, use the pks cluster CLUSTER-NAME command.
- For vSphere without NSX-T, AWS, and Azure, configure external access to the cluster’s master nodes using either DNS records or an external load balancer. Use the output from the pks cluster command to locate the master node IP addresses and ports.
- For GCP, use the output from the pks cluster command to locate the master node IP addresses and ports, and then continue to Configure Load Balancer Backend in Configuring a GCP Load Balancer for PKS Clusters.
  Note: For clusters with multiple master node VMs, health checks on port 8443 are recommended.
To access your cluster, run the following command:
```
pks get-credentials CLUSTER-NAME
```
Where CLUSTER-NAME is the unique name for your cluster.

For example:
```
$ pks get-credentials pks-example-cluster

Fetching credentials for cluster pks-example-cluster.
Context set for cluster pks-example-cluster.

You can now switch between clusters by using:
$kubectl config use-context &ltcluster-name&gt
```
The pks get-credentials command creates a local kubeconfig that allows you to manage the cluster. For more information about the pks get-credentials command, see Retrieving Cluster Credentials and Configuration.
To confirm you can access your cluster using the Kubernetes CLI, run the following command:
```
kubectl cluster-info
```
See Managing PKS for information about checking cluster health and viewing cluster logs.

Identify Kubernetes Cluster Master VMs

Note: This section applies only to PKS deployments on GCP or on vSphere without NSX-T. Skip this section if your PKS deployment is on vSphere with NSX-T, AWS, or Azure. For more information, see Load Balancers in PKS.

To reconfigure the load balancer or DNS record for an existing cluster, you may need to locate VM ID and IP address information for the cluster’s master VMs. Use the information you locate in this procedure when configuring your load balancer backend.

To locate the IP addresses and VM IDs for the master VMs of an existing cluster, do the following:

On the command line, run the following command to log in:
```
pks login -a PKS-API -u USERNAME -k
```
Where:
- PKS-API is the domain name for the PKS API that you entered in Ops Manager >Pivotal Container Service >PKS API >API Hostname (FQDN). For example, api.pks.example.com.
- USERNAME is your user name.
  
  See Logging in to PKS for more information about the pks login command.
To locate the cluster ID and master node IP addresses, run the following command:
```
pks cluster CLUSTER-NAME
```
Where CLUSTER-NAME is the unique name for your cluster.

From the output of this command, record the following items:
- UUID: This value is your cluster ID.
- Kubernetes Master IP(s): This value lists the IP addresses of all master nodes in the cluster.
Gather credential and IP address information for your BOSH Director.
To log in to the BOSH Director, perform the following:
1. SSH into the Ops Manager VM.
2. Log in to the BOSH Director by using the BOSH CLI from the Ops Manager VM.
For information on how to complete these steps, see Advanced Troubleshooting with the BOSH CLI .
To identify the name of your cluster deployment, run the following command:
```
bosh -e pks deployments
```
Your cluster deployment name begins with service-instance and includes the UUID you located in a previous step.
To identify the master VM IDs by listing the VMs in your cluster, run the following command:
```
bosh -e pks -d CLUSTER-SI-ID vms
```
Where CLUSTER-SI-ID is your cluster service instance ID which begins with service-instance and includes the UUID you previously located.

For example:
```
$ bosh -e pks -d service-instance-aa1234567bc8de9f0a1c vms
```
Your master VM IDs are displayed in the VM CID column.
Use the master VM IDs and other information you gathered in this procedure to configure your load balancer backend. For example, if you use GCP, use the master VM IDs retrieved during the previous step in Reconfiguring a GCP Load Balancer.

Next Steps

If your PKS deployment is on AWS, you must tag your subnets with your new cluster’s unique identifier before adding the subnets to the PKS workload load balancer. After you complete the Create a Kubernetes Cluster procedure, follow the instructions in AWS Prerequisites.

Please send any feedback you have to pks-feedback@pivotal.io.

Create a pull request or raise an issue on the source for this page in GitHub