Upgrade the platform from version 7.1 to 7.2

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

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

This upgrade methodology has been tested on 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.1 to 7.2, you’ll need:

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

Example commands in the steps on this page assume:

7.1-profile is the name of the 7.1 configuration profile.
Your 7.1 CDM deployment is a small cluster.
Your 7.1 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

To back up directory data, use the DS 7.1 backup utility.

After you’ve started to upgrade, you may not be able to roll back directory data easily because the data gets upgraded in place. If you need to roll back directory data, you’ll have to redeploy DS and restore directory data from a backup.

Export the version 7.1 AM and IDM configurations

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

Create a new branch based on version 7.1 artifacts. For example:

$ cd /path/to/forgeops/
$ git checkout -b 7.1-branch release/7.1-20221111

Locate the namespace that contains your current AM and IDM running version 7.1 of the CDK 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/bin
$ ./config.sh init --profile cdk
$ ./config.sh save --component am --profile 7.1-profile
$ ./config.sh save --component idm --profile 7.1-profile

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

$ cd /path/to/forgeops
$ ./bin/config export --component am --profile 7.1-profile
$ ./bin/config export --component idm --profile 7.1-profile

Verify that the exported configurations are in the corresponding configuration directories under /config/7.0/7.1-profile directory.
Run the git add . and git commit commands.

Upgrade the exported 7.1 configuration profiles to version 7.2

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

The latest branch with 7.2 artifacts is the release/7.2-20240117 branch.

Create a new branch based on version 7.2 artifacts. For example:

$ cd /path/to/forgeops/
$ git checkout -b 7.2-branch release/7.2-20240117

Restore the exported 7.1 configuration profiles into the 7.2-branch:

$ cd /path/to/forgeops of 7.2-branch
$ git restore --source 7.1-branch config/7.0/7.1-profile

Move the configuration profiles you restored from your 7.1 CDK into your 7.2 branch:

Refer to the "Configuration profiles moved to docker directory" section in the release notes for June 30, 2022.
1. Move the contents of the config/7.0/7.1-profile/am directory to the docker/am/config-profiles/7.1-profile path.
2. Move the contents of the config/7.0/7.1-profile/amster directory to the docker/amster/config-profiles/7.1-profile path .
3. Move the contents of the config/7.0/7.1-profile/idm directory to the docker/idm/config-profiles/7.1-profile path .

Upgrade the AM configuration in the 7.2 branch:

Edit and input the following lines in the am-config-upgrader file to use the correct version of am-config-upgrader:
```
REPO=${REPO:-gcr.io/forgerock-io/am-config-upgrader/pit1}
TAG=7.2.2-e4753f70465b5df8d7cfdf943d323b4e3100b1ac
```

Run am-config-upgrader:

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

Upgrade the IDM configuration in the 7.2 branch.

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

Migrate your 7.1 CDM deployment to version 7.2

Set your Kubernetes context so that you can access the cluster on which you deployed the version 7.1 CDM.

Upgrade the Secret Agent operator to version 1.1.5:

$ kubectl apply -f https://github.com/ForgeRock/secret-agent/releases/download/v1.1.5/secret-agent.yaml

Migrate the secrets to the new format:

$ cd /path/to/forgeops/upgrade/71to72/ds
$ ./migrate.sh secrets

Patch the update strategy for the DS stateful sets:

$ cd /path/to/forgeops/upgrade/71to72/ds
$ ./migrate.sh strategy idrepo
$ ./migrate.sh strategy cts

Prime the DS persistent volumes, so that they can be managed by the ds-operator:

$ cd /path/to/forgeops/upgrade/71to72/ds
$ ./migrate.sh prime idrepo-0
$ ./migrate.sh prime idrepo-1

$ ./migrate.sh prime cts-0
$ ./migrate.sh prime cts-1
$ ./migrate.sh prime cts-2

Update the DS stateful sets to version 7.2:

$ ./migrate.sh patch idrepo
$ ./migrate.sh patch cts

Refresh the non-primary DS pods:
1. Delete the DS replica pods, ds-idrepo-1, ds-cts-1, and ds-cts-2, but do not delete the primary pods ds-idrepo-0 and ds-cts-0:
```
$ kubectl delete pod ds-idrepo-1
$ kubectl delete pod ds-cts-1
$ kubectl delete pod ds-cts-2
```
1. Verify that the deleted ds-idrepo-1, ds-cts-1, and ds-cts-2 pods have resumed running.

Delete the primary DS pods:

$ kubectl delete pod ds-idrepo-0
$ kubectl delete pod ds-cts-0

Update the DS services:

$ ./migrate.sh patch-service idrepo
$ ./migrate.sh patch-service cts

Install DS components using the forgeops command:

$  cd /path/to/forgeops/
$ ./bin/forgeops install ds-idrepo --small
$ ./bin/forgeops install ds-cts --small

Add in the DS resources' owner reference:

$ cd /path/to/forgeops/upgrade/71to72/ds
$ ./migrate.sh patch-owner idrepo
$ ./migrate.sh patch-owner cts

Upgrade the platform to version 7.2

After migrating DS to use version 7.2 with the DS operator, install the version 7.2 platform using the forgeops command. These examples use the small profile, appropriately use your custom profile.

Upgrade the UI:

$ ./bin/forgeops install ui --small --fqdn cdm.example.com

Upgrade AM:

$ ./bin/forgeops install am --small --fqdn cdm.example.com

Upgrade IDM:

$ ./bin/forgeops install idm --small --fqdn cdm.example.com

Start the AM and IDM admin UIs, and verify that AM and IDM now 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.2, 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