Creating Clusters
Page last updated:
This topic describes how to create a Kubernetes cluster with Pivotal Container Service (PKS) using the PKS Command Line Interface (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, 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, or vSphere without NSX-T, you can create a load balancer using your cloud provider console.
For more information about configuring a cluster load balancer, see the following:
- Creating and Configuring a GCP Load Balancer for PKS Clusters
- Creating and Configuring an AWS Load Balancer for PKS Clusters
- Creating and Configuring an Azure Load Balancer for PKS Clusters
Create the 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
See Log in to the PKS CLI for more information about thepks login
command.Run the following command to create a cluster:
pks create-cluster CLUSTER-NAME \ --external-hostname HOSTNAME \ --plan PLAN-NAME \ [--num-nodes WORKER-NODES] \ [--network-profile NETWORK-PROFILE-NAME]
Replace the placeholder values in the command as follows:CLUSTER-NAME
: Enter a 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 theCLUSTER-NAME
string, but cluster creation fails if one or more special characters are present.HOSTNAME
: Enter an 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
or10.0.0.1
. If you created an external load balancer, use its IP address.PLAN-NAME
: Choose a plan for your cluster. Runpks plans
to list your available plans.- (Optional)
WORKER-NODES
: Choose the number of worker nodes for the cluster. - (Optional) (NSX-T only)
NETWORK-PROFILE-NAME
: Specify the name of the network profile to use for the cluster. See Using Network Profiles (NSX-T Only) for more information.
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 PKS 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.
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.
Track the cluster creation process by running
pks cluster CLUSTER-NAME
. ReplaceCLUSTER-NAME
with 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 value for Last Action State iserror
, troubleshoot cluster creation by logging in to the BOSH Director and runningbosh tasks
. See Advanced Troubleshooting with the BOSH CLI for more information.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 thepks cluster CLUSTER-NAME
command.
- Specify the hostname or FQDN and register the FQDN with the IP provided by PKS after cluster deployment. You can do this using
- For vSphere without NSX-T and AWS, 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.
- For vSphere with NSX-T, choose one of the following:
To access your cluster, run
pks get-credentials CLUSTER-NAME
. This command creates a localkubeconfig
that allows you to manage the cluster. For more information about thepks get-credentials
command, see Retrieving Cluster Credentials and Configuration.Run
kubectl cluster-info
to confirm you can access your cluster using the Kubernetes CLI.
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. 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
See Log in to the PKS CLI for more information about thepks login
command.To locate the cluster ID and master node IP addresses, run
pks cluster CLUSTER-NAME
. 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, SSH into the Ops Manager VM, and use the BOSH CLI to log in to the BOSH Director from the Ops Manager VM. For more information, see Advanced Troubleshooting with the BOSH CLI.
Identify the name of your cluster deployment. For example:
$ bosh -e pks deployments
Your cluster deployment name begins withservice-instance
and includes the UUID you located in a previous step.Identify the master VM IDs by listing the VMs in your cluster. For example:
$ bosh -e pks -d service-instance-aa1234567bc8de9f0a1c vms
Your master VM IDs appear in the VM CID column.Use the information you gathered in this procedure to configure your load balancer backend. For example, if you use GCP, use the master VM IDs from the previous step in Reconfiguring a GCP Load Balancer.
Please send any feedback you have to pks-feedback@pivotal.io.