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 upgrade from a legacy deployment to a non-legacy deployment, or from standalone to HA, or a HA to a standalone deployment.

Migrating data

When migrating data to a new cluster, your system must meet the following requirements

  • The Puppet Application Manager must be configured to support Full Snapshots (Instance).

  • Velero must be configured to use an external snapshot destination accessible to both the old and new clusters, such as S3 or NFS.

  • Both the old and new clusters must have the same connection status (online/offline). Migrating from offline to online clusters or vice versa is not supported.

  • You must use the 30 June 2021 or later release of Puppet Application Manager.

  • For offline installs, both the old and new clusters must use the same version of Puppet Application Manager.

Although there are restrictions on upgrade paths, it is possible to migrate data by setting up a new cluster and recovering data via a snapshot between:

  • Standalone and HA deployments

  • Legacy to standalone deployments

  • Legacy to HA deployments

For more information on using snapshots for data migration, see Disaster recovery or migration using a snapshot.

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.

  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).

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 ~6GB):
    https://k8s.kurl.sh/bundle/puppet-application-manager-standalone.tar.gz

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

    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. Run the installation command:
    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.
  4. 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

Use this method to upgrade Puppet Application Manager (PAM) from a version installed before May 2021.

Restriction: It is not currently 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 currently supported.

The legacy version reflects an older configuration that used Ceph 1.0 which hosted data directly on the file system. Puppet no longer recommend this for new installs, but maintains it to support existing installs and ensure other components can be kept up-to-date.

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
    • For HA installs:
      curl -sSL https://k8s.kurl.sh/puppet-application-manager-legacy | sudo bash -s ha
  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

Use this method to upgrade Puppet Application Manager (PAM) on offline nodes from a version installed before April 2021.

Restriction: It is not currently 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 currently 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 

    For HA installs use:

    cat install.sh | sudo bash -s airgap ha
    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.