ForgeOps

AM and IDM Images

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

AM Images

AM uses two Docker images, am and amster:

  • The am image contains your custom AM configuration.

  • The amster image contains your custom AM run-time data.

With AM up and running, you can iteratively update the am Docker image:

  • Customize AM’s configuration and run-time data using the console and the REST APIs.

  • Capture changes to the AM configuration by synchronizing them from the AM service running on Kubernetes back to the staging area and the master directory for configuration profiles in your forgeops repository clone.

  • Run Skaffold to detect the changes, rebuild the am Docker image, and restart AM. You can then test changes you’ve made to the AM configuration based on the updated Docker image.

You can also iteratively update the amster image:

  • Capture changes to AM run-time data by synchronizing the changes from the AM service running on Kubernetes back to the staging area and the master directory for configuration profiles in your forgeops repository clone.

    AM run-time data includes:

    • OAuth 2.0 clients

    • OpenID Connect 1.0 clients

    • IG, Web, Java, and SOAP STS agents

    • Policies

    • SAML v2.0 circles of trust and entities

  • Run Skaffold to detect the changes and rebuild the amster Docker image.

am Image

The am Docker image contains the AM configuration.

Perform the following steps iteratively when developing a customized am Docker image:

  1. Perform version control activities on your forgeops repository clone:

    1. Run the git status command.

    2. Review the state of the working directory and staging area.

    3. (Optional) Run the git commit command to commit changes to files that have been modified.

  2. Make sure that context is set to your namespace:

    $ kubens my-namespace

  3. Modify the AM configuration using the AM console or the REST APIs.

    For information about how to access the AM Admin UI or REST APIs, see AM Services.

    See Property Value Substitution for important information about configuring values that vary at run-time, such as passwords and host names.

  4. Export the changes you made to the AM configuration to your forgeops repository clone:

    $ cd /path/to/forgeops/bin
$ ./config.sh export --component am
Exporting AM configuration..
. . .

    The config.sh export command exports the modified parts of the AM configuration from the running ForgeRock Identity Platform to the docker/7.0/am/config directory.

  5. List the changed files using the config.sh diff -c am command:

    $ ./config.sh diff --component am
diff  -u --recursive config/7.0/cdk/am docker/7.0/am
Only in docker/7.0/am/config/services/realm/root/authenticationtreesservice/1.0/organizationconfig/default: my-test-tree.json
Only in docker/7.0/am: logback.xml
. . .

  6. Save the exported configuration to your profile:

    $ ./config.sh save --component am --profile my-profile 
Saving AM configuration..

    For more information about the management of ForgeRock Identity Platform configurations in the forgeops repository, see Configuration Profiles.

  7. Perform version control activities on your forgeops repository clone:

    1. Run the git status command.

    2. Review the state of the working directory and staging area.

    3. (Optional) Run the git commit command to commit changes to files that have been modified.

  8. Delete the existing deployment:

    $ cd /path/to/forgeops/
$ skaffold delete
Cleaning up…​
 - configmap "idm" deleted
 - configmap "idm-logging-properties" deleted
 - configmap "platform-config" deleted
. . .

  9. Redeploy with changes using the skaffold run command:

    $ skaffold run

    Skaffold builds a new am Docker image and redeploys AM.

  10. To validate that AM has the expected configuration, obtain the new password for amadmin user, start the console, and verify that your configuration changes are present.

amster Image

The amster Docker image contains AM run-time data.

Perform the following steps iteratively when developing a customized amster Docker image:

  1. Perform version control activities on your forgeops repository clone:

    1. Run the git status command.

    2. Review the state of the working directory and staging area.

    3. (Optional) Run the git commit command to commit changes to files that have been modified.

  2. Modify AM run-time data using the AM console or the REST APIs.

    For information about how to access the AM console or REST APIs, see AM Services.

    AM run-time data includes:

    • OAuth 2.0 clients

    • OpenID Connect 1.0 clients

    • IG, Web, Java, and SOAP STS agents

    • Policies

    • SAML v2.0 circles of trust and entities

  3. Make sure that context is set to your namespace:

    $ kubens my-namespace

  4. Synchronize the changes you made to the AM configuration to your configuration profile in your forgeops repository clone:

    $ cd /path/to/forgeops/bin
