Upgrading PAM on a Puppet-supported cluster

Upgrade Puppet Application Manager (PAM) on a Puppet-supported cluster to take advantage of new features and bug fixes, and to upgrade your cluster to the latest version of Kubernetes when one is available.

There are four possible upgrade types for Puppet Application Manager installations:

  • Online - For standalone or HA installations with a connection to the internet.
  • Offline - For air-gapped standalone or HA installations without a connection to the internet.
  • Online legacy - For standalone or HA installations created prior to April 2021 with a connection to the internet.
  • Offline legacy - For air-gapped standalone or HA installations created prior to April 2021 without a connection to the internet.
Restriction: You cannot use the upgrade process to move from a legacy deployment to a non-legacy deployment, or from standalone to HA, or vice versa. If you wish to change architecture types, see Migrating PAM data to a new system.

How to look up your Puppet Application Manager architecture

If you're running PAM on a Puppet-supported cluster, you can use the following command to determine your PAM architecture version:
kubectl get installer --sort-by=.metadata.creationTimestamp -o jsonpath='{.items[-1:].metadata.name}' ; echo
Depending on which architecture you used when installing, the command returns one of these values:
  • HA architecture: puppet-application-manager
  • Standalone architecture: puppet-application-manager-standalone
  • Legacy architecture: Any other value, for example, puppet-application-manager-legacy, cd4pe, or comply

Upgrade PAM online

Upgrade Puppet Application Manager (PAM) to take advantage of new features and bug fixes, and to upgrade your cluster to the latest version of Kubernetes when one is available.

Before you begin

Make sure you have captured an up-to-date snapshot of your PAM installation, which you can use to fall back the current version if there is an issue with the upgrade process. Learn more about snapshots at Backing up PAM using snapshots.

If you are upgrading from a version of PAM that used Weave (versions 1.100.3 and earlier) to a version of PAM that uses Flannel (versions 1.102.2 and later), pod-to-pod networking now depends on UDP port 8472 being open instead of ports 6783 and 6784.

Note: Starting with Puppet Application Manager 1.97.0, the force-reapply-addons flag is deprecated and generates a warning on use. If you are upgrading to a version prior to 1.97.0, you need to add the force-reapply-addons flag to the bash command using the -s flag.
  1. On your first primary node, rerun the installation script, passing in any arguments you included when installing for the first time:
    For standalone deployments, use:
    curl -sSL https://k8s.kurl.sh/puppet-application-manager-standalone | sudo bash

    For HA deployments, use:

    curl -sSL https://k8s.kurl.sh/puppet-application-manager | sudo bash
  2. If a new version of Kubernetes is available, the installer notes upgrade scripts to run on other nodes in an HA cluster.
    The installer also pauses before draining nodes as part of the Kubernetes upgrade. The node draining process can take several minutes to complete, during which time application workloads are stopped or migrated to other systems. This migration may cause several minutes of downtime while databases are rescheduled.

Upgrade PAM offline

Users operating in environments without direct access to the internet must use the links below to upgrade to the latest version of Puppet Application Manager (PAM).

Before you begin

Make sure you have captured an up-to-date snapshot of your PAM installation, which you can use to fall back the current version if there is an issue with the upgrade process. Learn more about snapshots at Backing up PAM using snapshots.

If you are upgrading from a version of PAM that used Weave (versions 1.100.3 and earlier) to a version of PAM that uses Flannel (versions 1.102.2 and later), pod-to-pod networking now depends on UDP port 8472 being open instead of ports 6783 and 6784.

Note: Starting with Puppet Application Manager 1.97.0, the force-reapply-addons flag is deprecated and generates a warning on use. If you are upgrading to a version prior to 1.97.0, you need to add the force-reapply-addons flag in Step 3 to the bash command after -s airgap.

To upgrade Puppet Application Manager:

  1. From a workstation with internet access, download the latest version of the installation bundle that is relevant for your installation type:
    For standalone installations, enter the following command (note that this bundle is ~4GB):
    curl -LO https://k8s.kurl.sh/bundle/puppet-application-manager-standalone.tar.gz

    For HA installations, enter the following command (note that this bundle is ~4GB):

    curl -LO https://k8s.kurl.sh/bundle/puppet-application-manager.tar.gz
  2. Copy the installation bundle to your primary and secondary nodes and unpack it:
    For standalone installations, use:
    tar xzf puppet-application-manager-standalone.tar.gz
    For HA installations, use:
    tar xzf puppet-application-manager.tar.gz
  3. Manually load the images from the installation bundle: 
    cat tasks.sh | bash -s load-images
  4. On your primary node, rerun the installation script, passing in any arguments you included when installing for the first time: 
    cat install.sh | sudo bash -s airgap
    Note: This script issues a prompt to run the task.sh and upgrade.sh scripts on your secondary nodes. Use the versions of these scripts from the downloaded bundle in step 2.
  5. If a new version of Kubernetes is available, the installer systems provide upgrade scripts to run on other nodes in an HA cluster. The installer also pauses before draining nodes as part of the Kubernetes upgrade. Node draining is performed as part of a Kubernetes upgrade.
    The node draining process can take several minutes to complete, during which time application workloads are stopped or migrated to other systems. This migration may cause several minutes of downtime while databases are rescheduled.
