Upgrade

Learn about upgrade between supported versions of IG in Product Support Lifecycle Policy | PingGateway and Agents.

Planning the upgrade

Major, minor, maintenance, and patch product release levels are defined in ForgeRock product release levels. How much you need to do to upgrade IG software depends on the magnitude of the differences between the version you currently use and the new version.

Minor, maintenance, and patch releases have a limited effect on current functionality but contain necessary bug and security fixes. Keep up-to-date with maintenance and patch releases because the fixes are important, and the risk of affecting service is minimal.

Do these planning tasks before you start an upgrade:

Planning task Description

Planning task	Description
Find out what changed	Read the Release Notes for all releases between the version you currently use and the new version.
Understand the impact	Decide whether you need to change the configuration of your deployment for this release, and evaluate the work involved. Make sure you meet all of the requirements for the new version. In particular, make sure that you have a recent, supported Java version.
Plan for server downtime	At least one of your IG servers will be down during upgrade. Plan to route client applications to another server until the upgrade process is complete, and you have validated the result. Make sure client application owners are aware of the change, and let them know what to expect. If you have a single IG server, make sure the downtime happens in a low-usage window, and make sure you let client application owners plan accordingly.
Back up	The IG configuration is a set of files, including `admin.json`, `config.json`, `logback.xml`, routes, and scripts. Back up the IG configuration and store it in version control, so that you can roll back if something goes wrong. Also back up any tools scripts that you have edited for your deployment, and any trust stores used to connect securely.
Plan for rollback	Sometimes even a well-planned upgrade fails to go smoothly. In such cases, you need a plan to roll back smoothly to the pre-upgrade version. For IG servers, roll back by restoring a backed-up configuration.
Prepare a test environment	Before applying the upgrade in your production environment, always try to upgrade IG in a test environment. This will help you gauge the amount of work required, without affecting your production environment, and will help smooth out unforeseen problems. The test environment should resemble your production environment as closely as possible.

Find out what changed

Read the Release Notes for all releases between the version you currently use and the new version.

Understand the impact

Decide whether you need to change the configuration of your deployment for this release, and evaluate the work involved.

Make sure you meet all of the requirements for the new version. In particular, make sure that you have a recent, supported Java version.

Plan for server downtime

At least one of your IG servers will be down during upgrade. Plan to route client applications to another server until the upgrade process is complete, and you have validated the result. Make sure client application owners are aware of the change, and let them know what to expect.

If you have a single IG server, make sure the downtime happens in a low-usage window, and make sure you let client application owners plan accordingly.

Back up

The IG configuration is a set of files, including admin.json, config.json, logback.xml, routes, and scripts. Back up the IG configuration and store it in version control, so that you can roll back if something goes wrong.

Also back up any tools scripts that you have edited for your deployment, and any trust stores used to connect securely.

Plan for rollback

Sometimes even a well-planned upgrade fails to go smoothly. In such cases, you need a plan to roll back smoothly to the pre-upgrade version.

For IG servers, roll back by restoring a backed-up configuration.

Prepare a test environment

Before applying the upgrade in your production environment, always try to upgrade IG in a test environment. This will help you gauge the amount of work required, without affecting your production environment, and will help smooth out unforeseen problems.

The test environment should resemble your production environment as closely as possible.

Upgrade the IG configuration

Use the Release Notes for all releases between the version you currently use and the new version, and upgrade your configuration as follows:

Review all Incompatible changes, and adjust your configuration as necessary.
Switch to the replacement settings in Deprecation. 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 see 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.

Upgrade IG instances

For information about the versions that are supported for upgrade, see Upgrade paths.

Upgrade a single IG instance

Read and act on Plan the upgrade and Upgrade the IG configuration.
Back up the IG configuration, and store it in version control so that you can roll back if something goes wrong.
Stop IG.
Make the new configuration available on the file system, and specify the IG_INSTANCE_DIR env variable or ig.instance.dir system property to point to them.
Restart IG.
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.

