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

Installing and Configuring PKS

Page last updated:

This topic describes how to install and configure Pivotal Container Service (PKS).

Prerequisites

Before performing the procedures in this topic, you must have deployed and configured Ops Manager. For more information, see the prerequisites for your cloud provider:

If you are using an instance of Ops Manager that you configured previously to install other runtimes, confirm the following settings before you install PKS:

  1. Navigate to Ops Manager.
  2. From the Director Config pane, do the following:
    1. Select the Enable Post Deploy Scripts checkbox.
    2. Clear the Disable BOSH DNS server for troubleshooting purposes checkbox.
  3. Click the Installation Dashboard link to return to the Installation Dashboard.
  4. Click Apply Changes.

Step 1: Install PKS

To install PKS, do the following:

  1. Download the product file from Pivotal Network.
  2. Navigate to https://YOUR-OPS-MANAGER-FQDN/ in a browser to log in to the Ops Manager Installation Dashboard.
  3. Click Import a Product to upload the product file.
  4. Under Pivotal Container Service in the left column, click the plus sign to add this product to your staging area.

Step 2: Configure PKS

Click the orange Pivotal Container Service tile to start the configuration process.

Pivotal Container Service tile on the Ops Manager installation dashboard

Assign AZs and Networks

Perform the following steps:

  1. Click Assign AZs and Networks.

  2. Select the availability zone (AZ) where you want to deploy the PKS API VM as a singleton job.

    Note: You must select an additional AZ for balancing other jobs before clicking Save, but this selection has no effect in the current version of PKS.

    Assign AZs and Networks pane in Ops Manager

  3. Under Network, select the infrastructure subnet you created for the PKS API VM.

  4. Under Service Network, select the services subnet you created for Kubernetes cluster VMs.

  5. Click Save.

PKS API

Perform the following steps:

  1. Click PKS API.
  2. Under Certificate to secure the PKS API, provide your own certificate and private key pair. The certificate you enter here should cover the domain that routes to the PKS API VM with TLS termination on the ingress.

    (Optional) If you do not have a certificate and private key pair, you can have Ops Manager generate one for you. Perform the following steps:
    1. Select the Generate RSA Certificate link.
    2. Enter the wildcard domain for your API hostname. For example, if your PKS API domain is api.pks.example.com, then enter *.pks.example.com.
    3. Click Generate.
  3. Click Save.

Plans

To activate a plan, do the following:

  1. Click the Plan 1, Plan 2, or Plan 3 tab.

    Note: A plan defines a set of resource types used for deploying clusters. You can configure up to three plans. Configuring Plan 1 is required.

  2. Select Active to activate the plan and make it available to developers deploying clusters.
  3. Under Name, provide a unique name for the plan.
  4. Under Description, edit the description as needed. The plan description appears in the Services Marketplace, which developers can access by using PKS CLI.
  5. Under AZ placement, select an AZ for the Kubernetes clusters deployed by PKS.
  6. Under Default Cluster Authorization Mode, select an authentication mode for the Kubernetes clusters. Pivotal recommends selecting RBAC. For more information, see Authorization Overview in the Kubernetes documentation.
  7. Under ETCD/Master VM Type, select the type of VM to use for Kubernetes etcd and master nodes.
  8. Under Master Persistent Disk Type, select the size of the persistent disk for the Kubernetes master VM.
  9. Under Worker VM Type, select the type of VM to use for Kubernetes worker nodes.
  10. Under Worker Persistent Disk Type, select the size of the persistent disk for the Kubernetes worker nodes.
  11. Under Worker Node Instances, select the default number of Kubernetes worker nodes to provision for each cluster. For high availability, Pivotal recommends creating clusters with at least 3 worker nodes.
  12. Under Errand VM Type, select the size of the VM where the errand will run. The smallest instance possible is sufficient, as the only errand running on this VM is the one that applies the Default Cluster App YAML configuration.
  13. (Optional) Under (Optional) Add-ons - Use with caution, enter additional YAML configuration to add custom workloads to each cluster in this plan. You can specify multiple files using --- as a separator.
  14. If you want users to be able to create pods with privileged containers, select the Enable Privileged Containers - Use with caution option. For more information, see Pods in the Kubernetes documentation.
  15. Click Save.

To deactivate a plan, do the following:

  1. Click the Plan 1, Plan 2, or Plan 3 tab.
  2. Select Plan Inactive.
  3. Click Save.

Kubernetes Cloud Provider

To configure your Kubernetes cloud provider settings, follow the procedure for your cloud provider.

  1. Click Kubernetes Cloud Provider.
  2. Under Choose your IaaS, select either vSphere or GCP.
  3. Follow the procedures for your cloud provider below.

vSphere

In the procedure below, you will use credentials for vCenter master and worker VMs. You must have provisioned the service account associated with each type of VM with the correct permissions. For more information, see Create the Master Node Service Account and Create the Worker Node Service Account.

Perform the following steps:

  1. Click Kubernetes Cloud Provider.
  2. Under Choose your IaaS, select vSphere.
  3. Perform the steps specific to vSphere. Ensure the values match those in the vCenter Config section of the Ops Manager tile:
    1. Enter your vCenter Master Credentials. Enter the username using the format user@CF-EXAMPLE.com.
    2. Enter your vCenter Worker Credentials. Enter the username using the format user@CF-EXAMPLE.com.
    3. Enter your vCenter Host. For example, vcenter.CF-EXAMPLE.com.
    4. Enter your Datacenter Name. For example, CF-EXAMPLE-dc.
    5. Enter your Datastore Name. For example, CF-EXAMPLE-ds.
    6. Enter the Stored VM Folder so that the persistent stores know where to find the VMs. To retrieve the name of the folder, navigate to your Ops Manager Director tile, click vCenter Config, and locate the value for VM Folder. The default folder name is pcf_vms.
  4. Click Save.

