Custom Docker Image Development

Before you can develop custom Docker images, you must have deployed the ForgeRock Identity Platform and learned how to access its administration GUIs and REST APIs. Now you’re ready to configure the platform to meet your needs. As you configure the platform, you can decide at any point to build new custom Docker images that will incorporate the configuration changes you’ve made.

When you develop custom Docker images, you iterate on the following process:

  • Access AM and IDM running in the CDK, and customize them using their GUIs and REST APIs.

  • Export your customizations from the CDK to a Git repository on your local computer.

  • Rebuild the Docker images for the platform with your new customizations.

  • Redeploy the platform on the CDK.

Before you build customized Docker images for the platform, be sure you’re familiar with the types of data used by the platform. This conceptual information helps you understand which type of data is included in custom Docker images.

To develop customized Docker images, start with base images and a canonical configuration profile from ForgeRock. Then, build up a configuration profile, customizing the platform to meet your needs. The configuration profile is integrated into the customized Docker image:

Brief overview of containers for developers.

Before you deploy the platform in production, you must change from using ForgeRock’s evaluation-only base images to using base images you build yourself. Building your own base images is covered in Base Docker Images.

Custom Images for AM

With AM up and running, you can iteratively:

  • Customize AM’s configuration and run-time data using the console and the REST APIs.

  • Capture changes to the AM configuration by synchronizing them from the AM service running on Kubernetes back to the staging area and the master directory for configuration profiles in your forgeops repository clone.

    Skaffold detects the changes and rebuilds the am Docker image. Then, it restarts AM, and you can test any changes you’ve made to the AM configuration based on the updated Docker image.

  • Capture changes to certain run-time data - OAuth 2.0 clients and IG agents - by synchronizing them from the AM service running on Kubernetes back to the staging area and the master directory for configuration profiles in your forgeops repository clone.

    Skaffold detects the changes and rebuilds the amster Docker image.

am Image

The am Docker image contains the AM configuration.

Perform the following procedure iteratively when developing a customized am Docker image:

Create a Customized am Docker Image

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

    1. Run the git status command.

    2. Review the state of the working directory and staging area.

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

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

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

  3. Export the changes you made to the AM configuration to your forgeops repository clone:

    $ cd /path/to/forgeops/bin
$ ./config.sh export --component am --version 7.0
Exporting AM configuration..

Any changed configuration files have been exported into
docker/7.0/am/config. Check any changed files before saving back to the config
folder to ensure correct formatting/functionality.

    The config.sh export command exports the modified parts of the AM configuration from the running ForgeRock Identity Platform to the docker/7.0/am/config directory.

  4. Verify the changed files using the config.sh diff -c am command.

    If any of the files contain hard-coded host names or passwords, replace them with configuration expressions. AM resolves configuration expressions when it starts up.

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

  5. After you’ve replaced all the hard-coded host names and passwords in exported files with configuration expressions, copy the exported files to your configuration profile.

    For more information about the management of ForgeRock Identity Platform configurations in the forgeops repository, see Configuration Profiles.

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

    1. Run the git status command.

    2. Review the state of the working directory and staging area.

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

  7. Reinitialize the staging area with your configuration profile:

    $ cd /path/to/forgeops/bin
$ ./config.sh init --profile my-profile --component am --version 7.0

  8. Execute the skaffold run command:

    $ cd /path/to/forgeops
$ skaffold run

    Skaffold builds a new am Docker image and redeploys AM.

  9. To validate that AM has the expected configuration, start the console and verify that your configuration changes are present.

amster Image

The amster Docker image contains AM run-time data.

Perform the following procedure iteratively when developing a customized amster Docker image:

Create a Customized amster Docker Image

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

    1. Run the git status command.

    2. Review the state of the working directory and staging area.

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

  2. Modify OAuth 2.0 clients or IG agents using the AM console or the REST APIs.

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

  3. Synchronize the changes you made to the AM configuration to your configuration profile in your forgeops repository clone:

    $ cd /path/to/forgeops/bin
$ ./config.sh sync --profile my-profile --component amster --version 7.0
Exporting Amster configuration…​

