ForgeOps

idm image

The idm Docker image contains the IDM configuration.

Customization overview

  • Customize IDM’s configuration data by using the IDM admin UI and REST APIs.

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

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

  • Build an updated idm Docker image that contains your customizations.

  • Redeploy IDM.

  • Verify that changes you’ve made to the IDM 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 docker/idm/config-profiles/my-profile directory.

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

  3. 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, refer to IDM Services.

    Refer to About 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 IDM configuration in the running ForgeRock Identity Platform to a configuration profile:

    $ cd /path/to/forgeops/bin
    $ ./config export idm my-profile --sort
    [.cyan][INFO] Running export for idm in idm-6b9db8cd7c-s7d46
    [INFO] Updating existing profile: /path/to/forgeops/docker/idm/config-profiles/my-profile/conf
    [INFO] Creating a new profile: /path/to/forgeops/docker/idm/config-profiles/my-profile/ui/admin/default/config#
    tar: Removing leading `/' from member names
    [INFO] Completed export
    [INFO] Sorting configuration.
    [INFO] Sorting completed.

    If the configuration profile does not exist yet, the config export command creates it.

    The config export idm my-profile command copies IDM static configuration from the running CDK instance to the configuration profile:

    Exporting the configuration from the CDK to a configuration profile.
  5. Perform version control activities on your forgeops repository clone:

    1. Review the differences in the files you exported to the configuration profile. For example:

      $ git diff
      diff --git a/docker/idm/config-profiles/my-profile/conf/audit.json b/docker/idm/config-profiles/my-profile/conf/audit.json
      index 0b3dbeed6..1e5419eeb 100644
      --- a/docker/idm/config-profiles/my-profile/conf/audit.json
      + b/docker/idm/config-profiles/my-profile/conf/audit.json
      @@ -135,7 +135,9 @@
         },
         "exceptionFormatter": {
           "file": "bin/defaults/script/audit/stacktraceFormatter.js",
      -    "globals": {},
      +    "globals": {
      +      "Test": "Test value"
      +    },
           "type": "text/javascript"
         }
       }

      Note that if this is the first time that you have exported IDM configuration changes to this configuration profile, the git diff command will not show any changes.

    2. Run the git status command.

    3. If you have new untracked files in your clone, run the git add command.

    4. Review the state of the docker/idm/config-profiles/my-profile directory.

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

  6. Identify the repository to which you’ll push the Docker image. You’ll use this location to specify the --push-to argument value in the build idm image step.

  7. Decide on the image tag name so you can tag each build of the image. You’ll use this tag name to specify the --tag argument value in the build idm image step.

  8. Build a new idm image that includes your changes to IDM static configuration:

    $ ./forgeops build idm --config-profile my-profile --push-to my-repo --tag my-idm-tag
    
    Flag --short has been deprecated, and will be removed in the future.
    
    [+] Building 3.3s (12/12) FINISHED                             docker:default
     ⇒ [internal] load build definition from Dockerfile
     ⇒ ⇒ transferring dockerfile: 1.09kB
    ...
     ⇒ [internal] load metadata for gcr.io/forgerock-io/idm-cdk:7.4.0                                                    2.0s
     ⇒ [internal] load build context                                                                                     0.1s
     ⇒ ⇒ transferring context: 563.76kB                                                                                 0.0s
     ⇒ [1/7] FROM gcr.io/forgerock-io/idm-cdk:7.4.0@sha256:...
     ⇒ ⇒ resolve gcr.io/forgerock-io/idm-cdk:7.4.0@sha256:...
     ...
     ⇒ [7/7] COPY --chown=forgerock:root  /opt/openidm
     ⇒ exporting to image
     ⇒ ⇒ exporting layers
     ⇒ ⇒ writing image
     ⇒ ⇒ naming to docker.io/library/idm
    
    What’s Next?
      View a summary of image vulnerabilities and recommendations → docker scout quickview
    Updated the image_defaulter with your new image for idm: "idm".
  9. Redeploy IDM using your new IDM image:

Redeploy IDM: forgeops command installations

The forgeops build command calls Docker to build a new idm Docker image and to push the image to your Docker repository. The new image includes your configuration profile. It also updates the image defaulter file so that the next time you install IDM, the forgeops install command gets IDM static configuration from your new custom Docker image.

Building the new custom Docker image.
  1. Perform version control activities on your forgeops repository clone:

    1. Run the git status command.

    2. Review the state of the kustomize/deploy/image-defaulter/kustomization.yaml file.

    3. (Optional) Run the git commit command to commit changes to the image defaulter file.

  2. Remove IDM from your CDK installation:

    $ ./forgeops delete idm
    "cdk" platform detected in namespace: "my-namespace".
    Uninstalling component(s): ['idm'] from namespace: "my-namespace".
    OK to delete components? [Y/N] Y
    service "idm" deleted
    deployment.apps "idm" deleted
  3. Redeploy IDM:

    $ ./forgeops install idm --cdk
    Checking cert-manager and related CRDs: cert-manager CRD found in cluster.
    Checking secret-agent operator and related CRDs: secret-agent CRD found in cluster
    
    Installing component(s): ['idm'] platform: "cdk" in namespace: "my-namespace" from deployment manifests in …​
    
    configmap/idm created
    configmap/idm-logging-properties created
    service/idm created
    deployment.apps/idm created
    
    Enjoy your deployment!
  4. Validate that IDM has the expected configuration:

    • Run the kubectl get pods command to monitor the status of the IDM pod. Wait until the pod is ready before proceeding to the next step.

    • Describe the IDM 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 IDM admin UI and verify that your configuration changes are present.

Redeploy IDM: Helm installations (technology preview)

  1. Locate the Successfully tagged message in the forgeops build output, which contains the new IDM Docker image’s repository and tag.

  2. Redeploy IDM using the new IDM Docker image:

    $ cd /path/to/forgeops/charts/identity-platform
    $ helm upgrade identity-platform \
     oci://us-docker.pkg.dev/forgeops-public/charts/identity-platform \
     --version 7.4 --namespace my-namespace \
     --set 'idm.image.repository=my-repository' \
     --set 'idm.image.tag=my-idm-tag'
  3. Validate that IDM has the expected configuration:

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

    • Describe the IDM 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 IDM admin UI and verify that your configuration changes are present.

Copyright © 2010-2024 ForgeRock, all rights reserved.