LATEST VERSION: v1.2 - RELEASE NOTES
Pivotal Container Service v1.1

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.

vSphere without NSX-T or GCP

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 or vSphere without NSX-T, 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 configure GCP load balancers only for PKS clusters that are deployed on GCP.

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:

  1. Grant cluster access to a new or existing user in UAA. See the Grant Cluster Access to a User section of Managing Users in PKS with UAA for more information.

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

    pks login -a PKS-API -u USERNAME -k
    
    For more information about the pks login command, see the Log in to the PKS CLI section of Installing the PKS CLI.

  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, my-cluster.example.com or 10.0.0.1. If you created an external load balancer, use its IP address.
    • 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 my-cluster.example.com \
      --plan large --num-nodes 3

      Note: It can take up to 30 minutes to create a cluster.

  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:   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 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. 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, 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 Step 3: 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.

  6. To access your cluster, run pks get-credentials CLUSTER-NAME. This 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.

  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.

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:

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

    pks login -a PKS-API -u USERNAME -k
    
    For more information about the pks login command, see the Log in to the PKS CLI section of Installing the PKS CLI.

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

  4. Identify the name of your cluster deployment. For example:

    $ bosh -e pks deployments
    Your cluster deployment name begins with service-instance and includes the UUID you located in a previous step.

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

  6. 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 Reconfiguring a GCP Load Balancer in Configuring a GCP Load Balancer for PKS Clusters.


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