LATEST VERSION: v1.3 - RELEASE NOTES

Pivotal Container Service v1.3

• v1.2
• v1.1
• v1.0

PDF

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 PKS 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 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:

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

2. 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 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] \
   [--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 the CLUSTER-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 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.
   • (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.

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

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
   

   See Log in to the PKS CLI for more information about the pks login command.

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