Skaffold is used to run the export job. Ensure your default-repo is set.

Removing any existing Amster jobs…​
job.batch "amster" deleted
Deploying Amster job…​
Waiting for Amster pod to come up.
No resources found in david namespace.
Amster job is responding..

Executing Amster export within the amster pod
kubectl exec [POD] [COMMAND] is DEPRECATED and will be removed in a future
version. Use kubectl kubectl exec [POD] — [COMMAND] instead.

Amster OpenAM Shell (7.0.0-SNAPSHOT build @build.number@, JVM: 11.0.8)
Type ':help' or ':h' for help.
-----------------------------------------------------------------------------
am> :load /tmp/do_export.amster
Export completed successfully
Copying the export to the ./tmp directory
tar: Removing leading `/' from member names
Dynamic config exported

Shutting down Amster job…​

Saving Amster configuration..


* APPLYING FIXES *
Adding back amsterVersion placeholder …​
Adding back FQDN placeholder …​
Removing 'userpassword-encrypted' fields …​
Add back password placeholder with defaults

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

    The config.sh sync command exports the modified AM configuration profile from the running ForgeRock Identity Platform to the staging area. Then, it saves the configuration profile as my-profile in the master directory for configuration profiles:

    This diagram shows how the config.sh command synchronizes a configuration profile.

    For more information about the management of ForgeRock Identity Platform configuration profiles in the forgeops repository, see Configuration Profiles.

  4. Examine each JSON file that was written to your configuration profile.

    If any of the files contain hard-coded host names or passwords, replace them with configuration expressions. AM resolves configuration expressions when it starts up.

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

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

    1. Run the git status command.

    2. Review the state of the working directory and staging area.

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

  6. Reinitialize the staging area with your configuration profile:

    $ cd /path/to/forgeops/bin
$ ./config.sh init --profile my-profile --component amster --version 7.0

  7. Shut down your ForgeRock Identity Platform deployment and delete PVCs used by the deployment from your namespace. See CDK Shutdown and Removal for details.

  8. Redeploy the ForgeRock Identity Platform:

    $ cd /path/to/forgeops
$ skaffold run

  9. To validate that AM has the expected changes to run-time data, start the console and verify that your changes are present.

Custom Images for IDM

With IDM up and running, you can iteratively:

  • Customize IDM’s configuration using the Admin UI and the REST APIs.

  • Capture your configuration changes by synchronizing them from the IDM service running on Kubernetes back to the staging area and the master directory for configuration profiles in your forgeops repository clone.

    Skaffold detects the changes and rebuilds the idm Docker image. Then, it restarts IDM, and you can test the deployment based on the updated Docker image.

idm Image

The idm Docker image contains the IDM configuration.

Perform the following procedure iteratively when developing a customized idm Docker image:

Create a Customized idm Docker Image

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

    1. Run the git status command.

    2. Review the state of the working directory and staging area.

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

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

    When modifying the IDM configuration, use configuration expressions, not hard-coded values, for all host names and passwords.

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

  3. Synchronize the changes you made to the IDM configuration to your forgeops repository clone:

    $ cd /path/to/forgeops/bin
$ ./config.sh sync --profile my-profile --component idm --version 7.0
tar: Removing leading `/' from member names

    The config.sh sync command exports the modified IDM configuration from the running ForgeRock Identity Platform to the staging area. Then, it saves the configuration profile as my-profile in the master directory for configuration profiles:

    This diagram shows how the config.sh command synchronizes a configuration profile.

    For more information about the management of ForgeRock Identity Platform configurations in the forgeops repository, see Configuration Profiles.

  4. Execute the skaffold run command:

    $ cd /path/to/forgeops
$ skaffold run

    Skaffold builds a new idm Docker image and redeploys IDM.

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

    1. Run the git status command.

    2. Review the state of the working directory and staging area.

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

  6. To validate that IDM has the expected configuration, start the Admin UI and verify that your configuration changes are present.

Property Value Substitution

ForgeRock recommends using property value substitution for all passwords in the ForgeRock Identity Platform configuration in containerized deployments. Property value substitution eases promotion of the ForgeRock Identity Platform configuration from a development environment to a test or production environment.

