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.