Pivotal Container Service v1.0

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).

Configure Cluster Access

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.

Create a Kubernetes Cluster

Perform the following steps:

  1. 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.

  2. On the command line, run the following command to log in:

    pks login -a PKS_API -u USERNAME -p PASSWORD --ca-cert CERT-PATH
    See Log in to the PKS CLI for more information about the pks login command.

  3. 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, or
    • PLAN-NAME: Choose a plan for your cluster. Run pks plans to list your available plans.
    • (Optional) 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.

      For example:
      $ pks create-cluster my-cluster \
      --external-hostname \
      --plan large --num-nodes 3
  4. Track the cluster creation process by running pks cluster CLUSTER-NAME. Replace CLUSTER-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:
    Kubernetes Master Port:   8443
    Worker Instances:         3
    Kubernetes Master IP(s):
    If 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.

  5. 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 cluster command to locate the master node IP address and port.

  6. To access your cluster, run pks get-credentials CLUSTER-NAME. This command creates a local kubeconfig that allows you to manage the cluster. See Retrieve Cluster Credentials and Configuration for more information.

  7. 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.

Please send any feedback you have to

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