Upgrade

Supported upgrade paths

The following table lists supported upgrade paths to IG 2023.2:

Version	Upgrade supported?
IG 6.x	✔
IG 7.x	✔

Version

Upgrade supported?

IG 6.x

✔

IG 7.x

✔

For more information, refer to Checking your product versions are supported in the ForgeRock Knowledge Base.

For unsupported, legacy deployments, ForgeRock can assist you in the upgrade process.

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 in the release notes for the new version. In particular, make sure 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 in the release notes for the new version. In particular, make sure 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 changed functionality, and adjust your configuration as necessary.
Switch to the replacement settings in 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.

Upgrade IG instances

For information about the versions that are supported for upgrade, refer to 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.