Upgrade PingAM, PingIDM, or PingDS image to a newer patch release

Patched images are released for each platform product separately. So you may need to update each of PingAM, PingIDM, or PingDS images to a newer image patch release separately.

Because the Ping Identity Platform is highly customizable, testing all possible upgrade scenarios is challenging. 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 PingAM, PingIDM, or PingDS image to a newer patch release, you’ll need:

A local clone of the ForgeOps repository.
A running ForgeOps deployment deployed using ForgeOps 2025.1.0 or later.
A configured ForgeOps deployment environment in your forgeops repository clone using the forgeops env command.

Example commands in this section assume that your ForgeOps deployment:

Is using the default configuration.
Doesn’t include PingGateway.

Back up critical Directory data

If upgrading DS, back up all the directory data stored in the ds-idrepo and ds-cts backends. After you’ve started to upgrade, you can’t roll back directory data changes easily because the data is upgraded in place. To roll back directory data, you must redeploy DS and restore directory data. Consider backing up directory data on volume snapshots for a simpler restore scenario.

For upgrading a dev environment, ensure that you have exported your AM or IDM configuration changes to your custom configuration profile.

Get ready for upgrade

Set your Kubernetes context so that you can access the cluster which contains your ForgeOps deployment.
Check the current supported product versions available if required:
```
$ cd /path/to/forgeops
$ ./bin/forgeops info --list-releases
```

Upgrade a product to a newer patch release

This section covers the steps to upgrade AM, Amster, IDM, or DS to a new patch release.

Amster and AM need to be on the same version. So if you’re upgrading AM, carry out the same steps to upgrade Amster.

Create a new release in your ForgeOps repository clone that includes your customized configuration of the product to be updated, using one of the following options:
1. To update to a new patch release use the forgeops image command and specify:
  - The new patch version in the --release flag.
  - Your current release in the --release-name flag.
    
    For example, to upgrade your AM image to 7.5.2 release:
    
    $ cd /path/to/forgeops $ ./bin/forgeops image --release 7.5.2 --release-name my-custom-release am
2. To update to the latest secure image in your current release, use the forgeops image command and specify:
  - The product version you have deployed in the --release flag.
  - Specify your current release in the --release-name flag.
    
    When you specify the current release in the forgeops image command, it selects the latest available secure image automatically.
    
    For example, to upgrade your AM image to the latest secure image of 7.5.1 release:
    
    $ cd /path/to/forgeops $ ./bin/forgeops image --release 7.5.1 --release-name my-custom-release am
If you’re upgrading AM, upgrade your custom AM configuration profile to the new version.

The --release-name option is required to ensure you use the version of the am-config-upgrader that matches your target AM version.
```
$ cd /path/to/forgeops
$ ./bin/forgeops upgrade-am-config --release-name my-custom-release \
 --config-profile docker/am/config-profiles/my-custom-release
```

Build your new custom image for the product you are upgrading.

The --config-profile option isn’t required to build DS image.

$ cd /path/to/forgeops
$ ./bin/forgeops build AM --env-name my-custom-env \
 --release-name my-custom-release --config-profile \
 docker/am/config-profiles/my-config-profile

Deploy your updated version.

In a Helm environment

$ cd /path/to/forgeops
$ helm upgrade --install identity-platform \
oci://us-docker.pkg.dev/forgeops-public/charts/identity-platform \
--version deployed version --namespace my-namespace \
--values helm/my-custom-env/values.yaml

In a Kustomize environment

$ cd /path/to/forgeops
$ ./bin/forgeops apply --env-name my-custom-env product

In the forgeops apply command, specify the product, such as am, idm, or ds for product.

Upgrade the platform UIs to a newer patch version

Use the steps in this section to upgrade platform UIs in a ForgeOps deployment. Usually the new platform UI patch versions are available together, so the steps upgrade all the platform UIs together. You don’t need to build new Docker images when you upgrade Platform UIs.

Upgrade your deployment environment to the new patch version.
1. To upgrade to the new patch release of platform UIs, specify the new patch number in the --release flag of the forgeops image command. For example, to upgrade to the 7.5.2 version UIs:
  $ cd /path/to/forgeops $ ./bin/forgeops image --release 7.5.2 ui --env-name my-custom-env
2. To update to the latest platform UI secure image for the currently deployed release, specify the current platform UI version in the --release flag:
  $ cd /path/to/forgeops $ ./bin/forgeops image --release 7.5.1 ui --env-name my-custom-env

Deploy your updated patch image:

In a Helm environment

$ cd /path/to/forgeops
$ helm upgrade --install identity-platform \
oci://us-docker.pkg.dev/forgeops-public/charts/identity-platform \
--version deployed version --namespace my-namespace \
--values helm/my-custom-env/values.yaml

In a Kustomize environment

$ cd /path/to/forgeops
$ ./bin/forgeops apply --env-name [.var}#my-custom-env# ui