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:
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:
am
Docker Image-
Perform version control activities on your
forgeops
repository clone:-
Run the
git status
command. -
Review the state of the working directory and staging area.
-
(Optional) Run the
git commit
command to commit changes to files that have been modified.
-
-
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.
-
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 thedocker/7.0/am/config
directory. -
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.
-
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. -
Perform version control activities on your
forgeops
repository clone:-
Run the
git status
command. -
Review the state of the working directory and staging area.
-
(Optional) Run the
git commit
command to commit changes to files that have been modified.
-
-
Reinitialize the staging area with your configuration profile:
$ cd /path/to/forgeops/bin $ ./config.sh init --profile my-profile --component am --version 7.0
-
Execute the
skaffold run
command:$ cd /path/to/forgeops $ skaffold run
Skaffold builds a new
am
Docker image and redeploys AM. -
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:
amster
Docker Image-
Perform version control activities on your
forgeops
repository clone:-
Run the
git status
command. -
Review the state of the working directory and staging area.
-
(Optional) Run the
git commit
command to commit changes to files that have been modified.
-
-
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.
-
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 asmy-profile
in the master directory for configuration profiles:For more information about the management of ForgeRock Identity Platform configuration profiles in the
forgeops
repository, see Configuration Profiles. -
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.
-
Perform version control activities on your
forgeops
repository clone:-
Run the
git status
command. -
Review the state of the working directory and staging area.
-
(Optional) Run the
git commit
command to commit changes to files that have been modified.
-
-
Reinitialize the staging area with your configuration profile:
$ cd /path/to/forgeops/bin $ ./config.sh init --profile my-profile --component amster --version 7.0
-
Shut down your ForgeRock Identity Platform deployment and delete PVCs used by the deployment from your namespace. See CDK Shutdown and Removal for details.
-
Redeploy the ForgeRock Identity Platform:
$ cd /path/to/forgeops $ skaffold run
-
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:
idm
Docker Image-
Perform version control activities on your
forgeops
repository clone:-
Run the
git status
command. -
Review the state of the working directory and staging area.
-
(Optional) Run the
git commit
command to commit changes to files that have been modified.
-
-
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.
-
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 asmy-profile
in the master directory for configuration profiles:For more information about the management of ForgeRock Identity Platform configurations in the
forgeops
repository, see Configuration Profiles. -
Execute the
skaffold run
command:$ cd /path/to/forgeops $ skaffold run
Skaffold builds a new
idm
Docker image and redeploys IDM. -
Perform version control activities on your
forgeops
repository clone:-
Run the
git status
command. -
Review the state of the working directory and staging area.
-
(Optional) Run the
git commit
command to commit changes to files that have been modified.
-
-
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:
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:
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:
-
Preparing External Stores in the AM documentation.
-
Store Managed Objects in the Repository in the IDM documentation.