Upgrading Enterprise PKS (Flannel Networking)

Page last updated:

This topic explains how to upgrade VMware Enterprise PKS from v1.6 to v1.7 on vSphere with Flannel networking, Google Cloud Platform (GCP), Amazon Web Services (AWS), and Azure.

For instructions on upgrading Enterprise PKS on vSphere with NSX-T networking, see Upgrading Enterprise PKS (NSX-T Networking).

Warning: Do not manually upgrade your Kubernetes version. Enterprise PKS includes the compatible Kubernetes version.

Overview

Before you upgrade, follow the procedures in Prepare to Upgrade below to plan and prepare your upgrade.

After you complete the preparation steps, continue to the procedures in Perform the Upgrade below. These steps guide you through the process of upgrading Ops Manager and the Enterprise PKS tile, importing an updated stemcell, and applying the changes to your deployment.

After you complete the upgrade, follow the procedures in After the Upgrade below to verify that your upgraded Enterprise PKS deployment is running properly.

Prepare to Upgrade

If you have not already, complete all of the steps in Upgrade Preparation Checklist for Enterprise PKS v1.7.

Perform the Upgrade

This section describes the steps required to upgrade to Enterprise PKS v1.7:

  1. Upgrade Ops Manager
  2. Download and Import Enterprise PKS v1.7
  3. Download and Import Stemcells
  4. Verify Errand Configuration
  5. Verify Resource Configuration
  6. Verify Remaining Configurations
  7. Apply Changes to the Enterprise PKS Tile

Upgrade Ops Manager

Each version of Enterprise PKS is compatible with multiple versions of Ops Manager. To determine Ops Manager compatibility and, if necessary, upgrade Ops Manager:

  1. See VMware Tanzu Network to determine if your Ops Manager version is compatible with Enterprise PKS v1.7.
  2. If your Ops Manager version is not compatible with Enterprise PKS v1.7, follow the steps below.
  3. Upgrade Ops Manager. For instructions, see Import Installation to Ops Manager v2.7 VM.

  4. Verify that the Enterprise PKS control plane remains functional by performing the following steps:

    1. Add more workloads and create an additional cluster. For more information, see About Cluster Upgrades in Maintaining Workload Uptime and Creating Clusters.
    2. Monitor the Enterprise PKS control plane in the Enterprise PKS tile > Status tab. Review the load and resource usage data for the PKS API and PKS Database VMs. If any levels are at capacity, scale up the VMs.

      Warning: Do not disable the PKS 1.7.x Upgrade - MySQL Clone errand. This errand must remain set to Default (On) at all times.

Download and Import Enterprise PKS v1.7

When you upgrade Enterprise PKS, your configuration settings typically migrate to the new version automatically. To download and import a Enterprise PKS version:

  1. Download the desired version of the product from VMware Tanzu Network.

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

  3. Under the Import a Product button, click + next to Enterprise PKS. This adds the tile to your staging area.

Download and Import Stemcells

Enterprise PKS requires a Xenial stemcell. A stemcell for Windows 2019 is also required if you intend to create Windows worker-based clusters. For information about Windows stemcells, see Configuring Windows Worker-Based Clusters (Beta).

If Ops Manager does not have the Xenial stemcell required for Enterprise PKS v1.7, the Enterprise PKS tile displays the message Missing stemcell. To download and import a new Xenial stemcell, follow the steps below:

  1. On the Enterprise PKS tile, click the Missing stemcell link.

    Verify stemcell assignment

  2. In the Stemcell Library, locate the Enterprise PKS tile and note the required stemcell version.

  3. Navigate to the Stemcells (Ubuntu Xenial) page on VMware Tanzu Network and download the required stemcell version for your IaaS.

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

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

  6. Select the Enterprise PKS tile and click Apply Stemcell to Products.

  7. Verify that Ops Manager successfully applied the stemcell. The stemcell version you imported and applied appears in the Staged column for Enterprise PKS.

  8. Return to the Installation Dashboard.

Verify Errand Configuration