Upgrade a site with multiple IG instances

The most straightforward option when upgrading sites with multiple IG instances is to upgrade in place. One by one, stop, upgrade, and then restart each server individually, leaving the service running during upgrade.

Migrate from web container mode to standalone mode

IG is delivered as a standalone Java executable in a .zip file, as well as in a .war file. Consider these points to migrate from IG in web container mode to IG in standalone mode.

Session replication between IG instances

High-availability of sessions is not supported in standalone mode.

Streaming asynchronous responses and events

In ClientHandler and ReverseProxyHandler, use only the default mode of asyncBehavior:non_streaming; responses are processed when the entity content is entirely available.

If the property is set to streaming, the setting is ignored.

Connection reuse when client certificates are used for authentication

In ClientHandler and ReverseProxyHandler, use only the default mode of stateTrackingEnabled:true; when a client certificate is used for authentication, connections cannot be reused.

If the property is set to false, the setting is ignored.

Tomcat configuration

Feature Standalone Tomcat

Feature	Standalone	Tomcat
Port number	Configure the `connectors` property of admin.json.	Configure in the `Connector` element of `/path/to/tomcat/conf/server.xml`: `<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" />`
HTTPS server-side configuration	Create a keystore, set up secrets, and configure secrets stores, ports, and ServerTlsOptions in admin.json. For information, see Configure IG for HTTPS (server-side) in standalone mode.	Create a keystore, and set up the SSL port in the `Connector` element of `/path/to/tomcat/conf/server.xml`. For information, see Configure IG for HTTPS (server-side) in Tomcat.
Session cookie name	Configure the `session` property of admin.json.	Configure `WEB-INF/web.xml` when you unpack the IG .war file.
Access logs	Configure in the Audit framework. For information, see Auditing your deployment and Audit framework.	Configure with `AccessLogValve`.
JDBC datasource	Configure with the JdbcDataSource object. For information, see JdbcDataSource. For an example, see Log in with credentials from a database.	Configure in the `GlobalNamingResources` element of `/path/to/tomcat/conf/server.xml`.
Environment variables	Configure in `$HOME/.openig/bin/env.sh`, where `$HOME/.openig` is the instance directory.	Configure in `/path/to/tomcat/bin/setenv.sh`.
Jar files	Add to `$HOME/.openig/extra`, where `$HOME/.openig` is the instance directory.	Add to to web container classpath; for example `/path/to/tomcat/webapps/ROOT/WEB-INF/lib`.

Port number

Configure the connectors property of admin.json.

Configure in the Connector element of /path/to/tomcat/conf/server.xml:

<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" />

HTTPS server-side configuration

Create a keystore, set up secrets, and configure secrets stores, ports, and ServerTlsOptions in admin.json.

For information, see Configure IG for HTTPS (server-side) in standalone mode.

Create a keystore, and set up the SSL port in the Connector element of /path/to/tomcat/conf/server.xml.

For information, see Configure IG for HTTPS (server-side) in Tomcat.

Session cookie name

Configure the session property of admin.json.

Configure WEB-INF/web.xml when you unpack the IG .war file.

Access logs

Configure in the Audit framework.

For information, see Auditing your deployment and Audit framework.

Configure with AccessLogValve.

JDBC datasource

Configure with the JdbcDataSource object.

For information, see JdbcDataSource.

For an example, see Log in with credentials from a database.

Configure in the GlobalNamingResources element of /path/to/tomcat/conf/server.xml.

Environment variables

Configure in $HOME/.openig/bin/env.sh, where $HOME/.openig is the instance directory.

Configure in /path/to/tomcat/bin/setenv.sh.

Jar files

Add to $HOME/.openig/extra, where $HOME/.openig is the instance directory.

Add to to web container classpath; for example /path/to/tomcat/webapps/ROOT/WEB-INF/lib.

Identity Gateway 7.2