You should also use property value substitution for host names and any other configuration values that will change as you promote your deployment from a development environment to a test or production environment.

To use property value substitution:

  • For AM, edit exported JSON files, replacing hard-coded values for passwords, host names, and other fields with configuration expressions.

  • For IDM, specify values for passwords, host names, and other fields using configuration expressions in the IDM Admin UI, or when using the REST API.

  • Specify values for configuration expressions in the data section of the config map in the /path/to/forgeops/kustomize/overlay/7.0/all/kustomization.yaml file. Use a key/value pair for each value to be substituted, specifying the configuration expression as the key.

Specifying passwords as described in the preceding section is extremely insecure. The passwords appear in cleartext in a Kubernetes config map.

It is expected that a future version of the platform will be able to resolve configuration expressions for passwords from password management systems; for example, HashiCorp Vault and Google Cloud Key Management System (KMS). For more information, see IDM issue #13262.

About Data Used by the Platform

The ForgeRock Identity Platform uses two types of data: configuration data and run-time data.

Configuration Data

Configuration data consists of properties and settings used by the ForgeRock Identity Platform. You update configuration data during the development phase of ForgeRock Identity Platform implementation. You should not change configuration data during the testing and production phases.

You change configuration data iteratively in a development environment. After changing configuration data, you rebuild Docker images and restart ForgeRock Identity Platform services when you’re ready to test sets of changes. If you make incorrect changes to configuration data, the platform might become inoperable. After testing modifications to configuration data, you promote your changes to test and production environments.

Examples of configuration data include AM realms, AM authentication trees, IDM social identity provider definitions, and IDM data mapping models for reconciliation.

Configuration Profiles

A ForgeRock Identity Platform configuration profile is a named set of configuration data that describes the operational characteristics of a running ForgeRock deployment.

Configuration profiles reside in two locations in the forgeops repository:

  • The master directory. Holds a canonical configuration profile for the CDK and user-customized configuration profiles. User-customized configuration profiles in this directory are considered to be the source of truth for ForgeRock Identity Platform deployments.

    The master directory for configuration profiles is located at the path /path/to/forgeops/config/7.0. You use Git to manage the configuration profiles in this directory.

  • The staging area. Holds a single configuration profile. You copy a profile from the master directory to the staging area before building a customized Docker image for the ForgeRock Identity Platform.

    The staging area is located in subdirectories of the path, /path/to/forgeops/docker/7.0. Configuration profiles copied to the staging area are transient and are not managed with Git.

The config.sh script lets you copy configuration profiles between the master directory and the staging area. It also lets you copy profiles from Kubernetes pods running ForgeRock Identity Platform components to the staging area.

You run this script before you build a customized Docker image for the platform. The script lets you specify which configuration profile to copy to the staging area. Skaffold uses this profile when it builds a Docker image.

For example, when you start developing customized images for the platform, you run the config.sh init command to initialize the staging area with the canonical CDK profile:

This diagram shows how the staging area is initialized from the canonical CDK profile.

You run the config.sh sync command to synchronize configuration changes you’ve made in a running deployment back to the staging area, and then to the master directory:

This diagram shows how the config.sh command synchronizes a configuration profile.

For more information about the config.sh script, see Managing Configurations in the forgeops repository’s top-level README file.

Run-Time Data

Run-time data consists of identities, policies, applications, and data objects used by the ForgeRock Identity Platform. You might extract sample run-time data while developing configuration data. Run-time data is volatile throughout ForgeRock Identity Platform implementation. Expect it to change even when the ForgeRock Identity Platform is in production.

You usually use sample data for run-time data. Run-time data that’s changed during development is not typically promoted to test and production environments. There’s no need to modify Docker images or restart ForgeRock Identity Platform services when run-time data is modified.

Examples of run-time data include AM and IDM identities, AM policies, AM OAuth 2.0 client definitions, and IDM relationships.

In the ForgeRock Identity Platform, run-time data is stored in databases and is not file-based. For more information about how run-time data is stored in AM and IDM, see: