Ping Identity Devops

Upgrading PingFederate

In a DevOps environment, upgrades can be simplified through automation, orchestration, and separation of concerns.

Starting with PingFederate 12.2, the server automatically upgrades the configuration data in server/default/data when it starts against data created by an earlier version. In containers, this means that upgrading a deployment with a persistent volume on /opt/out/instance/server/default/data is usually just an image-tag change followed by a restart. The Upgrade Utility is only required when the target version is earlier than 12.2, or when files outside server/default/data (templates, run.properties, and other conf files) must be migrated.

Choose the path that matches your target version:

Caveats

  1. This Document Assumes Kubernetes and Helm

    The terms in this document will focus on deployments in a Kubernetes Environment using the ping-devops Helm chart. However, the concepts should apply to any containerized PingFederate Deployment.

  2. Tags referenced in this document will become outdated

    The examples referenced in this document point to a specific tag. This tag may not exist anymore at the time of reading. To correct the issue, update the tag on your file to N -1 from the current PF version.

  3. Upgrades from Traditional Deployment

    It may be desirable to upgrade PingFederate along with migrating from a traditional environment. This is not recommended. Instead you should upgrade your current environment to the desired version of PingFederate and then create a profile that can be used in a containerized deployment.

  4. Ingress

    The values.yaml files mentioned in this document expects and nginx ingress controller with class nginx-public. It is not an issue if your environment doesn’t have this, the created ingresses will not be used.

Upgrade to PingFederate 12.2 or later

When a PingFederate 12.2 or later server starts and finds configuration data written by an earlier version, it upgrades the data automatically before serving requests. On a successful startup the admin log reports the upgrade, for example Performing data upgrade …​ from PingFederate version 12.3.6 to version 13.1.3 followed by Upgrade complete, Original pingFederate data version upgraded from: 12.3.6. For background on this behavior, including the Configuration Archive import path, see the PingFederate Upgrade FAQ and Upgrade considerations introduced in PingFederate 12.x in the PingFederate documentation.

This path assumes your deployment persists /opt/out/instance/server/default/data on a persistent volume, as described in Operating patterns and shown in 30-helm/pingfederate-upgrade/02-upgraded.yaml. If you do not persist the data directory, there is no data to upgrade — deploy the new image and let your server profile rebuild the configuration. If you are moving to Flex images rather than upgrading in place, see Migrate PingFederate to Flex Images.

  1. Back up the data directory from the running admin pod, while it is still on the old version. The upgrade modifies the data in place, and rolling back requires this backup.

    kubectl exec <release>-pingfederate-admin-0 -- \
  cp -r /opt/out/instance/server/default/data /tmp/data-pre-upgrade
kubectl cp <release>-pingfederate-admin-0:/tmp/data-pre-upgrade ./data-pre-upgrade

  2. In your values file, set the pingfederate-admin image tag to the target version and set pingfederate-engine.container.replicaCount to 0, then run:

    helm upgrade --install <release> pingidentity/ping-devops -f <values-file>

    The admin starts on the new version and upgrades the configuration data automatically. The engines must not run against the admin while versions differ — PingFederate servers running adjacent versions (for example, 12.1 and 12.2) cannot communicate with each other.

  3. Connect to the admin console and confirm that Cluster Management reports the target version.

  4. In your values file, restore pingfederate-engine.container.replicaCount and set the engine image tag to the same target version, then run helm upgrade --install again. The engines join the upgraded cluster.

The automatic upgrade covers configuration data in server/default/data only. It does not migrate files delivered outside that directory by the image or your server profile, such as templates and run.properties settings. Review the upgrade considerations page for your target version and update your server profile to match.

The automatic upgrade is one-way. To roll back, redeploy the previous image tag and restore the data directory from the backup taken in step 1.

Upgrade to a version earlier than 12.2

For target versions earlier than 12.2, run the Upgrade Utility inside the container against a copy of your data, then move the upgraded files into place. The Utility upgrades the data directory and produces a diff against your server profile, which you then reconcile.

Persistent Volume Upgrade will include steps helpful to both pieces. Server Profile Upgrade will discuss extracting upgraded files.

Step: Persistent Volume Upgrade

Steps needed in both Server-Profile upgrade and Persistent Volume upgrade include:

  1. Deploy your PingFederate version and server profile as background process

  2. Upgrade profile in container

    1. Backup the files in your profile.

    2. Download the PingFederate software bits for the new version.

    3. Run upgrade utility

    4. diff to view the changes. (optional)

  3. Reconfigure any variablized components.

  4. Export changes to your profile

