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

Upgrading PKS

Page last updated:

This topic explains how to upgrade the Pivotal Container Service (PKS) tile and existing Kubernetes clusters. It also explains the service interruptions that can result from service changes and upgrades and from failures at the process, VM, and IaaS level.

For conceptual information about upgrading the PKS tile and PKS-provisioned Kubernetes clusters, see What Happens During PKS Upgrades.

WARNING: Do not manually upgrade your Kubernetes version. The PKS service includes the compatible Kubernetes version.

For information about upgrading PKS on vSphere with NSX-T integration, see Upgrading PKS with NSX-T.

Prepare to Upgrade

Before you begin upgrading the PKS tile, consider your workload capacity and uptime requirements. If workers are operating too close to their capacity, the PKS upgrade can fail. View your workload resource usage in Dashboard. For more information, see Accessing Dashboard.

If your clusters are near capacity for your existing infrastructure, Pivotal recommends scaling up your clusters before you upgrade. Scale up your cluster by running pks resize or create a cluster using a larger plan. For more information, see Scaling Existing Clusters.

To prevent workload downtime during a cluster upgrade, Pivotal recommends running your workload on at least three worker VMs, using multiple replicas of your workloads spread across those VMs. For more information, see Maintaining Workload Uptime.

Step 1: Upgrade to Ops Manager v2.2.2+ or v2.3.1+ and PKS v1.1.5

Before you upgrade to PKS v1.2, you must upgrade PKS to v1.1.5+ and upgrade Ops Manager to v2.2.2+ or v2.3.1+.

For more information, refer to the compatibility chart below:

PKS Version Compatible Ops Manager Versions
1.2 2.2.2+, 2.3.1+
1.1.6 2.1.x, 2.2.x
1.1.5 2.1.x, 2.2.x
1.1.4 2.1.x, 2.2.x
1.1.3 2.1.0 - 2.1.6
1.1.2 2.1.x, 2.2.x
1.1.1 2.1.0 - 2.1.6

Upgrade Ops Manager on PKS v1.1.5 and Later

If you already use PKS v1.1.5, perform the steps below to upgrade Ops Manager:

  1. To upgrade to Ops Manager v2.2.2+ or v2.3.1+, follow the procedures detailed in Upgrade Ops Manager and Installed Products to v2.2 or Upgrade Ops Manager and Installed Products to v2.3.

  2. Operators should add additional workloads and create an additional cluster to ensure that the PKS control plane remains functional. For more information about performing those actions, see About Workload Upgrades in Maintaining Workload Uptime and Creating Clusters.

You can monitor the PKS control plane VM by clicking the Pivotal Container Service tile, selecting Status tab, and reviewing the Pivotal Container Service VM’s data points. If any data points are at capacity, scale your deployment accordingly.

Upgrade Ops Manager on PKS v1.1.4 and Earlier

If you use PKS v1.1.4 or earlier, perform the steps below to upgrade PKS and Ops Manager:

  1. To upgrade PKS v1.1.4 or earlier, follow the procedures detailed in Upgrading PKS in the PKS v1.1 documentation.

  2. To upgrade to Ops Manager v2.2.2+ or v2.3.1+, follow the procedures detailed in Upgrade Ops Manager and Installed Products to v2.2 or Upgrade Ops Manager and Installed Products to v2.3.

  3. Operators should add additional workloads and create an additional cluster to ensure that the PKS control plane remains functional. For more information about performing those actions, see About Workload Upgrades in Maintaining Workload Uptime and Creating Clusters.

You can monitor the PKS control plane VM by clicking the Pivotal Container Service tile, selecting Status tab, and reviewing the Pivotal Container Service VM’s data points. If any data points are at capacity, scale your deployment accordingly.

Step 2: Upgrade the PKS Tile

