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. If this is your first time building a custom Docker image, verify that you performed developer setup activities:

  2. Verify that:

    • The CDK is deployed.

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

    • All required third-party software is installed in your local environment (Minikube|GKE|EKS|AKS).

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

  4. 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 About property value substitution for important information about configuring values that vary at run-time, such as passwords and host names.

  5. Export the changes you made to the IDM configuration in the running ForgeRock Identity Platform to your configuration profile:

    $ cd /path/to/forgeops/bin
$ ./config export idm my-profile --sort
[INFO] Running export for idm in idm-869679958c-g2dpf
[INFO] Updating existing profile: /path/to/forgeops/docker/idm/config-profiles/my-profile/conf
tar: Removing leading `/' from member names
[INFO] Completed export
[INFO] Sorting configuration.
[INFO] Sorting completed.

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

    Exporting the configuration from the CDK to a configuration profile.

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

    1. Review the differences in the files you exported to your 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"
   }
 }

    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.

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

    $ ./forgeops build idm --config-profile my-profile
Generating tags...
 - idm → idm:afddab145-dirty
Checking cache...
 - idm: Not found. Building
Starting build...
Found [minikube] context, using local docker daemon.
Building [idm]…​
Sending build context to Docker daemon  769.5kB
Step 1/8 : FROM gcr.io/forgerock-io/idm-cdk:7.2.2
7.2.0: Pulling from forgerock-io/idm-cdk
c1ad9731b2c7: Already exists
f963d98b209f: Already exists
...
Step 8/8 : COPY --chown=forgerock:root . /opt/openidm
 --→ a34c1222f3da
Successfully built a34c1222f3da
Successfully tagged idm:afddab145-dirty
Build [idm] succeeded

Updated the image_defaulter with your new image for idm: "idm:a34c12..."

    The forgeops build command calls Skaffold to build a new idm Docker image and push the image to your Docker registry[1]. 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.

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

  9. Redeploy IDM:

    1. Remove IDM from your CDK installation:

      To prevent the forgeops delete command from deleting the PVCs, enter N in response to the prompt: OK to delete PVCs, VolumeSnapshots and Secrets? [Y/N]

      $ cd /path/to/forgeops/bin
$ ./forgeops delete idm
OK to delete these components? [Y/N] Y
This will erase all your PVCs(including backup PVCs), VolumeSnapshots and Secrets. This cannot be undone.
Press "CTRL+C" now if you want to cancel
OK to delete PVCs, VolumeSnapshots and Secrets? [Y/N] N
configmap "idm" deleted
configmap "idm-logging-properties" deleted
service "idm" deleted
deployment.apps "idm" deleted

    2. Redeploy IDM:

      $ ./forgeops install idm --cdk
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): ['idm']

configmap/idm created
configmap/idm-logging-properties created
service/idm created
deployment.apps/idm created

Enjoy your deployment!

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

  10. To validate that IDM has the expected configuration:

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

Additional topics of interest

Cloud Deployment Model

Deploy the CDM, ForgeRock’s reference implementation for cloud deployment.
How-Tos

Customize CDM deployments.
Shutdown

Shut down and remove your CDK deployment.
1. Occasionally, Skaffold has issues with cached images. To work around a caching problem, remove Skaffold’s cache by running the rm -rf $HOME/.skaffold/cache command. If removing the cache still does not resolve the problem, use the docker pull command to manually pull the images.