What to do next
When the deployment is complete, sign into Puppet Application Manager- http://<PUPPET APPLICATION MANAGER ADDRESS>:8800 - and verify that the new version number is displayed in the bottom left corner of the web UI.

PAM legacy upgrades

The legacy architecture is no longer supported. However, if you have not yet migrated to a supported architecture, you can use this method to upgrade Puppet Application Manager (PAM).

Before you begin
Make sure you have captured an up-to-date snapshot of your PAM installation, which you can use to fall back the current version if there is an issue with the upgrade process. Learn more about snapshots at Backing up PAM using snapshots.
Legacy architecture is no longer supported: The legacy architecture utilizes Rook 1.0, which is incompatible with Kubernetes version 1.20 and newer versions. Kubernetes version 1.19 is no longer receiving security updates. The legacy architecture reached the end of its support lifecycle on 30 June 2022, and Puppet no longer updates legacy architecture components. For information on migrating data from a legacy architecture to a standalone or HA architecture, go to our Support Knowledge Base instructions:
Restriction: It is not possible to upgrade from an online legacy install to a new offline install configuration. Similarly, upgrades from an offline legacy configuration to a new online install are not supported.

To upgrade a legacy version of Puppet Application Manager on nodes with internet access:

  1. On your node (or control plane node if you have a HA deployment), rerun the installation script, passing in any arguments you included when installing for the first time:
    • For standalone installs:
      curl -sSL https://k8s.kurl.sh/puppet-application-manager-legacy | sudo bash -s force-reapply-addons
    • For HA installs:
      curl -sSL https://k8s.kurl.sh/puppet-application-manager-legacy | sudo bash -s ha force-reapply-addons
  2. If a new version of Kubernetes is available, the systems provide upgrade scripts to run on each node in your cluster.
    Node draining is performed as part of a Kubernetes upgrade. The node draining process can take several minutes to complete.
    Note: During the Kubernetes upgrade process, nodes are not able to properly route network connections. If you have a HA deployment, make sure you have load balancers or a multi-node fail-over process in place, or schedule downtime before upgrading.

PAM offline legacy upgrades

The legacy architecture is no longer supported. However, if you have not yet migrated to a supported architecture, you can use this method to upgrade Puppet Application Manager (PAM) on offline nodes.

Before you begin
Make sure you have captured an up-to-date snapshot of your PAM installation, which you can use to fall back the current version if there is an issue with the upgrade process. Learn more about snapshots at Backing up PAM using snapshots.
Legacy architecture is no longer supported: The legacy architecture utilizes Rook 1.0, which is incompatible with Kubernetes version 1.20 and newer versions. Kubernetes version 1.19 is no longer receiving security updates. The legacy architecture reached the end of its support lifecycle on 30 June 2022, and Puppet no longer updates legacy architecture components. For information on migrating data from a legacy architecture to a standalone or HA architecture, go to our Support Knowledge Base instructions:
Restriction: It is not possible to upgrade from an online legacy install to a new offline install configuration. Similarly, upgrades from an offline legacy configuration to a new online install are not supported.

To upgrade Puppet Application Manager on nodes without a connection to the internet:

  1. From a workstation with internet access, download the latest version of the cluster installation bundle (note that this bundle is ~4GB): 
    https://k8s.kurl.sh/bundle/puppet-application-manager-legacy.tar.gz
  2. Copy the installation bundle to your primary and secondary Puppet Application Manager nodes and unpack it: 
    tar xzf puppet-application-manager-legacy.tar.gz
  3. Rerun the installation script. Don't forget to pass in any additional arguments you included when installing for the first time you installed the product:

    For standalone installs use:

    cat install.sh | sudo bash -s airgap force-reapply-addons

    For HA installs use:

    cat install.sh | sudo bash -s airgap ha force-reapply-addons
    Note: During the upgrade process, follow any prompts to run commands on your other cluster nodes.
What to do next
When the deployment is complete, sign into Puppet Application Manager and verify that the new version number is displayed in the bottom center of the web UI.