Pivotal Container Service v1.0

Installing and Configuring PKS on GCP

Page last updated:

This topic describes how to install and configure Pivotal Container Service (PKS) on Google Cloud Platform (GCP).

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

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. 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 orange Pivotal Container Service tile to start the configuration process.

Pivotal Container Service tile on the Ops Manager installation dashboard

Assign AZs and Networks

To assign AZs and networks, do the following:

  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.

This is the wildcard domain you use when setting up your DNS entry for your load balancer in Step 5.


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.

  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 the RBAC Support in Kubernetes blog post.
  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, 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, do the following:

  1. Click Kubernetes Cloud Provider.
  2. Under Choose your IaaS, select GCP.
  3. Perform the steps specific to GCP.
    • Ensure the values 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 Service Key, which you created using the instructions from the GCP prerequisites.
  4. Click Save.


To configure networking, do the following:

  1. Click Networking.
  2. Under Network, select Flannel.
  3. Click Save.


To configure UAA, do the following:

  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.

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

If you created a PKS API load balancer, you should give it a name in the Load Balancers column. For more information, see Step 5: Configure External Load Balancer.

(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 Using PKS for more information.

To retrieve the PKS API endpoint, do the following:

  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 load balancer to resolve to the domain name used in the certificate you provided during the PKS API section of the tile configuration.

Create Load Balancer for PKS API

  1. Navigate to Network Services > Load balancing and click Create load balancer.

  2. Under TCP Load Balancing, click Start configuration.

  3. Select whether you want to load balance traffic from the Internet to your VMs or only between your VMs.

  4. Select whether you want to place the backends for your load balancer in a single region or across multiple regions.

  5. Give your load balancer a name.

  6. Configure your backend.

    • Give your backend a name.
    • Select a region.
    • Select backends from either instance groups or VM instances in the target pool’s region.
    • (Optional) Select a backup pool.
    • (Optional) Select whether you want to create a health check or go without one.
    • Select a session affinity. None will enable successive requests from a particular client IP to go to any instance in the pool. Client IP will send requests from the client IP to the same instance. Client IP and protocol will send requests from the client IP with the same protocol to the same instance.
  7. Configure your frontend.

    • Give your frontend a name.
    • Select Create IP address to reserve the IP address from Step 4: Retrieve PKS API Endpoint.
    • Specify 8443 and 9021 as your ports. Your external load balancer forwards traffic to the UAA endpoint on port 8443 and the PKS API endpoint on port 9021.
    • Click Done.
  8. Click Create.

Create Firewall Rule for Load Balancer

  1. Navigate to VPC Network > Firewall rules and click Create firewall rule.

  2. Configure the following:

    • Give your firewall rule a name.
    • Select the network to which the firewall rule will apply.
    • Specify the priority of this firewall rule.
    • Select Ingress as the Direction of traffic.
    • Select Allow as the Action on match.
    • Select the load balancer you just created as your target.

      Note: Make sure that the PKS VM hosting the PKS API and Broker has the pks-api network tag. If it does not have the pks-api tag, add it so the above firewall rule will apply to it.

    • Use as your source IP range.
    • Under Protocols and ports, select Specified protocols and ports and specify tcp:8443,9021.
  3. Click Apply Changes.

Create Wildcard DNS Entry to Load Balancer

To create a DNS entry for the wildcard domain and certificate you generated in Step 3, do the following:

  1. Navigate to Network Services > Cloud DNS.

  2. If you do not already have a DNS zone, click Create zone.

    • Give a zone name and a DNS name.
    • Specify whether the DNSSEC state of the zone is Off, On, or Transfer.
    • Click Create.
  3. Add a DNS record for your load balancer.

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