To upgrade PKS, you follow the same Ops Manager process that you use to install the tile for the first time. Your configuration settings migrate to the new version automatically. Follow the steps below to perform an upgrade.

  1. Review the Release Notes for the version you are upgrading to.

  2. Download the desired version of the product from Pivotal Network.

  3. Navigate to the Ops Manager Installation Dashboard and click Import a Product to upload the product file.

  4. Under the Import a Product button, click + next to Pivotal Container Service. This adds the tile to your staging area.

  5. Click the newly-added Pivotal Container Service tile.

  6. Optional: To upgrade all PKS-deployed Kubernetes clusters when you upgrade the PKS tile, follow the steps below:

    1. Click Errands.
    2. Under Post-Deploy Errands, set the Upgrade all clusters errand to Default (On). The errand upgrades a single Kubernetes cluster at a time. Upgrading PKS Kubernetes clusters can temporarily interrupt the service, as described in Service Interruptions below.

      WARNING: If you upgrade PKS from v1.1 to v1.2, you must enable Upgrade all clusters errand. This ensures existing clusters can perform resize or delete actions after the upgrade.

      (Optional) To monitor the Upgrade all clusters errand using the BOSH CLI, do the following:
      1. Log in to the BOSH Director by running bosh -e MY-ENVIRONMENT log-in from a VM that can access your PKS deployment. For more information, see Managing PKS Deployments with BOSH.
      2. Run bosh -e MY-ENVIRONMENT tasks.
      3. Locate the task number for the errand in the # column of the BOSH output.
      4. Run bosh task TASK-NUMBER, replacing TASK-NUMBER with the task number you located in the previous step.
    3. Click Save.

      WARNING: If you set the Upgrade all clusters errand to Off, your Kubernetes cluster version will fall behind the PKS tile version. If your clusters fall more than one version behind the tile, you can no longer upgrade the clusters. You must upgrade your clusters to match the PKS tile version before the next tile upgrade.

  7. Review the other configuration panes. Click Save on any panes where you make changes.

    Note: When 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.

  8. Return to the Installation Dashboard and do one of the following:

    • Apply Changes: Click Apply Changes.
    • Review Pending Changes [BETA]:
      1. Click Review Pending Changes.
      2. Click Pivotal Container Service. If you changed Post-Deploy Errands, confirm that the Post-Deploy Errands setting matches the configuration you set in the previous step.
      3. Click Apply Changes.
  9. Operators should add additional workloads and create an additional cluster to ensure that the PKS control plane remains functional. For more information about performing those actions, see About Workload Upgrades in Maintaining Workload Uptime and Creating Clusters.

You can monitor the PKS control plane VM by clicking the Pivotal Container Service tile, selecting Status tab, and reviewing the Pivotal Container Service VM’s data points. If any data points are at capacity, scale your deployment accordingly.

Step 3: (Optional) Upgrade vCenter

  1. If you are deploying PKS on vSphere, consult vSphere Version Requirements and upgrade vSphere if necessary.

  2. Operators should add additional workloads and create an additional cluster to ensure that the PKS control plane remains functional. For more information about performing those actions, see About Workload Upgrades in Maintaining Workload Uptime and Creating Clusters.

You can monitor the PKS control plane VM by clicking the Pivotal Container Service tile, selecting Status tab, and reviewing the Pivotal Container Service VM’s data points. If any data points are at capacity, scale your deployment accordingly.

Upgrade Kubernetes Clusters

If you set the Upgrade all clusters errand to Default (On), your PKS-deployed Kubernetes clusters are upgraded automatically when the PKS tile upgrade runs.

If you set the Upgrade all clusters errand to Off, you can upgrade all PKS-deployed Kubernetes clusters by setting the Upgrade all clusters errand to On and clicking Apply Changes.

WARNING: If you upgrade PKS from v1.1 to v1.2, you must enable Upgrade all clusters errand. This ensures existing clusters can perform resize or delete actions after the upgrade.

Service Interruptions

Service changes and upgrades and failures at the process, VM, and IaaS level can cause outages in the PKS service, as described below.

Read this section if:

  • You are experiencing a service interruption and are wondering why.
  • You are planning to update or change a Kubernetes cluster and want to know if it might cause a service interruption.

Stemcell or Service Upgrade

An operator updates a stemcell version or the PKS tile version.

  • Impact: The PKS API experiences downtime while the new stemcell is applied to the Pivotal Container Service VM.

    • Required Actions: None. If the update deploys successfully, apps reconnect automatically.
  • Impact: Workloads running on single node clusters experience downtime.

    • Required Actions: None. If the update deploys successfully, workloads resume automatically. For more information, see Maintaining Workload Uptime.

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