amster 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 amster Docker image contains AM run-time data.

Customization Overview

  • Customize AM run-time data by using the console and the REST APIs. 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

  • Capture changes to AM run-time data by exporting the changes from the AM service running on Kubernetes back to the staging area.

  • Save the modified AM run-time data to a configuration profile in your forgeops repository clone.

  • Build an updated amster Docker image that contains your customized run-time data, and configure the CDK installer to use the updated amster image.

  • Redeploy the CDK.

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

Detailed Steps

  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 AM run-time data using the AM console or the REST APIs. 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

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

  4. Export the changes you made to AM run-time data 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
  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 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, in containerized deployments.

  6. Save the AM run-time 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.
  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. (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 custom amster image.

  9. Build a new amster image that includes your changes to the AM run-time data, and configure the CDK installer to use the new amster image:

    $ ./cdk build amster
  10. Redeploy the CDK:

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

      $ ./cdk delete am idm ds amster
      Uninstalling component(s): ['ds', 'am', 'idm', 'amster']
      OK to delete these components? [Y/N] Y
      directoryservice.directory.forgerock.io "ds-idrepo" deleted
      service "am" deleted
      deployment.apps "am" deleted
      configmap "idm" deleted
      configmap "idm-logging-properties" deleted
      service "idm" deleted
      deployment.apps "idm" 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.

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

  12. (Optional) If you have sample AM run-time data that you want to use for testing, but which you don’t want to include in the amster Docker image, you can import it to your running CDK deployment. Copy the run-time data, in JSON format, into the staging area—the docker/7.0/amster directory. Then, run the config.sh import command:

    $ cd /path/to/forgeops/bin
    $ ./config.sh import
  13. To validate that AM has the expected run-time data, start the AM console and verify that the changes you made are present.

Next Step