Pivotal Container Service v1.0

Installing and Configuring PKS on vSphere

Page last updated:

This topic describes how to install and configure Pivotal Container Service (PKS) on vSphere without NSX-T integration.

Before performing the procedures in this topic, consult the requirements in the vSphere Prerequisites and Resource Requirements topic.

Step 1: Install PKS

Perform the following steps to install PKS:

  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. From the Director Config page, configure the following settings:
    • Select Enable Post Deploy Scripts.
    • Clear the Disable BOSH DNS server for troubleshooting purposes checkbox.
  4. Click Apply Changes.
  5. Click Import a Product to upload the product file.
  6. 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 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.

    Assign AZs and Networks pane in Ops Manager

  2. Select an availability zone (AZ) for your singleton jobs and one or more AZs to balance other jobs in.

    Note: If you upgrade PKS, you must place singleton jobs in the AZ you selected when you first installed the PKS tile. You cannot move singleton jobs to another AZ.

    Note: In PKS, Pivotal Container Service is a singleton job. This broker VM enables the creation of PKS clusters through the PKS CLI.

  3. Under Network, select a subnet for the PKS broker.

  4. Under Service Network, select a subnet for the on-demand service instances created by the PKS broker.

  5. Click Save.


Perform the following steps:

  1. Click PKS API.
  2. Under Certificate to secure the PKS API, provide your own wildcard certificate and private key pair. The certificate you enter here should cover the domain that routes to the PKS broker 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 that matches the URL used to access PKS API and UAA endpoints. For example, if your UAA URL is, then enter *
    3. Click Generate.
  3. Click Save.


To activate a plan, perform the following steps:

  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.

  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 Default Cluster Authorization Mode, select an authentication mode for the Kubernetes clusters. Pivotal recommends selecting RBAC. For more information, see the RBAC Support in Kubernetes blog post.
  6. Under AZ placement, select an AZ for the Kubernetes clusters deployed by PKS.
  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.
  15. Click Save.

To deactivate a plan, perform the following steps:

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

Kubernetes Cloud Provider

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:

      vSphere IaaS pane in Ops Manager

      1. Enter your vCenter Credentials.
      2. Enter your vCenter Host, such as
      3. Enter your Datacenter Name, such as cf-example-dc.
      4. Enter your Datastore Name, such as cf-example-ds.
      5. 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.


Perform the following steps:

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


Perform the following steps:

  1. Click UAA.
  2. For UAA URL, enter a domain name to use when accessing UAA and the PKS API. For example, This domain name must match the certificate you generated when configuring the PKS API pane.
  3. Enter the time (in seconds) for the PKS CLI access token lifetime.
  4. Enter the time (in seconds) for the PKS CLI refresh token lifetime.

(Optional) Syslog

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

Note: BOSH Director logs contain sensitive information that should be considered privileged. For example, these logs may contain cloud provider credentials. If you choose to forward logs to an external syslog endpoint, using TLS encryption is strongly recommended to prevent information from being intercepted by a third party.

To specify the destination for PKS log messages, perform the following steps:

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

(Optional) Resource Config

To modify the resource usage of PKS, click Resource Config and edit the PKS on-demand broker job.

(Optional) Stemcell

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 the Understanding Floating Stemcells topic.

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.

When an operator creates a cluster, they provide an IP address for the Kubernetes master host, then point the load balancer to the newly created cluster. If you use a load balancer as a service (LBaaS) tool, your LBaaS may manage cluster creation and configuration.

See Create a Cluster for more information.

Perform the following steps to retrieve the PKS API endpoint:

  1. Navigate to the Ops Manager Installation Dashboard.
  2. Click the PKS tile.
  3. Click the Status tab and locate the IP address of the PKS API endpoint. This is the endpoint that developers use to create and manage clusters.

Step 5: Configure External Load Balancer

Configure your external TCP or HTTPS load balancer to resolve to the domain name used in the certificate you provided during the PKS API section of the tile configuration. Your external load balancer forwards traffic to the PKS API endpoint on port 9021 and the UAA endpoint on port 8443.

The load balancer should be configured with:

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