$ ./config.sh sync --profile my-profile --component amster
/Users/. . ./forgeops/bin/amster export docker/7.0/amster/config
Cleaning up any previous amster jobs…​
starting the amster job
kustomize build /Users/. . ./forgeops/bin/../kustomize/base/amster-export | kubectl  apply -f -
job.batch/amster created
kubectl  get pod -l app=amster --output=jsonpath={.items[0].metadata.name}
Waiting for pod amster-95v45
kubectl  wait --for=condition=ready pod amster-95v45 --timeout=90s
kubectl  cp -c pause amster-95v45:/var/tmp/amster/realms docker/7.0/amster/config/realms
tar: Removing leading `/' from member names
kubectl  delete job amster
job.batch "amster" deleted

Saving Amster configuration

* APPLYING FIXES *
Adding back amsterVersion placeholder …​
Adding back FQDN placeholder …​
Removing 'userpassword-encrypted' fields …​

Adding back password placeholder with defaults in these files:

idm-provisioning.json
idm-resource-server.json
resource-server.json
oauth2.json
ig-agent.json

The above fixes have been made to the Amster files.
If you have exported new files that should contain commons
placeholders or passwords, please update the rules in this script.

    The config.sh sync command exports the modified AM configuration profile from the running ForgeRock Identity Platform to the staging area. Then, it saves the configuration profile as my-profile in the master directory for configuration profiles:

    This diagram shows how the config.sh command synchronizes a configuration profile.

    For more information about the management of ForgeRock Identity Platform configuration profiles in the forgeops repository, see Configuration Profiles.

  5. Examine each JSON file that was written to your configuration profile.

    If any of the files contain hard-coded host names or passwords, replace them with configuration expressions. AM resolves configuration expressions when it starts up.

    See Property Value Substitution for important information about configuring values that vary at run-time, such as passwords and host names.

  6. Perform version control activities on your forgeops repository clone:

    1. Run the git status command.

    2. Review the state of the working directory and staging area.

    3. (Optional) Run the git commit command to commit changes to files that have been modified.

  7. Make sure that context is set to your namespace:

    $ kubens my-namespace

  8. Reinitialize the staging area with your configuration profile:

    $ cd /path/to/forgeops/bin
$ ./config.sh init --profile my-profile
Removing docker/7.0/am/config/
Removing docker/7.0/amster/config/
Removing docker/7.0/idm/conf/
Removing docker/7.0/idm/ui/
Removing docker/7.0/ig/config/
Copying /path/to/forgeops/config/7.0/my-profile/idm.
Copying /path/to/forgeops/config/7.0/my-profile/am.
Copying /path/to/forgeops/config/7.0/my-profile/ig.
Copying /path/to/forgeops/config/7.0/my-profile/amster.
Completed

  9. (Optional) If you have customized DS data in the idrepo directory, take a backup of those changes, so you can restore your DS data after redeploying your customized amster image.

  10. Shut down your ForgeRock Identity Platform deployment, and remove the PVCs. See CDK Shutdown and Removal for details.

  11. Redeploy the ForgeRock Identity Platform:

    $ cd /path/to/forgeops
$ skaffold run

  12. (Optional) If needed, restore any user identity data that you have customized in your environment.

  13. (Optional) Suppose you have sample AM run-time data that you want to use for testing, but you don’t want to include the sample data in the amster Docker image.

  14. Make sure that context is set to your namespace:

    $ kubens my-namespace

    • You can import the sample data to your running CDK deployment:

      $ cd /path/to/forgeops/bin
$ ./amster import /path/to/run-time-data
Cleaning up amster components
job.batch "amster" deleted
Packing and uploading configs
configmap/amster-import created
Deploying amster
job.batch/amster created

Waiting for amster job to complete. This can take several minutes.
. . .
Amster output ***
java.util.prefs.FileSystemPreferences$1 run
INFO: Created user preferences directory.
am> :load amster-scripts/import.amster
Importing directory /opt/amster/config
Imported /opt/amster/config/realms/root/OAuth2Clients/MyClient.json
Import completed successfully
import done
Cleaning up amster components
job.batch "amster" deleted
configmap "amster-import" deleted

      In this example, /path/to/run-time-data is a directory that contains JSON files with run-time AM data. JSON files in all of this path’s subdirectories are imported into AM.

    • Be sure to delete the sample AM data before you export the Amster component. If you do not delete the sample data, it will be incorporated into the amster Docker image the next time you build the image.

  15. To validate that AM has the expected changes to run-time data, start the console and verify that your changes are present.

IDM Image

With IDM up and running, you can iteratively:

  • Customize IDM’s configuration using the Admin UI and the REST APIs.

  • Capture your configuration changes by synchronizing them from the IDM service running on Kubernetes back to the staging area and the master directory for configuration profiles in your forgeops repository clone.

  • Run Skaffold to detect the changes, rebuild the idm Docker image, and restart IDM. You can then test changes you’ve made to the IDM configuration based on the updated Docker image.

idm Image

The idm Docker image contains the IDM configuration.

Perform the following steps iteratively when developing a customized idm Docker image:

  1. Perform version control activities on your forgeops repository clone:

    1. Run the git status command.

    2. Review the state of the working directory and staging area.

    3. (Optional) Run the git commit command to commit changes to files that have been modified.

  2. Modify the IDM configuration using the IDM Admin UI or the REST APIs.

    For information about how to access the IDM Admin UI or REST APIs, see IDM Services.

    See Property Value Substitution for important information about configuring values that vary at run-time, such as passwords and host names.

  3. Make sure that context is set to your namespace:

    $ kubens my-namespace

  4. Synchronize the changes you made to the IDM configuration to your forgeops repository clone:

    $ cd /path/to/forgeops/bin
$ ./config.sh sync --profile my-profile --component idm
tar: Removing leading '/' from member names

    The config.sh sync command exports the modified IDM configuration from the running ForgeRock Identity Platform to the staging area. Then, it saves the configuration profile as my-profile in the master directory for configuration profiles:

    This diagram shows how the config.sh command synchronizes a configuration profile.

    For more information about the management of ForgeRock Identity Platform configurations in the forgeops repository, see Configuration Profiles.

  5. Execute the skaffold run command:

    $ cd /path/to/forgeops
$ skaffold run

    Skaffold builds a new idm Docker image and redeploys IDM.

  6. Perform version control activities on your forgeops repository clone:

    1. Run the git status command.

    2. Review the state of the working directory and staging area.

    3. (Optional) Run the git commit command to commit changes to files that have been modified.

  7. To validate that IDM has the expected configuration, start the Admin UI, and verify that your configuration changes are present.

Copyright © 2010-2024 ForgeRock, all rights reserved.