--- title: Migrate secrets from secret agent to Helm-based secrets description: Migrate a ForgeOps Helm deployment from secret agent to Helm-based secrets. component: forgeops version: 2026.3 page_id: forgeops:prepare:security/migrate-helmsec canonical_url: https://docs.pingidentity.com/forgeops/2026.3/prepare/security/migrate-helmsec.html llms_txt: https://docs.pingidentity.com/forgeops/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md section_ids: before_you_begin: Before you begin back_up_your_secrets: Back up your secrets confirm_ds_password_rotation_support: Confirm DS password-rotation support verify_the_current_state_of_the_deployment: Verify the current state of the deployment run_the_migration_command: Run the migration command what_the_migration_command_does: What the migration command does responses_to_prompts_during_migration: Responses to prompts during migration validate_the_deployment_after_migration: Validate the deployment after migration troubleshooting: Troubleshooting result: Result next_steps: Next steps --- # 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. 1. 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 ``` 2. (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 1. Verify that all pods are running: ``` $ kubectl get pods -n my-ns ``` 2. Verify that the deployment is currently using secret agent. For example, check that the `forgerock-sac` resource exists: ``` $ kubectl get sac -n my-ns ``` 3. 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. 1. 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: 1. Runs pre-migration checks. 2. Upgrades the existing environment to keep the environment files consistent. 3. Switches the environment to Helm-based secrets by updating the environment with `--helm-secrets`. 4. Updates the environment `values.yaml` file for the first set of Helm-managed secrets. 5. Rotates `ds-env-secrets` so that AM can continue to communicate with DS during the transition. 6. Updates the `forgerock-sac` resource to remove the secrets being migrated away from secret agent. 7. Runs `helm upgrade` and forces the `ds-set-passwords` and `amster` jobs as needed. * In phase 2 The command: 1. Merges the remaining Helm-generated secret settings into `values.yaml`. 2. Rotates `ds-passwords`. 3. Deletes the `forgerock-sac` resource after the remaining secret agent-managed secrets have been migrated. 4. Runs `helm upgrade` again to apply the remaining secret changes. 5. Restarts DS so that the new password values are used consistently. 6. Deletes the temporary `old-ds-env-secrets` and `old-ds-passwords` secrets. 7. 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: 1. Verify that all pods are healthy: ``` $ kubectl get pods --namespace my-ns ``` 2. 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. 3. Verify that the `forgerock-sac` resource has been removed: ``` $ kubectl get sac --namespace my-ns ``` 4. Confirm that the application is reachable and that you can log in to the platform. 5. Verify that the completed jobs are present as expected for the migrated release, such as: * `amster-` * `ds-set-passwords-` * `keystore-create-` * `ssh-keygen-` ### 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: 1. Run Helm again and force an Amster run. 2. 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 ``` 3. 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.