ForgeOps

Upgrade the DS from version 7.1 to 7.4

If you’ve already installed ForgeRock Identity Platform version 7.1 using Skaffold, follow the steps provided on this page to upgrade to version 7.4. Using this procedure, you don’t have to upgrade DS in multiple steps through 7.2, 7.3 and 7.4 versions.

This procedure is for upgrading DS only. For upgrading the other components, such as AM or IDM, follow the steps similar to those mentioned in the 7.3 to 7.4 upgrade guide.

The DS upgrade requires downtime while the stateful set is redeployed.

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 DS from version 7.1 to 7.4, 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.4 artifacts

Ensure that your Kustomize overlay for version 7.4 matches the one for 7.1. For example, a small-size deployment in 7.1 has two ds-idrepo pods, but the default small-sized deployment in 7.4 has three ds-idrepo pods.

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.

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.

Upgrade steps

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

  2. Check out the branch of your forgeops repository clone that contains the version 7.4 artifacts.

  3. Upgrade the Secret Agent operator to the latest version:

    $ kubectl apply -f https://github.com/ForgeRock/secret-agent/releases/latest/download/secret-agent.yaml
  4. Migrate the secrets to the new format:

    $ cd /path/to/forgeops/upgrade/71to74/ds
    $ ./migrate.sh secrets
  5. Patch the update strategy for the DS stateful sets:

    $ cd /path/to/forgeops/upgrade/71to74/ds
    $ ./migrate.sh strategy idrepo
    $ ./migrate.sh strategy cts
  6. Prime the persistent volumes. DS version7.4 uses the ds-new Docker image which requires some directory configuration to be moved to the persistent disk:

    $ cd /path/to/forgeops/upgrade/71to74/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
  7. Update the DS stateful sets to version 7.4:

    $ ./migrate.sh patch idrepo
    $ ./migrate.sh patch cts
  8. 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
    2. Verify that the deleted ds-idrepo-1, ds-cts-1, and ds-cts-2 pods have resumed running.

  9. Delete the primary DS pods:

    $ kubectl delete pod ds-idrepo-0
    $ kubectl delete pod ds-cts-0
  10. Delete the stateful sets using the forgeops command. Do not delete the PVCs and volume snapshots:

    1. Delete ds-idrepo:

      $ cd /path/to/forgeops
      $ ./bin/forgeops delete ds-idrepo
      
      Ensure you follow the prompts below exactly:
      OK to delete components? [Y/N] y
      OK to delete PVCs? [Y/N] n
      OK to delete volume snapshots? [Y/N] n
      ...
    2. Delete ds-cts:

      $ ./bin/forgeops delete ds-cts
      
      Ensure you follow the prompts below exactly:
      OK to delete components? [Y/N] y
      OK to delete PVCs? [Y/N] n
      OK to delete volume snapshots? [Y/N] n
      ...
  11. Reinstall the stateful sets using the forgeops command:

    $ ./bin/forgeops install ds-idrepo --small
    $ ./bin/forgeops install ds-cts --small
  12. Delete unsupported rcs-agent:

    $ kubectl delete deployment rcs-agent
    $ kubectl delete configmap rcs-agent-config-properties
    $ kubectl delete configmap rcs-agent-logging-properties