amster Image

This page uses the terms initial dynamic configuration and sample dynamic configuration to distinguish how and when dynamic configuration is loaded into the CDK.

  • Initial dynamic configuration refers to AM dynamic configuration that’s loaded when the CDK and the CDM start up. The amster Docker image contains initial dynamic configuration.

  • Sample dynamic configuration refers to dynamic configuration that’s not loaded when the CDK and the CDM start up. Sample dynamic configuration might include IDM dynamic configuration, sample identities, or AM dynamic configuration that is not in the amster Docker image.

See Dynamic Configuration for more information.

Customization Overview

  • Customize initial dynamic configuration by using the console and the REST APIs. Initial dynamic configuration 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

  • Back up sample dynamic configuration if needed.

  • Remove AM sample dynamic configuration from the CDK, so that it’s not inadvertently included in the amster Docker image.

  • Capture changes to initial dynamic configuration by exporting the changes from the AM service running on Kubernetes to the staging area.

  • Save the modified initial dynamic configuration to a configuration profile in your forgeops repository clone.

  • Build an updated amster Docker image that contains your customized initial dynamic configuration.

  • Redeploy the CDK.

  • Restore sample dynamic configuration.

  • Verify that changes you’ve made to the initial dynamic configuration are in the new Docker image.

Detailed Steps

  1. If this is your first time building a custom Docker image, verify that you performed these setup activities, which are required for developers:

  2. Verify that:

    • The CDK is deployed.

    • The namespace in which the CDK is deployed is set in your Kubernetes context.

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

    1. Run the git status command.

    2. Review the state of the config directory.

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

  4. Use the AM console or REST APIs to modify initial dynamic configuration, including:

    • 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

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

  5. (Optional) Back up and remove sample dynamic configuration if needed:

    1. If you’ve added sample dynamic configuration to the CDK, back it up, so that you can restore it after you restart the CDK.

    2. If you have any AM sample dynamic configuration, remove it from AM. If you do not remove the sample dynamic configuration from AM, it will be included in the amster Docker image.

  6. Export the changes you made to initial dynamic configuration in the running ForgeRock Identity Platform to the staging area:

    $ cd /path/to/forgeops/bin
    $ ./config.sh export --component amster
    /Users/forgeops/Repositories/forgeops/bin/amster export docker/7.0/amster/config
    Cleaning up any previous amster jobs…​
    starting the amster job
    kustomize build /Users/forgeops/Repositories/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-dbh6v
    kubectl  wait --for=condition=ready pod amster-dbh6v --timeout=90s
    kubectl  cp -c pause amster-dbh6v:/var/tmp/amster/realms docker/7.0/amster/config/realms
    tar: Removing leading `/' from member names
    kubectl  delete job amster
    job.batch "amster" deleted

    The config.sh export --component amster command copies initial dynamic configuration from the running CDK instance to the staging area.

    Exporting the configuration from the CDK to the staging area.
  7. Review the differences between the files you exported to the staging area and files that you previously saved to your configuration profile.

    Use the config.sh diff command to review the changes. For example:

    $ ./config.sh diff --component amster --profile my-profile
    Only in docker/7.0/amster: amster-scripts
    Only in docker/7.0/amster/config: realms
    Only in docker/7.0/amster/config/root: Applications
    diff -u --recursive -x '.' -x Dockerfile -x '.sh' config/7.0/my-profile/amster/config/root/IdentityGatewayAgents/ig-agent.json docker/7.0/amster/config/root/IdentityGatewayAgents/ig-agent.json
    --- config/7.0/my-profile/amster/config/root/IdentityGatewayAgents/ig-agent.json	2021-04-27 11:20:28.000000000 -0700
    + docker/7.0/amster/config/root/IdentityGatewayAgents/ig-agent.json	2021-04-27 14:12:11.000000000 -0700
    @@ -1,7 +1,7 @@
     {
       "metadata" : {
         "realm" : "/",
    -    "amsterVersion" : "&{version}",
    +    "amsterVersion" : "7.1.0",
    . . .

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

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

  8. Save the exported data to your configuration profile:

    $ ./config.sh save --component amster --profile my-profile
    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 save --component amster command copies the initial dynamic configuration from the staging area to your configuration profile.

    Saving the configuration to your configuration profile.
  9. Perform version control activities on your forgeops repository clone:

    1. Run the git status command.

    2. Review the state of the config directory.

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

  10. Build a new amster image that includes your updated initial dynamic configuration:

    $ ./cdk build amster

    The cdk build command calls Skaffold to build a new amster Docker image and push the image to your Docker registry. It also updates the image defaulter file so that the next time you install Amster, the cdk install command loads initial dynamic configuration from your new custom Docker image.

    Building the new custom Docker image.
  11. Redeploy the CDK:

    1. Remove AM, IDM, DS, and Amster from your namespace:

      $ ./cdk delete am idm ds amster
      Uninstalling component(s): ['am', 'idm', 'ds', 'amster']
      OK to delete these components? [Y/N] y
      service "am" deleted
      deployment.apps "am" deleted
      configmap "idm" deleted
      configmap "idm-logging-properties" deleted
      service "idm" deleted
      deployment.apps "idm" deleted
      job.batch "amster" deleted
    2. Delete PVCs that contain AM run-time data:

      $ kubectl delete pvc -l app.kubernetes.io/name=ds
      persistentvolumeclaim "data-ds-idrepo-0" deleted
    3. Redeploy AM, IDM, DS, and Amster:

      $ ./cdk install ds am idm amster 
      Checking secret-agent operator and related CRDs: secret-agent CRD found in cluster.
      Checking ds-operator and related CRDs: ds-operator CRD found in cluster.
      
      Installing component(s): ['ds', 'am', 'idm', 'amster']
      
      directoryservice.directory.forgerock.io/ds-idrepo created
      service/am created
      deployment.apps/am created
      configmap/idm created
      configmap/idm-logging-properties created
      service/idm created
      deployment.apps/idm created
      job.batch/amster created
      
      Enjoy your deployment!
    4. Run the kubectl get pods command to monitor the status of the CDK pods. Wait until the pods are ready before proceeding to the next step.

  12. (Optional) Restore sample dynamic configuration if needed:

    • To restore sample identities and sample IDM dynamic configuration, use the DS restore utility that corresponds with your backup. For example, if you backed up your sample data with the export-ldif utility, restore it with the import-ldif utility.

    • To restore sample AM dynamic configuration, use the amster import command. For example:

      $ cd /path/to/forgeops/bin
      $ ./amster import /path/to/am-sample-dynamic-configuration
      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/am-sample-dynamic-configuration is a directory that contains JSON files with AM dynamic configuration. JSON files in all of this path’s subdirectories are imported into AM.

  13. To validate that AM has the expected dynamic configuration, start the AM console and verify that the changes you made are present.

Next Step