Upgrade the platform from version 7.2 to 7.3

If you’ve already installed ForgeRock Identity Platform version 7.2 using artifacts from the forgeops repository, follow the steps provided on this page to upgrade to version 7.3.

Use these steps to upgrade the platform in place, with no downtime.

This upgrade methodology has been tested against a deployment based on ForgeRock’s evaluation-only Docker images with basic configuration settings.

Because the ForgeRock Identity Platform is highly customizable, it is difficult for ForgeRock to test all possible upgrade scenarios. It is your responsibility to validate that these upgrade steps work correctly in a test environment with your customized configuration before you upgrade a production environment.

Prerequisites and assumptions

To upgrade the platform from version 7.2 to 7.3, you’ll need:

A running version 7.2 CDK deployment with your current AM and IDM configurations
A running version 7.2 CDM deployment
A forgeops repository clone with a branch that contains 7.2 artifacts
A forgeops repository clone with a branch that contains 7.3 artifacts

Example commands in the steps on this page assume:

7.2-profile is the name of the 7.2 configuration profile.
Your 7.2 CDM deployment is a small cluster.
Your 7.2 CDM deployment does not include IG.

When you perform the upgrade:

Choose a different name for the configuration profile, if you prefer.
Specify a different cluster size, if applicable.
Add commands to upgrade IG, if applicable.

Back up critical data

Before upgrading, back up all critical data, including:

Directory data stored in the ds-idrepo and ds-cts backends
AM and IDM configuration data
Customized artifacts in your forgeops repository clone

After you’ve started to upgrade, you may not be able to roll back directory data easily because the data is upgraded in place. If you need to roll back directory data, you’ll have to redeploy DS and restore directory data from a backup. Consider backing up directory data on volume snapshots for a simpler restore scenario.

Export the version 7.2 AM and IDM configurations

Locate a branch of your forgeops repository clone that contains version 7.2 artifacts and check out the branch.
(Optional) Check out a new branch based on the branch that contains version 7.2 artifacts.
Locate a namespace running version 7.2 of the CDK that contains your current AM and IDM configurations.
If you’ve never exported the AM and IDM configurations on this system, initialize directories where the configuration profiles will be exported:
```
$ cd /path/to/forgeops/docker/am/config-profiles
$ cp -r cdk 7.2-profile
$ cd /path/to/forgeops/docker/idm/config-profiles
$ mkdir -p 7.2-profile/conf
```
This step is not necessary for the latest 7.2 branches of the forgeops repository, but performing it causes no ill effect.

Export the AM and IDM configurations from the running 7.2 CDK deployment:

$ cd /path/to/forgeops
$ ./bin/config export am 7.2-profile --sort 
$ ./bin/config export idm 7.2-profile --sort

Run the git add . and git commit commands.

Upgrade the exported configuration profiles to version 7.3

Locate the branch of your forgeops repository clone that contains version 7.3 artifacts and check out the branch.

The latest branch with 7.3 artifacts is the release/7.3-20240131 branch.
(Optional) Check out a new branch based on the branch that contains version 7.3 artifacts.
Copy the configuration profiles you exported from your 7.2 CDK into the 7.3 branch:
- Copy the AM 7.2 configuration profile into the /path/to/forgeops/docker/am/config-profiles directory.
- Copy the IDM 7.2 configuration profile into the /path/to/forgeops/docker/idm/config-profiles directory.

Upgrade the AM configuration in the 7.3 branch.

Run the am-config-upgrader utility:

$ cd /path/to/forgeops
$ ./bin/am-config-upgrader docker/am/config-profiles/7.2-profile

Upgrade the IDM configuration in the 7.3 branch.

Follow the steps in Migrate your configuration in the IDM documentation.
Run the git add . and git commit commands.

Upgrade the 7.2 pods to 7.3 and build custom 7.3 Docker images

Set your Kubernetes context so that you can access the cluster on which you deployed the version 7.2 CDM.
Check out the branch of your forgeops repository clone that contains version 7.3 artifacts.

This is important! If you’ve checked out a branch that contains version 7.2 artifacts, the forgeops install command reinstalls version 7.2 instead of upgrading your pods to version 7.3.
Upgrade the ds-cts pods from 7.2 to 7.3:
```
$ cd /path/to/forgeops
$ ./bin/forgeops install ds-cts --small
```
This command updates one ds-cts pod at a time. Run the kubectl get pods --watch command to observe the pod upgrades.

After all the ds-cts pods have been upgraded, run the ds-debug.sh command to verify that directory replication is working correctly. Run commands similar to the following for each ds-cts pod:
```
$ ./bin/ds-debug.sh rstatus podname
```
Upgrade the ds-idrepo pods from 7.2 to 7.3:
```
$ cd /path/to/forgeops
$ ./bin/forgeops install ds-idrepo --small
```
This command updates one ds-idrepo pod at a time. Run the kubectl get pods --watch command to observe the pod upgrades.

After all the ds-idrepo pods have been upgraded, run the ds-debug.sh command to verify that directory replication is working correctly. Run commands similar to the following for each ds-idrepo pod:
```
$ ./bin/ds-debug.sh rstatus podname
```
Check out the branch of your forgeops repository clone that contains version 7.3 artifacts.

This branch should contain the 7.2-profile configuration profile you upgraded to work with version 7.3.

Build Docker images for version 7.3 that contain the 7.2-profile configuration profile:

$ cd /path/to/forgeops
$ ./bin/forgeops build am --config-profile 7.2-profile --push-to my-repo
$ ./bin/forgeops build idm --config-profile 7.2-profile --push-to my-repo

The newly-built Docker images are based on ForgeRock’s evaluation-only Docker images.

Upgrade the ForgeRock Identity Platform pods from 7.2 to 7.3:
```
$ ./bin/forgeops install ui --small
$ ./bin/forgeops install am --small
$ ./bin/forgeops install idm --small
```
Wait for the pod upgrades to complete. Run the kubectl get pods --watch command to observe the pod upgrades.

In version 7.2, the default number of AM pods in a small configuration is three. In version 7.3, that’s been changed to two. If you use the default small size cluster configuration, you’ll have one fewer AM pod after completing the AM upgrade.
Start the AM and IDM admin UIs in your upgraded CDM deployment. Verify that:
- The start page for each admin UI indicates that the component version is 7.3, not 7.2.
- AM and IDM use your custom configuration.
If you are using a Kubernetes-based ForgeRock Identity Platform deployment in production, you must rebuild base Docker images for version 7.3, and then build custom Docker images based on those images:
1. Build your own Docker base images. Refer to Your own base Docker images for more information.
2. Rebuild your custom Docker images, basing them on the images you built in the previous step. Refer to Create Docker images for use in production for more information.

ForgeOps