Upgrading Clusters

Page last updated:

This topic describes how to upgrade Kubernetes clusters provisioned by Enterprise Pivotal Container Service (Enterprise PKS). Upgrading a cluster makes the cluster’s internal PKS version match your PKS control plane’s PKS version.

For information about updating clusters, which modifies a cluster’s configuration, see pks update-cluster in the PKS CLI documentation.

Overview

When upgrading Enterprise PKS, you can choose one of the following approaches:

  • Upgrade the Enterprise PKS tile and all Enterprise PKS-provisioned Kubernetes clusters simultaneously. This is the default behavior of the Enterprise PKS tile.
  • Upgrade the Enterprise PKS tile only and then upgrade Enterprise PKS-provisioned Kubernetes clusters separately. If you want to upgrade your clusters separately, do the following:

    1. Review Limitations.
    2. Complete the steps listed in Prerequisites.
    3. Complete the steps listed in Upgrade Clusters.

    Note: When Enterprise PKS is set to upgrade the Enterprise PKS tile only and not the clusters, the Kubernetes cluster version falls behind the Enterprise PKS tile version. If the clusters fall more than one version behind the tile, Enterprise PKS cannot upgrade the clusters. The clusters must be upgraded to match the Enterprise PKS tile version before the next tile upgrade.

For more information about Enterprise PKS upgrades, see What Happens During Enterprise PKS Upgrades.

Prerequisites

Before upgrading Kubernetes clusters provisioned by Enterprise PKS, you must do the following:

  • Install the PKS command line interface (CLI) v1.5. For more information, see Installing the PKS CLI.
  • Disable Upgrade all clusters errand in the Enterprise PKS tile. For more information, see Modify Errand Configuration in the Enterprise PKS Tile below.

    Warning: If you disable Upgrade all clusters errand when upgrading the Enterprise PKS tile or updating your tile configuration, you must upgrade all your Kubernetes clusters before the next Enterprise PKS upgrade or tile configuration update.

Modify Errand Configuration in the Enterprise PKS Tile

To modify errand configuration when upgrading your Enterprise PKS version, perform the steps below. For more information about upgrading Enterprise PKS, see Upgrading Enterprise PKS.

  1. If you have not already, import the product file for the new Enterprise PKS version to the Ops Manager Installation Dashboard.
  2. In the Enterprise PKS tile, navigate to the Errands pane.
  3. Disable Upgrade all clusters errand and click Save. Errands pane
  4. Return to the Ops Manager Installation Dashboard and click Review Pending Changes.
  5. Select Enterprise PKS and any other products you want to deploy and click Apply Changes.

Upgrade Clusters

To upgrade a Kubernetes cluster provisioned by Enterprise PKS:

  1. On the command line, run the following command to log in to Enterprise PKS:

    pks login -a PKS-API -u USERNAME -k
    
    Where:

    • PKS-API is the domain name for the PKS API that you entered in Ops Manager > Enterprise PKS > PKS API > API Hostname (FQDN). For example, api.pks.example.com.
    • USERNAME is your user name.

      See Logging in to Enterprise PKS for more information about the pks login command.

      Note: If your operator has configured Enterprise PKS to use a SAML identity provider, you must include an additional SSO flag to use the above command. For information about the SSO flags, see the section for the above command in PKS CLI. For information about configuring SAML, see Configure SAML as an Identity Provider in the Installing topic for your IaaS.

  2. Run the following command to upgrade your cluster:

    pks upgrade-cluster CLUSTER-NAME
    

    Where CLUSTER-NAME is the name of the Kubernetes cluster you want to upgrade. The pks upgrade-cluster command lets you upgrade only one cluster. To upgrade multiple clusters, you must run the pks upgrade-cluster command for each cluster you want to upgrade.

    Note: When you make multiple cluster upgrade requests, Enterprise PKS upgrades these clusters in parallel with a limit of four concurrent cluster upgrades. If you schedule more than four cluster upgrades, Enterprise PKS queues the upgrades. If you submit too many upgrade requests, an error may occur. For more information, see Error During Individual Cluster Upgrades.

For more information about the pks upgrade-cluster command, see pks upgrade-cluster in the PKS CLI documentation.

Note: The PKS CLI also provides the similar pks update-cluster command. Use pks update-cluster when modifying a cluster’s configuration, such as to change a cluster’s node count or to apply IaaS tagging to a cluster’s VMs. For more information about pks update-cluster, see pks update-cluster in the PKS CLI documentation.

Limitations

If you upgrade the Enterprise PKS tile only and then attempt to resize or update your existing Kubernetes clusters, these operations fail until you upgrade the clusters.

If you want to upgrade the Enterprise PKS tile and your existing Kubernetes clusters simultaneously, do not disable Upgrade all clusters errand in the Enterprise PKS tile.


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