Upgrade
Learn about upgrade between supported versions of PingGateway in Product Support Lifecycle Policy | PingGateway and Agents.
Learn about upgrade of routes in Studio in Upgrade from an earlier version of Studio.
This section describes how to upgrade a single PingGateway instance. The most straightforward option when upgrading sites with multiple PingGateway instances is to upgrade in place. One by one, stop, upgrade, and then restart each server individually, leaving the service running during the upgrade.
PingGateway supports the following types of upgrade:
- Drop-in software update
-
Usually, an update from a version of PingGateway to a newer minor version, as defined in Product Support Lifecycle Policy | PingGateway and Agents. For example, the update from 2023.2 to 2023.4.
Drop-in software updates can introduce additional functionality and fix bugs or security issues. Consider the following restrictions for drop-in software updates:
-
Don’t require any update to the configuration
-
Cannot cause feature regression
-
Can change default or previously configured behavior only for bug fixes and security issues
-
Can deprecate but not remove existing functionality
-
- Major upgrade
-
Usually, an upgrade from a version of PingGateway to a newer major version, as defined in Product Support Lifecycle Policy | PingGateway and Agents. For example, the upgrade from 7.2 to 2023.2.
Major upgrades can introduce additional functionality and fix bugs or security issues. Major upgrades don’t have the restrictions of drop-in software update. Consider the following features of major upgrades:
-
Can require code or configuration changes
-
Can cause feature regression
-
Can change default or previously configured behavior
-
Can deprecate and remove existing functionality
-
Drop-in software update with binaries
-
Read and act on Plan the upgrade.
-
Back up the PingGateway configuration and store it in version control so that you can roll back if something goes wrong.
-
Make the new configuration available on the file system.
By default, PingGateway configuration files are located under
$HOME/.openig(on Windows%appdata%\OpenIG). For information about how to use a different location, refer to Configuration location. -
Restart PingGateway from the new installation directory.
-
In a test environment that simulates your production environment, validate that the upgraded service performs as expected with the new configuration. Check the logs for new or unexpected notifications or errors.
-
Allow client application traffic to flow to the upgraded site.
Drop-in software update with Docker files
-
Read and act on Plan the upgrade.
-
Back up the PingGateway configuration and store it in version control so that you can roll back if something goes wrong.
-
In a test environment that simulates your production environment, validate that the upgraded service performs as expected with the new configuration. Check the logs for new or unexpected notifications or errors.
-
Allow client application traffic to flow to the upgraded site.
Major upgrade with binaries
-
Read and act on Plan the upgrade.
-
Use the release notes for all releases between the version you currently use and the new version, and create a new configuration as follows:
-
Review all incompatible changes and removed functionality, and adjust your configuration as necessary.
-
Switch to the replacement settings for deprecated functionality. Although deprecated objects continue to work, they add to the notifications in the logs and are eventually removed.
-
Check the lists of fixes, limitations, and known issues to find out if they impact your deployment.
-
Recompile your Java extensions. The method signature or imports for supported and evolving APIs can change in each version.
-
Read the documentation updates for new examples and information that can help with your configuration.
-
-
Back up the PingGateway configuration and store it in version control so that you can roll back if something goes wrong.
-
Make the new configuration available on the file system.
By default, PingGateway configuration files are located under
$HOME/.openig(on Windows%appdata%\OpenIG). For information about how to use a different location, refer to Configuration location. -
Restart PingGateway from the new installation directory.
-
In a test environment that simulates your production environment, validate that the upgraded service performs as expected with the new configuration. Check the logs for new or unexpected notifications or errors.
-
Allow client application traffic to flow to the upgraded site.
Major upgrade with Docker files
-
Read and act on Plan the upgrade.
-
Use the release notes for all releases between the version you currently use and the new version, and create a new configuration as follows:
-
Review all incompatible changes and removed functionality, and adjust your configuration as necessary.
-
Switch to the replacement settings for deprecated functionality. Although deprecated objects continue to work, they add to the notifications in the logs and are eventually removed.
-
Check the lists of fixes, limitations, and known issues to find out if they impact your deployment.
-
Recompile your Java extensions. The method signature or imports for supported and evolving APIs can change in each version.
-
Read the documentation updates for new examples and information that can help with your configuration.
-
-
Back up the PingGateway configuration and store it in version control so that you can roll back if something goes wrong.
-
In a test environment that simulates your production environment, validate that the upgraded service performs as expected with the new configuration. Check the logs for new or unexpected notifications or errors.
-
Allow client application traffic to flow to the upgraded site.
Post upgrade tasks
After upgrade, review the what’s new section in the release notes and consider activating new features and functionality.
Rollback
| Before you roll back to a previous version of PingGateway, consider whether any change to the configuration during or since upgrade could be incompatible with the previous version. |
-
Plan for server downtime
Plan to route client applications to another server until the rollback process is complete and you have validated the result. Make sure the owners of client application are aware of the change, and let them know what to expect.
-
Make the new configuration available on the file system.
By default, PingGateway configuration files are located under
$HOME/.openig(on Windows%appdata%\OpenIG). For information about how to use a different location, refer to Configuration location.
-
Plan for server downtime
Plan to route client applications to another server until the rollback process is complete and you have validated the result. Make sure the owners of client application are aware of the change, and let them know what to expect.