Here we will walk through an example volume upgrade.

Your orchestration user will need access to kubectl exec -it <pod> — sh for multiple steps here.

The suggested script should not be used if a persistent volume is attached to /opt/out. New software bits will not include special files built into the docker image. It is recommended to mount volumes on PingFederate Admin to /opt/out/instance/server/default/data.

Deploy PingFederate as a Background Process

Deploy your PingFederate version and server profile as background process with Helm:

If you’re using this example as is, you’ll need a devops-secret.

Be sure to change the ingress domain name value to your domain in 01-background.yaml.

Be sure to change the image tag value in 01-background.yaml.

 
# If necessary, add the chart repository and update
helm repo add pingidentity https://helm.pingidentity.com/
helm repo update

helm upgrade --install pf-upgrade pingidentity/ping-devops \
  -f 30-helm/pingfederate-upgrade/01-background.yaml

The args section starts PingFederate as a background process and tail -f /dev/null as the foreground process.

Upgrade Profile in Container

The steps for upgrading can be automated with a script. Example scripts are included at 30-helm/pingfederate-upgrade/hooks.

To use the scripts:

Copy the hooks folder to your PingFederate container

kubectl cp 30-helm/pingfederate-upgrade/hooks pf-upgrade-pingfederate-admin-0:/opt/staging

Copy the target PingFederate license to your PingFederate container. See Using Your DevOps User and Key to retrieve an evaluation license, or mount an existing product license.

kubectl cp pingfederate.lic pf-upgrade-pingfederate-admin-0:/tmp

Copy the target PingFederate software to your PingFederate container. See Download Product Installation Files.

kubectl cp pingfederate-11.1.1.zip pf-upgrade-pingfederate-admin-0:/tmp

  1. Navigate to Ping Identity’s Download webpage.

  2. Select a Product download page, for example: PingFederate Download Page.

  3. Click on the download button for the desired installation method and product version.

    1. If prompted to sign in, please sign in and the download will begin. Alternatively, Sign In Here.

    2. If you do not have a Ping Identity account, you can create one on the Account Creation Page.

Run the Upgrade Utility

The pf-upgrade.sh script will:

  • Verify both the PingFederate software bits and new license file is on the container

  • Backup the current /opt/out folder to /opt/current_bak

  • Run the upgrade utility

  • Overwrite /opt/out or /opt/out/instance/server/default/data with upgraded files

  • Run diff between /opt/staging (server-profile location) and respective upgraded file. Diffs can be found in /tmp/stagingDiffs

Exec into the container and run the script.

kubectl exec -it pf-upgrade-pingfederate-admin-0 -- sh
cd /opt/staging/hooks
sh pf-upgrade.sh 10.3.4

At the conclusion of the script you will have an upgraded /opt/out/instance/server/default/data folder.

Step: Server Profile Upgrade

If your profile is applied on each start of your container, you should keep your profile up to date with the product version you are deploying.

After the previously run script, you can find upgraded profile files in /opt/new_staging These files will be hard-coded and you should follow Build a PingFederate Profile as needed for templating.

Additionally, If you use the bulk-config data.json import it will not be found here. It should be imported via the standard process on the next container start.

Step: Post Upgrade

To enable PingFederate admin as a foreground process, scale it down first.

kubectl scale sts pf-upgrade-pingfederate-admin --replicas=0

Finally, update PingFederate image version to new target PingFederate version and run as normal.

Be sure to change the ingress domain name value to your domain in 02-upgraded.yaml.

Be sure to change the image tag value in 02-upgraded.yaml.

 
helm upgrade --install pf-upgrade pingidentity/ping-devops \
  -f 30-helm/pingfederate-upgrade/02-upgraded.yaml

This will restart the admin console, and trigger a rolling update of all the engines.

The final yaml 30-helm/pingfederate-upgrade/02-upgraded.yaml still points to the same profile. The steps that should have been completed in Server Profile Upgrade were not included.

Connecting to the admin console will now show the upgraded version in cluster management.

Step: Migrate Cluster Discovery Settings

To simplify future upgrades, migrate the cluster discovery settings in the tcp.xml file to the jgroups.properties file.

You can find the default jgroups.properties file here.

For more information, refer to Migrate Cluster Discovery Settings in the PingFederate admin guide.