Migrate secrets from secret agent to Helm-based secrets

Use this procedure to migrate an existing ForgeOps deployment that uses Helm and secret agent for secrets management to Helm-based secrets.

In ForgeOps 2026.3.0, Helm-generated secrets were added to the Helm chart, the Secret Generator option was removed, and the forgeops migrate sa2hs command was added to migrate secrets from secret agent to Helm-generated secrets.

This procedure applies only to Helm deployments.
Do not use this procedure for Kustomize deployments.
Because ForgeOps deployments are highly customizable, validate this procedure in a test environment before using it in production.
Run the forgeops commands in the Python3 virtual environment that you created for deploying ForgeOps.
If you are testing in a minikube environment, ensure that minikube tunnel is running in a separate terminal window.

Before you begin

Make sure that:

Your deployment uses Helm.
Your deployment currently uses secret agent.
You have updated your ForgeOps artifacts to version 2026.3.0 or later.
You know the environment name, namespace, and location of your ForgeOps repository clone.
All pods in the deployment are healthy before you start.

This migration does not require Secret Generator prerequisites.

For newly created environments with ForgeOps 2026.3 or later, Helm-generated secrets are enabled by default. Existing environments are not changed automatically and must be migrated.

Back up your secrets

Before you start, back up the secrets used by your deployment.

At a minimum, back up the following secrets:

am-env-secrets, am-keystore, am-passwords, amster, amster-env-secrets
ds-env-secrets, ds-passwords

idm-env-secrets, idm

For example:

$ kubectl get secret am-env-secrets -n my-ns -o yaml > am-env-secrets.yaml
$ kubectl get secret ds-env-secrets -n my-ns -o yaml > ds-env-secrets.yaml
$ kubectl get secret ds-passwords -n my-ns -o yaml > ds-passwords.yaml

(Optional) You can also back up the DS key material that secret agent does not generate:

ds-master-keypair, ds-ssl-keypair

For example:

$ kubectl get secret ds-master-keypair -n my-ns -o yaml > ds-master-keypair.yaml
$ kubectl get secret ds-ssl-keypair -n my-ns -o yaml > ds-ssl-keypair.yaml

Secret agent can integrate with a cloud secret manager such as Google Cloud Secret Manager, AWS Secrets Manager, and Azure Key Vault. If your secret agent deployment uses a cloud secret manager, review that configuration before migrating to Helm-based secrets.

Confirm DS password-rotation support

For a no-downtime migration, use DS images that support multiple password values in DS. If your deployment does not have that capability, plan for downtime when passwords change during migration.

Verify the current state of the deployment

Verify that all pods are running:
```
$ kubectl get pods -n my-ns
```
Verify that the deployment is currently using secret agent. For example, check that the forgerock-sac resource exists:
```
$ kubectl get sac -n my-ns
```
Review the current Helm values file for the environment:
```
$ cat /path/to/forgeops/helm/my-env/values.yaml
```

Run the migration command

ForgeOps 2026.3.0 adds the forgeops migrate sa2hs command to migrate secrets from secret agent to Helm-generated secrets. To display the command help, run the [.command]forgeops migrate sa2hs --help# command.

To migrate a Helm deployment, run:
```
$ forgeops migrate sa2hs --env-name my-env -n my-ns
```
If you are testing with a local chart instead of the published chart, specify the chart location:
```
$ forgeops migrate sa2hs -o ./charts/identity-platform --env-name my-env -n my-ns
```
This command is for Helm deployments, so you need not specify a --helm option.

What the migration command does

The migration command pauses before each major change so that you can review what it is about to do in the running deployment.

For a Helm deployment, the command performs the migration in phases.

In phase 1

The command:

Runs pre-migration checks.
Upgrades the existing environment to keep the environment files consistent.
Switches the environment to Helm-based secrets by updating the environment with --helm-secrets.
Updates the environment values.yaml file for the first set of Helm-managed secrets.
Rotates ds-env-secrets so that AM can continue to communicate with DS during the transition.
Updates the forgerock-sac resource to remove the secrets being migrated away from secret agent.
Runs helm upgrade and forces the ds-set-passwords and amster jobs as needed.

In phase 2

The command:

Merges the remaining Helm-generated secret settings into values.yaml.
Rotates ds-passwords.
Deletes the forgerock-sac resource after the remaining secret agent-managed secrets have been migrated.
Runs helm upgrade again to apply the remaining secret changes.
Restarts DS so that the new password values are used consistently.
Deletes the temporary old-ds-env-secrets and old-ds-passwords secrets.
Runs Helm again to complete cleanup and force an Amster run.

Responses to prompts during migration

The script prompts before making changes. When prompted, review the action and continue. These prompts are expected because the migration changes a running deployment.

Validate the deployment after migration

After the migration completes:

Verify that all pods are healthy:
```
$ kubectl get pods --namespace my-ns
```
Verify that the deployment is now using Helm-based secrets.

Review the environment values.yaml file and confirm that Helm-generated secret settings are present.
Verify that the forgerock-sac resource has been removed:
```
$ kubectl get sac --namespace my-ns
```
Confirm that the application is reachable and that you can log in to the platform.
Verify that the completed jobs are present as expected for the migrated release, such as:
- amster-<revision>
- ds-set-passwords-<revision>
- keystore-create-<revision>
- ssh-keygen-<revision>

Troubleshooting

AM or IDM does not come up

If AM or IDM does not come up after the migration, restart the affected deployment:

$ kubectl rollout restart deployment am --namespace my-ns
$ kubectl rollout restart deployment idm --namespace my-ns

DS needs to pick up the new password values

If DS does not restart as needed during the migration, restart the DS stateful sets:

$ kubectl rollout restart sts ds-idrepo --namespace my-ns
$ kubectl rollout restart sts ds-cts --namespace my-ns

The admin UI shows a white screen after migration: Migration testing found that a missing Amster run can lead to a white screen after login.

If this happens:

Run Helm again and force an Amster run.

If needed, redeploy the platform and restart IDM. For example:

$ cd /path/to/forgeops

$ helm upgrade --install identity-platform  identity-platform \
--repo https://ForgeRock.github.io/forgeops/ \
--version 2026.3 --namespace my-ns \
--values /path/to/forgeops/helm/my-env/values.yaml

$ kubectl rollout restart deployment idm --namespace my-ns

Clear your browser data or use an incognito window, and then log in again.

Result

After the migration:

The deployment no longer depends on secret agent for Helm-managed secrets.
Helm functions generate the default secrets used by the deployment.
The chart uses lookup logic so that existing secret values can be preserved across upgrades.
SSH key material that Helm cannot generate directly continues to be handled by the ssh-keygen job.

Next steps

After you migrate the deployment:

Continue using Helm for future updates.
Use the Helm values file as the source of truth for the environment.
Review your team runbooks so they no longer reference secret agent for Helm deployments.
If you maintain documentation for fresh deployments, note that Helm-generated secrets are enabled by default for new environments.
After all your environments have migrated to use Helm-generated secrets, you can remove the secret agent from your deployment environment.