`am` image

The am Docker image contains the AM configuration.

Customization overview

Customize AM’s configuration data by using the AM admin UI and REST APIs.
Capture changes to the AM configuration by exporting them from the AM service running on Kubernetes 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.
Redeploy AM.
Verify that changes you’ve made to the AM configuration are in the new Docker image.

Detailed steps

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).
- You have set up your environment to push to your Docker registry.
Perform version control activities on your forgeops repository clone:
1. Run the git status command.
2. Review the state of the docker/am/config-profiles/my-profile directory.
3. (Optional) Run the git commit command to commit changes to files that have been modified.
Modify the AM configuration using the AM admin UI or the REST APIs.

For information about how to access the AM admin UI or REST APIs, refer to AM Services.

Refer to About property value substitution for important information about configuring values that vary at run-time, such as passwords and host names.

Export the changes you made to the AM configuration in the running ForgeRock Identity Platform to a configuration profile:

$ cd /path/to/forgeops/bin
$ ./config export am my-profile --sort
[INFO] Running export for am in am-6fb64659f-bmdhh
[INFO] Updating existing profile: /path/to/forgeops/docker/am/config-profiles/my-profile
[INFO] Clean profile: /path/to/forgeops/docker/am/config-profiles/my-profile
[INFO] Exported AM config
[INFO] Running AM static config through the am-config-upgrader to upgrade to the current version of forgeops.

+ docker run --rm --user 502:20 --volume /path/to/forgeops/docker/am/config-profiles/my-profile:/am-config gcr.io/forgerock-io/am-config-upgrader/pit1:7.4.0' locally
7.4.0-latest-postcommit: Pulling from gcr.io/forgerock-io/am-config-upgrader/pit1
...
Reading existing configuration from files in /am-config/config/services...
Modifying configuration based on rules in [/rules/latest.groovy]...
reading configuration from file-based config files
Writing configuration to new location at /am-config/config/services...
Upgrade Completed, modified configuration saved to /am-config/config/services
[INFO] Completed upgrading AM configuration
[INFO] Running AM static config through the am-config-upgrader to replace any missing default placeholders.

+ docker run --rm --user 502:20 --volume /path/to/forgeops/docker/am/config-profiles/my-profile:/am-config --volume /path/to/forgeops/etc/am-upgrader-rules:/rules gcr.io/forgerock-io/am-config-upgrader/pit1:7.4.0

...

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
...
Writing configuration to new location at /am-config/config/services...
Upgrade Completed, modified configuration saved to /am-config/config/services
[INFO] Completed replacing AM placeholders
[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 am my-profile command copies AM static configuration from the running CDK instance to the configuration profile:

Perform version control activities on your forgeops repository clone:

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

$ git diff
diff --git a/docker/am/config-profiles/my-profile/config/services/realm/root/selfservicetrees/1.0/organizationconfig/default.json b/docker/am/config-profiles/my-profile/config/services/realm/root/selfservicetrees/1.0/organizationconfig/default.json
index 970c5a257..19f4f17f0 100644
--- a/docker/am/config-profiles/my-profile/config/services/realm/root/selfservicetrees/1.0/organizationconfig/default.json
+ b/docker/am/config-profiles/my-profile/config/services/realm/root/selfservicetrees/1.0/organizationconfig/default.json
@@ -9,6 +9,7 @@
     "enabled": true,
     "treeMapping": {
       "Test": "Test",
+      "Test1": "Test1",
       "forgottenUsername": "ForgottenUsername",
       "registration": "Registration",
       "resetPassword": "ResetPassword",

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

Run the git status command.
If you have new untracked files in your clone, run the git add command.
Review the state of the docker/am/config-profiles/my-profile directory.
(Optional) Run the git commit command to commit changes to files that have been modified.

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 am image step.
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 in the build am image step.

Build a new am image that includes your changes to AM static configuration:

$ ./forgeops build am --config-profile my-profile --push-to my-repo --tag my-am-tag
Flag --short has been deprecated, and will be removed in the future.
[+] Building 3.2s (10/10) FINISHED
...
⇒ [internal] load metadata for gcr.io/forgerock-io/am-cdk:7.4.0
 ⇒ [1/5] FROM gcr.io/forgerock-io/am-cdk:7.4.0@sha256:...
...
 ⇒ [5/5] WORKDIR /home/forgerock
 ⇒ exporting to image
 ⇒ ⇒ exporting layers
 ⇒ ⇒ writing image sha256:...
 ⇒ ⇒ naming to docker.io/library/am

What’s Next?
  View a summary of image vulnerabilities and recommendations → docker scout quickview
Updated the image_defaulter with your new image for am: "am".

Redeploy AM using your new AM image:
- If you installed the platform using the forgeops command, follow the steps in Redeploy AM: forgeops command installations.
- If you installed the platform using Helm, follow the steps in Redeploy AM: Helm installations (technology preview).

Redeploy AM: forgeops command installations

The forgeops build command calls Docker to build a new am 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 AM, the forgeops install command gets AM static configuration from your new custom Docker image.

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.

Remove AM from your CDK installation:

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

Redeploy AM:

$ ./forgeops install am --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): ['am'] platform: "cdk" in namespace: "my-namespace" from deployment manifests in …

service/am created
deployment.apps/am created

Enjoy your deployment!

Validate that AM 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 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 admin UI and verify that your configuration changes are present.

Redeploy AM: Helm installations (technology preview)

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

Redeploy AM using the new AM 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 'am.image.repository=my-repository' \
 --set 'am.image.tag=my-am-tag'

Validate that AM 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 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 admin UI and verify that your configuration changes are present.

ForgeOps

`am` image

Customization overview

Detailed steps

Redeploy AM: forgeops command installations

Redeploy AM: Helm installations (technology preview)

Next step

ForgeOps

am image

Customization overview

Detailed steps

Redeploy AM: forgeops command installations

Redeploy AM: Helm installations (technology preview)

Next step

`am` image