am Image

This documentation describes new, pre-release CDK features. If you want to work with a stable feature set, use the CDK as described in this section of the documentation.

The am Docker image contains the AM configuration.

Customization Overview

  • Customize AM’s configuration data by using the console and the REST APIs.

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

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

  • Build an updated am Docker image that contains your customizations, and configure the CDK installer to use the updated am image.

  • Redeploy AM.

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

Detailed Steps

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

  1. Verify that:

  2. 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.

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

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

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

  4. Export the changes you made to the AM configuration in the running ForgeRock Identity Platform to the staging area:

    $ cd /path/to/forgeops/bin
    $ ./config.sh export --component am
    Exporting AM configuration..
    
    AM configuration files have been exported to docker/7.0/am/config.
    Reading existing configuration from files in /am-config/config/services…​
    Modifying configuration based on rules in [/rules/placeholders.groovy]…​
    reading configuration from file-based config files
    SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
    SLF4J: Defaulting to no-operation (NOP) logger implementation
    SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
    Writing configuration to new location at /am-config/config/services…​
    Upgrade Completed, modified configuration saved to /am-config/config/services
  5. 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 am --profile my-profile
    diff  -u --recursive config/7.0/my-profile/am docker/7.0/am
    diff -u --recursive -x '.' -x Dockerfile -x '.sh' config/7.0/my-profile/am/config/services/realm/root/iplanetamplatformservice/1.0/globalconfig/default/com-sun-identity-servers/server-default.json docker/7.0/am/config/services/realm/root/iplanetamplatformservice/1.0/globalconfig/default/com-sun-identity-servers/server-default.json
    --- config/7.0/my-profile/am/config/services/realm/root/iplanetamplatformservice/1.0/globalconfig/default/com-sun-identity-servers/server-default.json	2021-04-23 16:38:05.000000000 -0700
    + docker/7.0/am/config/services/realm/root/iplanetamplatformservice/1.0/globalconfig/default/com-sun-identity-servers/server-default.json	2021-04-23 16:38:53.000000000 -0700
    @@ -140,7 +140,6 @@
           "org.forgerock.openam.radius.server.context.cache.size=5000",
           "com.iplanet.am.jssproxy.checkSubjectAltName=false",
           "org.forgerock.services.cts.reaper.cache.size=5000000",
    -      "com.iplanet.services.debug.level=error",
           "org.forgerock.services.cts.store.location=external",
           "com.sun.identity.crl.cache.directory.searchattr=",
           "com.sun.am.event.notification.expire.time=5",
    @@ -229,6 +228,7 @@
           "com.sun.identity.saml.xmlsig.keypass=%BASE_DIR%/security/secrets/default/.keypass",
           "com.sun.identity.crl.cache.directory.user=",
           "openam.cdm.default.charset=UTF-8",
    +      "com.iplanet.services.debug.level=warning",
           "com.sun.identity.saml.xmlsig.storepass=%BASE_DIR%/security/secrets/default/.storepass",
           "com.sun.identity.session.repository.enableEncryption=false",
           "org.forgerock.services.default.store.min.connections=",
  6. Save the AM configuration to your configuration profile:

    $ ./config.sh save --component am --profile my-profile
    Saving AM configuration.
  7. 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.

  8. Build a new am image that includes your changes to the AM configuration, and configure the CDK installer to use the new am image:

    $ ./cdk build am
    Generating tags…​
     - am → am:32005dccf
    Checking cache…​
     - am: Not found. Building
    Starting build…​
    Found [minikube] context, using local docker daemon.
    Building [am]…​
    Sending build context to Docker daemon  1.989MB
    Step 1/15 : FROM gcr.io/forgerock-io/am-base:7.1.0
     --→ 4e0b979daa5c
    . . .
    Step 15/15 : ENTRYPOINT ["/home/forgerock/custom-entrypoint.sh"]
     --→ Running in 5f85c3a0f12a
     --→ 16e5e404830e
    Successfully built 16e5e404830e
    Successfully tagged am:32005dccf
    
    Updated the image_defaulter with your new image for am: "am:16e5e4048…​"
  9. Redeploy AM:

    1. Remove AM from your CDK installation:

      $ ./cdk delete am
      Uninstalling component(s): ['am']
      OK to delete these components? [Y/N] Y
      service "am" deleted
      deployment.apps "am" deleted
    2. Redeploy AM:

      $ ./cdk install am
      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): ['am']
      
      service/am created
      deployment.apps/am created
      
      Enjoy your deployment!
    3. Run the kubectl get pods command to monitor the status of the AM pod. Wait until the pod is ready before proceeding to the next step.

  10. To validate that AM has the expected configuration:

    • Describe the AM pod. Locate the tag of the Docker image that Kubernetes loaded, and verify that it’s your new custom Docker image’s tag.

    • Start the AM console and verify that your configuration changes are present.

Next Step