GCP

Ensure the values in the following procedure match those in the Google Config section of the Ops Manager tile.

  1. Enter your GCP Project Id, which is the name of the deployment in your Ops Manager environment.
  2. Enter your VPC Network, which is the VPC network name for your Ops Manager environment.
  3. Enter your GCP Master Service Account Key. For information about configuring this key, see Create the Master Node Service Account.
  4. Enter your GCP Worker Service Account Key. For information about configuring this key, see Create the Worker Node Service Account.
  5. Click Save.

Networking

To configure networking, do the following:

  1. Click Networking.
  2. Under Network, select the Container Network Interface to use.
  3. Click Save.

UAA

To configure the UAA server, do the following:

  1. Click UAA.
  2. Under UAA URL, enter a fully qualified domain name (FQDN) to access UAA on the PKS broker VM. This URL must belong to the domain you provided in the PKS API section. For example, if you provided a certificate for *.pks.example.com, enter api.pks.example.com for the UAA URL.
  3. Under PKS CLI Access Token Lifetime, enter a time in seconds for the PKS CLI access token lifetime.
  4. Under PKS CLI Refresh Token Lifetime, enter a time in seconds for the PKS CLI refresh token lifetime.
  5. Click Save.

(Optional) Syslog

You can designate an external syslog endpoint for PKS component and cluster log messages.

To specify the destination for PKS log messages, do the following:

  1. Click Syslog.
  2. Select Yes to configure syslog forwarding.
  3. Enter the destination syslog endpoint.
  4. Enter the destination syslog port.
  5. Select a transport protocol for log forwarding.
  6. (Optional) Pivotal strongly recommends that you enable TLS encryption when forwarding logs as they may contain sensitive information. For example, these logs may contain cloud provider credentials. To enable TLS, perform the following steps.
    1. Provide the accepted fingerprint (SHA1) or name of remote peer. For example, *.YOUR-LOGGING-SYSTEM.com.
    2. Provide a TLS certificate for the destination syslog endpoint.

      Note: You do not need to provide a new certificate if the TLS certificate for the destination syslog endpoint is signed by a Certificate Authority (CA) in your BOSH certificate store.

Errands

Errands are scripts that run at designated points during an installation.

To configure when post-deploy and pre-delete errands for PKS are run, make a selection in the dropdown next to the errand. For a typical PKS deployment, Pivotal recommends that you leave the default settings.

For more information about errands and their configuration state, see Managing Errands in Ops Manager.

Resource Config

To modify the resource usage of PKS, click Resource Config and edit the Pivotal Container Service job.

Note: If you experience timeouts or slowness when interacting with the PKS API, select a VM Type with greater CPU and memory resources for the Pivotal Container Service job.

If you are using GCP, enter a name for your PKS API load balancer that begins with tcp: in the Load Balancers column. For example, tcp:pks-api. For more information, see Configuring a GCP Load Balancer for the PKS API.

(Optional) Stemcell

Note: The Stemcell pane appears in Ops Manager v2.0 and earlier only. In Ops Manager v2.1 and later, manage stemcells using the Stemcell Library. For more information, see Importing and Managing Stemcells in the Pivotal Cloud Foundry documentation.

To edit the stemcell configuration, click Stemcell. Click Import Stemcell to import a new stemcell.

PKS uses floating stemcells. Floating stemcells allow upgrades to the minor versions of stemcells but not the major versions. For example, a stemcell can float from 1234.56 to 1234.99 but not from 1234.991 to 1235.0. For more information on floating stemcells, see Understanding Floating Stemcells.

WARNING: Because PKS uses floating stemcells, updating the PKS tile with a new stemcell triggers the rolling of every VM in each cluster. Also, updating other product tiles in your deployment with a new stemcell causes the PKS tile to roll VMs. This rolling is enabled by the Upgrade all clusters errand. Pivotal recommends that you keep this errand turned on because automatic rolling of VMs ensures that all deployed cluster VMs are patched. However, automatic rolling can cause downtime in your deployment.

Step 3: Apply Changes

After configuring the tile, return to the Ops Manager Installation Dashboard and click Apply Changes to deploy the tile.

Step 4: Retrieve PKS API Endpoint

You must share the PKS API endpoint to allow your organization to use the API to create, update, and delete clusters. See Create a Cluster for more information.

To retrieve the PKS API endpoint, do the following:

  1. Navigate to the Ops Manager Installation Dashboard.
  2. Click the Pivotal Container Service tile.
  3. Click the Status tab and locate the Pivotal Container Service job. The IP address of the Pivotal Container Service job is the PKS API endpoint.

Step 5: Configure External Load Balancer

If you are using GCP, continue to Step 4: Create a Network Tag for the Firewall Rule of Configuring a GCP Load Balancer for the PKS API.

If you are using vSphere, configure an external load balancer to access the PKS API from outside the network. You can use any external load balancer of your choice.

Your external load balancer forwards traffic to the PKS API endpoint on ports 9021 and 8443. Configure the external load balancer to resolve to the domain name you set in the PKS API section of the tile configuration.

The load balancer should be configured with:

Next Steps

Follow the procedures in Configure PKS API Access.

Configure authentication for PKS using User Account and Authentication (UAA). To create and manage users using UAA, see Manage Users in UAA.


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