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

Upgrading PKS with NSX-T

Page last updated:

This topic explains how to upgrade the Pivotal Container Service (PKS) for environments using vSphere with NSX-T.

Before You Upgrade

This section describes the activites you must perform before upgrading PKS.

Consult Compatibility Charts

For more information on PKS with NSX-T and Ops Manager compatiblity, refer to the compatibility chart below:

PKS Version Compatible NSX-T Versions Compatible Ops Manager Versions
v1.2.x v2.2, v2.3 v2.2.2+, v2.3.1+
v1.1.6 v2.1, v2.2 v2.1.x, 2.2.x
v1.1.5 v2.1, v2.2 v2.1.x, v2.2.x
v1.1.4 v2.1 v2.1.x, 2.2.x
v1.1.3 v2.1 v2.1.0 - 2.1.6
v1.1.2 v2.1 v2.1.x, 2.2.x
v1.1.1 v2.1 - Advanced Edition v2.1.0 - 2.1.6

For more information on NSX-T product compatibility, see the VMware Product Interoperability Matrix for PKS in the VMware documentation.

Determine Your Upgrade Path

Use the following table to determine your upgrade path to PKS v1.2 with NSX-T. PKS v1.2 supports NSX-T v2.3, which is the recommended NSX-T version.

If your current version of PKS is… Then use the following upgrade path:
v1.1.4 or earlier
  1. Upgrade to PKS v1.1.5 or later.
  2. Upgrade to NSX-T v2.2.
  3. Upgrade to Ops Manager v2.2.2 or later, or Ops Manager v2.3.1 or later.
  4. Upgrade to PKS v1.2.x.
  5. Upgrade to NSX-T v2.3.
v1.1.5 or later
  1. Upgrade to NSX-T v2.2.
  2. Upgrade to Ops Manager v2.2.2 or later, or Ops Manager v2.3.1 or later.
  3. Upgrade to PKS v1.2.x.
  4. Upgrade to NSX-T v2.3.

Prepare to Upgrade

Before you begin upgrading the PKS tile, follow the steps below:

  1. Review the Release Notes for the version or versions of PKS you are upgrading to.
  2. Verify that your Kubernetes environment is healthy. To verify the health of your Kubernetes environment, see Verifying Deployment Health.
  3. Make sure there are no issues with vSphere by following the steps below:
    1. Verify that datastores have enough space.
    2. Verify that hosts have enough memory.
    3. Verify that there are no alarms.
    4. Verify that hosts are in a good state.
  4. Verify that NSX Edge is configured for high availability using Active/Standby mode.

    Note: Workloads in your Kubernetes cluster are unavailable while the NSX Edge nodes run the upgrade unless you configure NSX Edge for high availability. For more information, see the Configure NSX Edge for High Availability (HA) section of Preparing NSX-T Before Deploying PKS.

  5. (Optional) Back up the environment using the procedures in the following topics:

During the Upgrade

This section describes the steps required to upgrade to PKS v1.2 with NSX-T v2.3.

Step 1: Upgrade to PKS v1.1.5 or Later

Skip this step if you are already running PKS v1.1.5+.

Follow the procedures detailed in Upgrading PKS with NSX-T in the PKS v1.1 documentation.

Note: PKS v1.1.5 with NSX-T introduces architectural changes that require larger sized worker node VMs. Before you upgrade to PKS v1.1.5 or later, you must increase the size of the Kubernetes worker node VM. For more information on how to increase the worker node VM size, see Increase the Kubernetes Worker Node VM Size in the PKS v1.1 documentation. For more information about the architectural changes in PKS v1.1.5 with NSX-T, see NSX-T Architectural Changes in the PKS v1.1.5 Release Notes.

Step 2: Upgrade to NSX-T v2.2

Skip this step if you are already running NSX-T v2.2.

To upgrade to NSX-T v2.2, follow the procedures detailed in Upgrading NSX-T in the VMware documentation.

Step 3: Upgrade to Ops Manager v2.2.2+ or v2.3.1+

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

  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. Verify that the PKS control plane remains functional by performing the following steps:

    1. Add more workloads and create an additional cluster. For more information about performing those actions, see About Workload Upgrades in Maintaining Workload Uptime and Creating Clusters.
    2. 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 4: Upgrade to PKS v1.2.x

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.

  4. Browse to the PKS product file and select it. Uploading the file takes several minutes. Upload PKS product file to Ops Manager

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

    Import the PKS product file

Step 5: Download and Import the Stemcell

PKS v1.2.x uses a Xenial stemcell.

If Ops Manager does not have the Xenial stemcell required for PKS, the PKS tile displays the message Missing stemcell.

Note: If the Stemcell Library in Ops Manager already has a compatible Xenial stemcell, the Missing stemcell link does not appear. You do not need to download or import a new stemcell and can skip this step.

To download and import a new Xenial stemcell, follow the steps below:

  1. On the Pivotal Container Service tile, click on the Missing stemcell link.

    Verify stemcell assignment

  2. In the Stemcell Library, locate Pivotal Container Service and note the required stemcell version.

  3. Visit the Stemcells for PCF (Ubuntu Xenial) page on Pivotal Network, and download the required stemcell version for vSphere.

  4. Return to the Installation Dashboard in Ops Manager, and click on Stemcell Library.

  5. On the Stemcell Library page, click Import Stemcell and select the stemcell file you downloaded from Pivotal Network. Import stemcell

  6. Select the PKS product and click Apply Stemcell to Products. Apply stemcell to PKS

  7. Verify that Ops Manager successfully applied the stemcell. Verify stemcell assignment

  8. Select the Installation Dashboard link to return to the Installation Dashboard. Verify status is green

Step 6: Verify Errand Configuration

To verify that errands are configured correctly in the PKS tile, perform the following steps.

  1. In the PKS tile, click Errands.

  2. Under Post-Deploy Errands, verify that the listed errands are configured as follows:

    • NSX-T Validation errand: Set to On
    • Upgrade all clusters errand: Set to Default (On)
    • Create pre-defined Wavefront alerts errand: Set to Default (Off)

    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.

  3. If you make any changes, click Save.

Step 6: Apply Changes to the PKS Tile

Perform the following steps to complete the upgrade to the PKS tile.

  1. Return to the Installation Dashboard in Ops Manager.

  2. If you are using Ops Manager v2.2, click Review Pending Changes [BETA]. For more information about this Ops Manager page, see Reviewing Pending Product Changes.

  3. If you are using Ops Manager v2.3, click Review Pending Changes. For more information about this Ops Manager page, see Reviewing Pending Product Changes.

  4. Click Apply Changes.

Step 7: Upgrade to NSX-T v2.3

NSX-T v2.3 is the recommended version of NSX-T to use with PKS v1.2.

To upgrade to NSX-T v2.3, follow the procedures detailed in Upgrading NSX-T Data Center.

After the Upgrade

After you complete the upgrade to PKS v1.2.x and NSX-T v2.3, complete the following verifications and optional upgrades.

Verify the Upgrade

After you apply changes to the PKS tile and the upgrade is complete, verify that your Kubernetes environment is healthy and confirm that NCP is running on the master node VM.

To verify the health of your Kubernetes environment and NCP, see Verifying Deployment Health.

(Optional) Upgrade vSphere

Upgrade vSphere from version 6.5 or 6.5 U1 to 6.5 U2 or 6.7. VMware vSphere 6.7 is only supported with Ops Manager v2.3.1 or later and NSX-T v2.3.

For more information, see vSphere Version Requirements in PKS documentation and Upgrading vSphere in an NSX Environment in the VMware documentation.


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