To verify your Errands pane is correctly configured, do the following:

  1. In the Enterprise PKS tile, click Errands.

  2. Under Post-Deploy Errands:

    • Review the PKS 1.7.x Upgrade - MySQL Clone errand:
      • Confirm the PKS 1.7.x Upgrade - MySQL Clone errand is set to On, the default.

        Warning: The PKS 1.7.x Upgrade - MySQL Clone errand must be enabled before you apply changes. It cannot be run separately afterwards.

    • Review the Upgrade all clusters errand:
      • If you want to upgrade the Enterprise PKS tile and all your existing Kubernetes clusters simultaneously, confirm that Upgrade all clusters errand is set to Default (On). The errand upgrades all clusters. Upgrading Enterprise PKS-provisioned Kubernetes clusters can temporarily interrupt the service as described in Service Interruptions.
      • If you want to upgrade the Enterprise PKS tile only and then upgrade your existing Kubernetes clusters separately, disable Upgrade all clusters errand. For more information, see Upgrading Clusters.

        Warning: Disabling the Upgrade all clusters errand causes the PKS version tagged in your Kubernetes clusters to fall behind the Enterprise PKS tile version. If you disable the Upgrade all clusters errand when upgrading the Enterprise PKS tile, you must upgrade all your Kubernetes clusters before the next Enterprise PKS upgrade.

    • Configure the Run smoke tests errand:
      • Set the Run smoke tests errand to On. The errand uses the Enterprise PKS Command Line Interface (PKS CLI) to create a Kubernetes cluster and then delete it. If the creation or deletion fails, the errand fails and the installation of the Enterprise PKS tile is aborted.
  3. Click Save.

Verify Resource Configuration

To confirm your Resource Config pane is correctly configured, do the following:

  1. In the Enterprise PKS tile, click Resource Config.

  2. Under PKS API, confirm that the PERSISTENT DISK TYPE size is no smaller than its PKS v1.6 size.

  3. Under PKS Database, ensure the following:

    • The PERSISTENT DISK TYPE size is the same as the PERSISTENT DISK TYPE size of PKS API.
    • The VM TYPE ephemeral disk size is at least four times the size of the PERSISTENT DISK TYPE size.
  4. Click Save.

Verify Remaining Configurations

To confirm your other Enterprise PKS tile panes are correctly configured, do the following:

  1. Review the Assign AZs and Networks pane.

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

  2. Review the other configuration panes.
  3. Make changes where necessary.

    WARNING: Do not change the number of master/etcd nodes for any plan that was used to create currently-running clusters. Enterprise PKS does not support changing the number of master/etcd nodes for plans with existing clusters.

  4. Click Save on any panes where you make changes.

Apply Changes to the Enterprise PKS Tile

To complete the upgrade of the Enterprise PKS tile:

  1. Return to the Installation Dashboard in Ops Manager.

  2. Click Review Pending Changes. For more information about this Ops Manager page, see Reviewing Pending Product Changes.

  3. Click Apply Changes.

  4. (Optional) To monitor the progress of 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 Enterprise PKS deployment. For more information, see Using BOSH Diagnostic Commands in Enterprise PKS.
    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.

Warning: Upgrading Enterprise PKS to v1.7 reconfigures the Enterprise PKS control plane. If your upgrade to Enterprise PKS v1.7 fails, contact Support.

After the Upgrade

After you complete the upgrade to Enterprise PKS v1.7, complete the following verifications and upgrades:

Update the PKS and Kubernetes CLIs

Update the PKS and Kubernetes CLIs on any local machine where you run commands that interact with your upgraded version of Enterprise PKS.

To update your CLIs, download and re-install the PKS and Kubernetes CLI distributions that are provided with Enterprise PKS on VMware Tanzu Network.

For more information about installing the CLIs, see the following topics:

Verify the Upgrade

After you apply changes to the Enterprise PKS tile and the upgrade is complete, do the following:

  1. Verify that your Kubernetes environment is healthy. To verify the health of your Kubernetes environment, see Verifying Deployment Health.

    For any cluster upgrade that fails, you can use the BOSH ID of the upgrade task for debugging. To retrieve the BOSH task ID, see Retrieve Cluster Upgrade Task ID in Verifying Deployment Health.

  2. Verify that the Enterprise PKS control plane remains functional by performing the following steps:

    1. Add more workloads and create an additional cluster. For more information, see About Cluster Upgrades in Maintaining Workload Uptime and Creating Clusters.
    2. Monitor the Enterprise PKS control plane in the Enterprise PKS tile > Status tab. Review the load and resource usage data for the PKS API and PKS Database VMs. If any levels are at capacity, scale up the VMs.

      Warning: Do not disable the PKS 1.7.x Upgrade - MySQL Clone errand. This errand must remain set to Default (On) at all times.

(Optional) Reduce PKS Database Ephemeral Disk Size

You can return your PKS Database ephemeral disk to a smaller size after the upgrade. You resized the disk while completing the steps in Verify Resource Config Configuration above.

To return the PKS Database ephemeral disk to a smaller size, do the following:

  1. In the Enterprise PKS tile, click Resource Config.

  2. For PKS Database, set the VM TYPE to be the same as the VM TYPE of the PKS API.

  3. Click Save.

  4. Click Review Pending Changes. For more information about this Ops Manager page, see Reviewing Pending Product Changes.

  5. Click Apply Changes.


Please send any feedback you have to pks-feedback@pivotal.io.