Create a Cluster
Page last updated:
This topic describes how to create a Kubernetes cluster with Pivotal Container Service (PKS) using the PKS Command Line Interface (CLI).
When you create a cluster, you must configure external access to the cluster by creating an external TCP or HTTPS load balancer. Create the load balancer before you create the cluster, then point the load balancer to the IP address of the master virtual machine (VM) after cluster creation.
You can configure any load balancer of your choice. If you use vSphere with NSX-T or GCP, you can create a load balancer using your cloud provider console. For information about configuring a GCP load balancer for PKS clusters, see Configuring a GCP Load Balancer for PKS Clusters.
Note: You can only configure GCP load balancers for PKS clusters deployed on GCP.
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 cluster’s master VM after cluster creation.
Perform the following steps:
Grant cluster access to a new or existing user in UAA. See the Grant Cluster Access to a User section of Manage Users in UAA for more information.
On the command line, run the following command to log in:
pks login -a PKS_API -u USERNAME -p PASSWORD --ca-cert CERT-PATHSee Log in to the PKS CLI for more information about the
Run the following command to create a cluster:
pks create-cluster CLUSTER-NAME \ --external-hostname HOSTNAME \ --plan PLAN-NAME \ [--num-nodes WORKER-NODES]Replace the placeholder values in the command as follows:
CLUSTER-NAME: Enter a unique name for your cluster.
HOSTNAME: Enter an external hostname for your cluster. You can use any fully qualified domain name (FQDN) or IP address you own. For example,
PLAN-NAME: Choose a plan for your cluster. Run
pks plansto list your available plans.
WORKER-NODES: Choose the number of worker nodes for the cluster. If you do not specify a number of worker nodes, the default value is 3. For high availability, Pivotal recommends creating clusters with at least 3 worker nodes. The maximum value is 50.
$ pks create-cluster my-cluster \ --external-hostname my-cluster.example.com \ --plan large --num-nodes 3
Track the cluster creation process by running
pks cluster CLUSTER-NAME. Replace
CLUSTER-NAMEwith 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.7If the value for Last Action State is
error, troubleshoot cluster creation by logging in to the BOSH Director and running
bosh tasks. See Advanced Troubleshooting with the BOSH CLI for more information.
Configure external access to the cluster’s master node using either a DNS record or an external load balancer. Use the output from the
pks clustercommand to locate the master node IP address and port.
To access your cluster, run
pks get-credentials CLUSTER-NAME. This command creates a local
kubeconfigthat allows you to manage the cluster. See Retrieve Cluster Credentials and Configuration for more information.
kubectl cluster-infoto confirm you can access your cluster using the Kubernetes CLI.
See Managing PKS for information about checking cluster health and viewing cluster logs.
Please send any feedback you have to firstname.lastname@example.org.