ForgeOps Documentation

ForgeRock provides a number of resources to help you get started in the cloud. These resources demonstrate how to deploy the ForgeRock Identity Platform on Kubernetes.

The ForgeRock Identity Platform serves as the basis for our simple and comprehensive identity and access management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

Start Here

ForgeRock provides several resources to help you get started in the cloud. These resources demonstrate how to deploy the ForgeRock Identity Platform on Kubernetes. Before you proceed, review the following precautions:

  • Deploying ForgeRock software in a containerized environment requires advanced proficiency in many technologies. See Assess Your Skill Level for details.

  • If you don’t have experience with complex Kubernetes deployments, then either engage a certified ForgeRock consulting partner or deploy the platform on traditional architecture.

  • Don’t deploy ForgeRock software in Kubernetes in production until you have successfully deployed and tested the software in a non-production Kubernetes environment.

For information about obtaining support for ForgeRock Identity Platform software, see Support From ForgeRock.

Introducing the CDK and CDM

The forgeops repository and DevOps documentation address a range of our customers' typical business needs. The repository contains artifacts for two primary resources to help you with cloud deployment:

  • Cloud Developer’s Kit (CDK). The CDK is a minimal sample deployment for development purposes. Developers deploy the CDK, and then access AM’s and IDM’s GUI consoles and REST APIs to configure the platform and build customized Docker images for the platform.

  • Cloud Deployment Model (CDM). The CDM is a reference implementation for ForgeRock cloud deployments. You can get a sample ForgeRock Identity Platform deployment up and running in the cloud quickly using the CDM. After deploying the CDM, you can use it to explore how you might configure your Kubernetes cluster before you deploy the platform in production.

    The CDM is a robust sample deployment for demonstration and exploration purposes only. It is not a production deployment.

CDK CDM

Fully integrated AM, IDM, and DS installations

Randomly generated secrets

Resource requirement

Namespace in a GKE, EKS, AKS, or Minikube cluster

GKE, EKS, or AKS cluster

Can run on Minikube

Multi-zone high availability

Replicated directory services

Ingress configuration

Certificate management

Prometheus monitoring, Grafana reporting, and alert management

ForgeRock’s DevOps documentation helps you deploy the CDK and CDM:

  • Cloud Developer’s Kit Documentation. Tells you how to install the CDK, modify the AM and IDM configurations, and create customized Docker images for the ForgeRock Identity Platform.

  • Cloud Deployment Model Documentation. Tells you how to quickly create a Kubernetes cluster on Google Cloud, Amazon Web Services (AWS), or Microsoft Azure, install the ForgeRock Identity Platform, and access components in the deployment.

  • How-Tos. Contains how-tos for customizing monitoring, setting alerts, backing up and restoring directory data, modifying CDM’s default security configuration, and running lightweight benchmarks to test DS, AM, and IDM performance.

  • DevOps Release Notes. Keeps you up-to-date with the latest changes to the forgeops repository.

Try Out the CDK and the CDM

Before you start planning a production deployment, deploy either the CDK or the CDM—or both. If you’re new to Kubernetes, or new to the ForgeRock Identity Platform, deploying these resources is a great way to learn. When you’ve finished deploying them, you’ll have sandboxes suitable for exploring ForgeRock cloud deployment.

Deploy the CDK

Illustrates the major tasks performed to get the ${cdk.abbr} running as a sample environment.

The CDK is a minimal sample deployment of the ForgeRock Identity Platform. If you have access to a cluster on Google Cloud, EKS, or AKS, you can deploy the CDK in a namespace on your cluster. You can also deploy the CDK locally in a standalone Minikube environment, and when you’re done, you’ll have a local Kubernetes cluster with the platform orchestrated on it.

Prerequisite technologies and skills:

More information:

Deploy the CDM

Illustrates the major tasks performed to deploy the ${cdm.abbr}.

Deploy the CDM on Google Cloud, AWS, or Microsoft Azure to quickly spin up the platform for demonstration purposes. You’ll get a feel for what it’s like to deploy the platform on a Kubernetes cluster in the cloud. When you’re done, you won’t have a production-quality deployment. But you will have a robust, reference implementation of the platform.

After you get the CDM up and running, you can use it to test deployment customizations—options that you might want to use in production, but are not part of the CDM. Examples include, but are not limited to:

  • Running lightweight benchmark tests

  • Making backups of CDM data, and restoring the data

  • Securing TLS with a certificate that’s dynamically obtained from Let’s Encrypt

  • Using an ingress controller other than the NGINX ingress controller

  • Resizing the cluster to meet your business requirements

  • Configuring Alert Manager to issue alerts when usage thresholds have been reached

Prerequisite technologies and skills:

More information:

Build Your Own Service

Illustrates the major tasks performed when building a production deployment of ${platform.name} in the cloud.

Perform the following activities to customize, deploy, and maintain a production ForgeRock Identity Platform implementation in the cloud:

Create a Project Plan

Illustrates the major tasks performed when planning a production deployment of ${platform.name} in the cloud.

After you’ve spent some time exploring the CDK and CDM, you’re ready to define requirements for your production deployment. Remember, the CDM is not a production deployment. Use the CDM to explore deployment customizations, and incorporate the lessons you’ve learned as you build your own production service.

Analyze your business requirements and define how the ForgeRock Identity Platform needs to be configured to meet your needs. Identify systems to be integrated with the platform, such as identity databases and applications, and plan to perform those integrations. Assess and specify your deployment infrastructure requirements, such as backup, system monitoring, Git repository management, CI/CD, quality assurance, security, and load testing.

Prerequisite technologies and skills:

More information:

Configure the Platform

Illustrates the major tasks performed to configure the ${platform.name} before deploying in production.

With your project plan defined, you’re ready to configure the ForgeRock Identity Platform to meet the plan’s requirements. Install the CDK on your developers' computers. Configure AM and IDM. If needed, include integrations with external applications in the configuration. Iteratively unit test your configuration as you modify it. Build customized Docker images that contain the configuration.

Prerequisite technologies and skills:

More information:

Configure Your Cluster

Illustrates the major tasks performed to configure the cluster before deploying in production.

With your project plan defined, you’re ready to configure a Kubernetes cluster that meets the requirements defined in the plan. Install the platform using the customized Docker images developed in Configure the Platform. Provision the ForgeRock identity repository with users, groups, and other identity data. Load test your deployment, and then size your cluster to meet service level agreements. Perform integration tests. Harden your deployment. Set up CI/CD for your deployment. Create monitoring alerts so that your site reliability engineers are notified when the system reaches thresholds that affect your SLAs. Implement database backup and test database restore. Simulate failures while under load to make sure your deployment can handle them.

Prerequisite technologies and skills:

More information:

Stay Up and Running

Illustrates the major tasks performed to keep a ${platform.name} deployment up and running in production.

By now, you’ve configured the platform, configured a Kubernetes cluster, and deployed the platform with your customized configuration. Run your ForgeRock Identity Platform deployment in your cluster, continually monitoring it for performance and reliability. Take backups as needed.

Prerequisite technologies and skills:

More information:

Assess Your Skill Level

Benchmarking and Load Testing

I can:

  • Write performance tests, using tools such as Gatling and Apache JMeter, to ensure that the system meets required performance thresholds and service level agreements (SLAs).

  • Resize a Kubernetes cluster, taking into account performance test results, thresholds, and SLAs.

  • Run Linux performance monitoring utilities, such as top.

CI/CD for Cloud Deployments

I have experience:

  • Designing and implementing a CI/CD process for a cloud-based deployment running in production.

  • Using a cloud CI/CD tool, such as Tekton, Google Cloud Build, Codefresh, AWS CloudFormation, or Jenkins, to implement a CI/CD process for a cloud-based deployment running in production.

  • Integrating GitOps into a CI/CD process.

Docker

I know how to:

  • Write Dockerfiles.

  • Create Docker images, and push them to a private Docker registry.

  • Pull and run images from a private Docker registry.

I understand:

  • The concepts of Docker layers, and building images based on other Docker images using the FROM instruction.

  • The difference between the COPY and ADD instructions in a Dockerfile.

Git

I know how to:

  • Use a Git repository collaboration framework, such as GitHub, GitLab, or Bitbucket Server.

  • Perform common Git operations, such as cloning and forking repositories, branching, committing changes, submitting pull requests, merging, viewing logs, and so forth.

External Application and Database Integration

I have expertise in:

  • AM policy agents.

  • Configuring AM policies.

  • Synchronizing and reconciling identity data using IDM.

  • Managing cloud databases.

  • Connecting ForgeRock Identity Platform components to cloud databases.

ForgeRock Identity Platform

I have:

  • Attended ForgeRock University training courses.

  • Deployed the ForgeRock Identity Platform in production, and kept the deployment highly available.

  • Configured DS replication.

  • Passed the ForgeRock Certified Access Management and ForgeRock Certified Identity Management exams (highly recommended).

Google Cloud, AWS, or Azure (Basic)

I can:

  • Use the graphical user interface for Google Cloud, AWS, or Azure to navigate, browse, create, and remove Kubernetes clusters.

  • Use the cloud provider’s tools to monitor a Kubernetes cluster.

  • Use the command user interface for Google Cloud, AWS, or Azure.

  • Administer cloud storage.

Google Cloud, AWS, or Azure (Expert)

  • Read the cluster creation shell scripts in the forgeops repository to see how the CDM cluster is configured.

  • Create and manage a Kubernetes cluster using an infrastructure-as-code tool such as Terraform, AWS CloudFormation, or Pulumi.

  • Configure multi-zone and multi-region Kubernetes clusters.

  • Configure cloud-provider identity and access management (IAM).

  • Configure virtual private clouds (VPCs) and VPC networking.

  • Manage keys in the cloud using a service such as Google Key Management Service (KMS), Amazon KMS, or Azure Key Vault.

  • Configure and manage DNS domains on Google Cloud, AWS, or Azure.

  • Troubleshoot a deployment running in the cloud using the cloud provider’s tools, such as Google Stackdriver, Amazon CloudWatch, or Azure Monitor.

  • Integrate a deployment with certificate management tools, such as cert-manager and Let’s Encrypt.

  • Integrate a deployment with monitoring and alerting tools, such as Prometheus and Alertmanager.

I have obtained one of the following certifications (highly recommended):

  • Google Certified Associate Cloud Engineer Certification.

  • AWS professional-level or associate-level certifications (multiple).

  • Azure Administrator.

Integration Testing

I can:

  • Automate QA testing using a test automation framework.

  • Design a chaos engineering test for a cloud-based deployment running in production.

  • Use chaos engineering testing tools, such as Chaos Monkey.

Kubernetes (Basic)

I’ve gone through the tutorials at kubernetes.io, and am able to:

  • Use the kubectl command to determine the status of all the pods in a namespace, and to determine whether pods are operational.

  • Use the kubectl describe pod command to perform basic troubleshooting on pods that are not operational.

  • Use the kubectl command to obtain information about namespaces, secrets, deployments, and stateful sets.

  • Use the kubectl command to manage persistent volumes and persistent volume claims.

Kubernetes (Expert)

In addition to the basic skills for Kubernetes, I have:

  • Configured role-based access to cloud resources.

  • Configured Kubernetes objects, such as deployments and stateful sets.

  • Configured Kubernetes ingresses.

  • Passed the Cloud Native Certified Kubernetes Administrator exam (highly recommended).

Project Planning and Management for Cloud Deployments

I have planned and managed:

  • A production deployment in the cloud.

  • A production deployment of ForgeRock Identity Platform.

Security and Hardening for Cloud Deployments

I can:

  • Harden a ForgeRock Identity Platform deployment.

  • Configure TLS, including mutual TLS, for a multi-tiered cloud deployment.

  • Configure cloud identity and access management and role-based access control for a production deployment.

  • Configure encryption for a cloud deployment.

  • Configure Kubernetes network security policies.

  • Configure private Kubernetes networks, deploying bastion servers as needed.

  • Undertake threat modeling exercises.

  • Scan Docker images to ensure container security.

  • Configure and use private Docker container registries.

Site Reliability Engineering for Cloud Deployments

I can:

  • Manage multi-zone and multi-region deployments.

  • Implement DS backup and restore in order to recover from a database failure.

  • Manage cloud disk availability issues.

  • Analyze monitoring output and alerts, and respond should a failure occur.

  • Obtain logs from all the software components in my deployment.

  • Follow the cloud provider’s recommendations for patching and upgrading software in my deployment.

  • Implement an upgrade scheme, such as blue/green or rolling upgrades, in my deployment.

  • Create a Site Reliability Runbook for the deployment, documenting all the procedures to be followed and other relevant information.

  • Follow all the procedures in the project’s Site Reliability Runbook, and revise the runbook if it becomes out-of-date.

About the forgeops Repository

Use ForgeRock’s forgeops repository to customize and deploy the ForgeRock Identity Platform on a Kubernetes cluster.

The repository contains files needed for customizing and deploying the ForgeRock Identity Platform on a Kubernetes cluster:

  • Files used to build Docker images for the ForgeRock Identity Platform:

    • Dockerfiles

    • Scripts and configuration files incorporated into ForgeRock’s Docker images

    • Canonical configuration profiles for the platform

  • Kustomize bases and overlays

  • Skaffold configuration files

In addition, the repository contains numerous utility scripts and sample files. The scripts and samples are useful for:

  • Deploying ForgeRock’s CDM quickly and easily

  • Exploring monitoring, alerts, and security customization

  • Modeling a CI/CD solution for cloud deployment

See Repository Reference for information about the files in the repository, recommendations about how to work with them, and the support status for the files.

Repository Updates

New forgeops repository features become available in the release/7.1.0 branch of the repository from time to time.

When you start working with the forgeops repository, clone the repository. Depending on your organization’s setup, you’ll clone the repository either from ForgeRock’s public repository on GitHub, or from a fork. See Git Clone or Git Fork? for more information.

Then, check out the release/7.1.0 branch and create a working branch. For example:

$ git checkout release/7.1.0
$ git checkout -b my-working-branch

ForgeRock recommends that you regularly incorporate updates to the release/7.1.0 into your working branch:

  1. Review the Release Notes from time to time—they provide information about updates.

  2. Pull new commits in the release/7.1.0 branch into your clone’s release/7.1.0 branch.

  3. Rebase the commits from the new branch into your working branch in your forgeops repository clone.

It’s important to understand the impact of rebasing changes from the forgeops repository into your branches. Repository Reference provides advice about which files in the forgeops repository to change, which files not to change, and what to look out for when you rebase. Follow the advice in Repository Reference to reduce merge conflicts, and to better understand how to resolve them when you rebase your working branch with updates that ForgeRock has made to the release/7.1.0 branch.

Repository Reference

Directories

bin

Example scripts you can use or model for a variety of deployment tasks.

Recommendation: Don’t modify the files in this directory. If you want to add your own scripts to the forgeops repository, create a subdirectory under bin, and store your scripts there.

Support Status: Sample files. Not supported by ForgeRock.

cicd

Example files for working with Google Cloud Build CI/CD.

Recommendation: Don’t modify the files in this directory. If you want to add your own CI/CD support files to the forgeops repository, create a subdirectory under cicd, and store your files there.

Support Status: Sample files. Not supported by ForgeRock.

cluster

Example scripts and artifacts that automate cluster creation.

Recommendation: Don’t modify the files in this directory. If you want to add your own cluster creation support files to the forgeops repository, create a subdirectory under cluster, and store your files there.

Support Status: Sample files. Not supported by ForgeRock.

config

Configuration profiles, including the canonical cdk profile from ForgeRock and user-customized profiles.

Recommendation: Add your own profiles to this directory using the config.sh command. Do not modify the canonical cdk profile.

Support Status: Configuration profiles:

docker

Dockerfiles and other support files needed to build Docker images for the ForgeRock Identity Platform.

Recommendation: When customizing ForgeRock’s default deployments, you’ll need to add files under the docker/7.0 directory. For example, to customize the AM WAR file, you might need to add plugin JAR files, user interface customization files, or image files.

If you only add new files under the docker/7.0 directory, you should not encounter merge conflicts when you rebase changes from a new release tag into your branches. However, if you need to modify any files from ForgeRock, you might encounter merge conflicts. Be sure to track changes you’ve made to any files in the docker directory, so that you’re prepared to resolve merge conflicts after a rebase.

Support Status: Dockerfiles and other files needed to build Docker images for the ForgeRock Identity Platform. Support is available from ForgeRock.

etc

Files used to support several examples, including the CDM.

Recommendation: Don’t modify the files in this directory (or its subdirectories). If you want to use CDM automated cluster creation as a model or starting point for your own automated cluster creation, then create your own subdirectories under etc, and copy the files you want to model into the subdirectories.

Support Status: Sample files. Not supported by ForgeRock.

jenkins-scripts

For ForgeRock internal use only. Do not modify or use.

kustomize

Artifacts for orchestrating the ForgeRock Identity Platform using Kustomize.

Recommendation: Common deployment customizations, such as changing the deployment namespace and providing a customized FQDN, require modifications to files in the kustomize/overlay/7.0 directory. You’ll probably change, at minimum, the kustomize/overlay/7.0/all/kustomization.yaml file.

Expect to encounter merge conflicts when you rebase changes from a new release tag into your branches. Be sure to track changes you’ve made to files in the kustomize directory, so that you’re prepared to resolve merge conflicts after a rebase.

Support Status: Kustomize bases and overlays. Support is available from ForgeRock.

legacy-docs

Documentation for deploying the ForgeRock Identity Platform using DevOps techniques. Includes documentation for supported and deprecated versions of the forgeops repository.

Recommendation: Don’t modify the files in this directory.

Support Status:

Documentation for supported versions of the forgeops repository: Support is available from ForgeRock.

Documentation for deprecated versions of the forgeops repository: Not supported by ForgeRock.

Files in the Top-Level Directory

.gcloudignore, .gitchangelog.rc, .gitignore

For ForgeRock internal use only. Do not modify.

cloudbuild.yaml

Example files for working with Google Cloud Build.

Recommendation: Don’t modify this file. If you want to add your own Cloud Build configuration to the forgeops repository, use a different file name.

Support Status: Sample file. Not supported by ForgeRock.

LICENSE

Software license for artifacts in the forgeops repository. Do not modify.

Makefile

For ForgeRock internal use only. Do not modify.

notifications.json

For ForgeRock internal use only. Do not modify.

README.md

The top-level forgeops repository README file. Do not modify.

skaffold.yaml

The declarative configuration for running Skaffold to deploy the ForgeRock Identity Platform.

Recommendation: If you need to customize the skaffold.yaml file, you might encounter merge conflicts when you rebase changes from a new release tag into your branches. Be sure to track changes you’ve made to this file, so that you’re prepared to resolve merge conflicts after a rebase.

Support Status:

small, medium, large, am, amster, idm, ds-cts, ds-idrepo, and ig profiles: Support is available from ForgeRock.

All other profiles, including the am-only, am-idm-only, ds-only, idm-only, ig-only, no-ui, and persistence profiles are for ForgeRock internal use only. Support is not available from ForgeRock.

Git Clone or Git Fork?

For the simplest use cases—a single user in an organization installing the CDK or CDM for a proof of concept, or exploration of the platform—cloning ForgeRock’s public forgeops repository from GitHub provides a quick and adequate way to access the repository.

If, however, your use case is more complex, you might want to fork the forgeops repository, and use the fork as your common upstream repository. For example:

  • Multiple users in your organization need to access a common version of the repository and share changes made by other users.

  • Your organization plans to incorporate forgeops repository changes from ForgeRock.

  • Your organization wants to use pull requests when making repository updates.

If you’ve forked the forgeops repository:

  • You’ll need to synchronize your fork with ForgeRock’s public repository on GitHub when ForgeRock releases a new release tag.

  • Your users will need to clone your fork before they start working instead of cloning the public forgeops repository on GitHub. Because procedures in the Cloud Developer’s Kit Documentation and the Cloud Deployment Model Documentation tell users to clone the public repository, you’ll need to make sure your users follow different procedures to clone the forks instead.

  • The steps for initially obtaining and updating your repository clone will differ from the steps provided in the documentation. You’ll need to let users know how to work with the fork as the upstream instead of following the steps in the documentation.

Cloud Developer’s Kit Documentation

The CDK is a minimal sample deployment of the ForgeRock Identity Platform on Kubernetes that you can use for demonstration and development purposes. It includes fully integrated AM, IDM, and DS installations, and randomly generated secrets.

If you have access to a cluster on Google Cloud, EKS, or AKS, you can deploy the CDK in a namespace on your cluster. You can also deploy the CDK locally in a standalone Minikube environment, and when you’re done, you’ll have a local Kubernetes cluster with the platform orchestrated on it.

About the Cloud Developer's Kit

The CDK is a minimal sample deployment of the ForgeRock Identity Platform on Kubernetes that you can use for demonstration and development purposes. It includes fully integrated AM, IDM, and DS installations, and randomly generated secrets.

CDK deployments orchestrate a working version of the ForgeRock Identity Platform on Kubernetes. They also let you build and run customized Docker images for the platform.

This documentation describes how to deploy the CDK, and then use it to create and test customized Docker images containing your custom AM and IDM configurations:

Illustrates the major configuration tasks performed before deploying in production.

Before deploying the platform in production, you must customize it using the CDK. To better understand how this activity fits into the overall deployment process, see Configure the Platform.

Containerization

The CDK uses Docker for containerization. Start with evaluation-only Docker images from ForgeRock that include canonical configurations for AM and IDM. Then, customize the configurations, and create your own images that include your customized configurations.

For more information about Docker images for the ForgeRock Identity Platform, see About Custom Images.

Orchestration

The CDK uses Kubernetes for container orchestration. The CDK has been tested on the following Kubernetes implementations:

Next Step

CDK Architecture

Before you can deploy the CDK, you must have access to a namespace in a Kubernetes cluster. The cluster must have an ingress controller deployed on it.

CDK Deployments

  • Let you get the ForgeRock Identity Platform up and running on Kubernetes.

  • Are suitable for demonstrations and proofs of concept.

  • Build Kubernetes manifests based on the Kustomize bases and overlays in your local forgeops repository clone.

  • Use the image defaulter to specify which Docker images to use to run the platform:

    • By default, the image defaulter specifies the evaluation-only Docker images for release 7.1.0 of the platform, available from ForgeRock’s public registry. These images use ForgeRock’s canonical configurations for AM and IDM.

    • When you build custom Docker images with customized AM and IDM configurations, the cdk build command updates the image defaulter to specify your custom images.

The cdk install command with the --dev option uses your own Docker images.

CDK Pods

After deploying the platform, you’ll see the following pods running in your namespace. The pods are the same, regardless of whether you performed a demo or developer deployment:

Diagram of the deployed ${cdk.abbr}.
am

Runs ForgeRock Access Management.

When AM starts for the first time in a CDK deployment, it obtains its configuration from the AM Docker image. If you subsequently restart AM, it obtains its configuration from the Git repository running in your namespace.

After the am pod has started, a job is triggered that populates AM’s application store with several agents and OAuth 2.0 client definitions that are used by the CDK.

ds-idrepo-0

The ds-idrepo-0 pod provides directory services for:

  • The identity repository shared by AM and IDM

  • The IDM repository

  • The AM application and policy store

  • AM’s Core Token Service

idm

Runs ForgeRock Identity Management.

When IDM starts for the first time in a CDK deployment, it obtains its configuration from the IDM Docker image. If you subsequently restart IDM, it obtains its configuration from the Git repository running in your namespace.

In containerized deployments, IDM must retrieve its configuration from the file system and not from the IDM repository. The default values for the openidm.fileinstall.enabled and openidm.config.repo.enabled properties in the CDK’s system.properties file ensure that IDM retrieves its configuration from the file system. Do not override the default values for these properties.

rcs-agent

Runs the IDM Remote Connector Server Agent.

UI pods

Several pods provide access to ForgeRock common user interfaces:

  • admin-ui

  • end-user-ui

  • login-ui

Next Step

Minikube Environment Setup Checklist

forgeops Repository

Before you can deploy the CDK or the CDM, you must first get the forgeops repository and check out the release/7.1.0 branch:

  1. Clone the forgeops repository. For exmple:

    $ git clone https://github.com/ForgeRock/forgeops.git

    The forgeops repository is a public Git repository. You do not need credentials to clone it.

  2. Check out the release/7.1.0 branch:

    $ cd forgeops
    $ git checkout release/7.1.0

Depending on your organization’s repository strategy, you might need to clone the repository from a fork, instead of cloning ForgeRock’s master repository. You might also need to create a working branch from the release/7.1.0 branch. For more information, see Repository Updates.

Next Step

Third-Party Software

Before performing a demo deployment, you must obtain non-ForgeRock software and install it on your local computer.

ForgeRock recommends that you install third-party software using Homebrew on macOS and Linux[3] .

The versions listed in the following tables have been validated for deploying the ForgeRock Identity Platform and building custom Docker images for it. Earlier and later versions will probably work. If you want to try using versions that are not in the tables, it is your responsibility to validate them.

Install the following third-party software:

Software Version Homebrew package

Python 3

3.9.6

python

Kubernetes client (kubectl)

1.21.2

kubectl

Kubernetes context switcher (kubectx)

0.9.3

kubectx

Kustomize

4.2.0

kustomize

VirtualBox

6.1.22

virtualbox (cask)[3]

Minikube

1.23.2

minikube

If you plan to use the CDK to create custom Docker images for the ForgeRock Identity Platform, install the following additional software:

Software Version Homebrew package

Docker Desktop[4]

3.6.0

docker (cask)[3]

Skaffold

1.26.1

skaffold

Next Step

Minikube Cluster

Minikube software runs a single-node Kubernetes cluster in a virtual machine.

The cluster/minikube/cluster-up utility creates a Minikube cluster with a configuration that’s suitable for CDK deployments.

To set up Minikube:

$ cd /path/to/forgeops/cluster/minikube
$ ./cluster-up
Running: "minikube start --cpus=3 --memory=10g --disk-size=40g
--kubernetes-version=1.21.4 --addons=ingress,volumesnapshots --driver=virtualbox --bootstrapper kubeadm"
😄  minikube v1.23.2 on Darwin 11.5.1
    ▪ MINIKUBE_ACTIVE_DOCKERD=minikube
✨  Using the virtualbox driver based on user configuration
💿  Downloading VM boot image …​
    > minikube-v1.23.1.iso.sha256: 65 B / 65 B [-------------] 100.00% ? p/s 0s
    > minikube-v1.23.1.iso: 225.22 MiB / 225.22 MiB [ 100.00% 4.00 MiB p/s 1m2s
👍  Starting control plane node minikube in cluster minikube
🔥  Creating virtualbox VM (CPUs=3, Memory=10240MB, Disk=40960MB) . . .
🐳  Preparing Kubernetes v1.21.4 on Docker 20.10.6 …​
    ▪ Generating certificates and keys …​
    ▪ Booting up control plane …​
    ▪ Configuring RBAC rules …​
    ▪ Using image gcr.io/k8s-minikube/storage-provisioner:v5
    ▪ Using image k8s.gcr.io/sig-storage/snapshot-controller:v4.0.0
    ▪ Using image k8s.gcr.io/ingress-nginx/controller:v1.0.0-beta.3
    ▪ Using image k8s.gcr.io/ingress-nginx/kube-webhook-certgen:v1.0
    ▪ Using image k8s.gcr.io/ingress-nginx/kube-webhook-certgen:v1.0
    ▪ Using image gcr.io/k8s-minikube/storage-provisioner:v5
    You have selected "virtualbox" driver, but there are better options !
    For better performance and support consider using a different driver:
            - hyperkit
    To turn off this warning run:
            $ minikube config set WantVirtualBoxDriverWarning false
    To learn more about on minikube drivers checkout https://minikube.sigs.k8s.io/docs/drivers/
    To see benchmarks checkout https://minikube.sigs.k8s.io/docs/benchmarks/cpuusage/
🔎  Verifying Kubernetes components. . .
🔎  Verifying ingress addon. . .
🌟  Enabled addons: storage-provisioner, default-storageclass, volumesnapshots, ingress
🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default

The cluster/minikube/cluster-up utility uses the VirtualBox driver by default. Version 7.1 of the ForgeRock Identity Platform has been tested on Minikube clusters configured with the VirtualBox driver. If you prefer to configure a different virtual machine driver:

  • To configure your Minikube cluster with the Hyperkit driver (macOS systems only), specify the --driver hyperkit option when you run the cluster-up utility.

  • To configure your Minikube cluster with the Docker driver (Linux systems only), specify the --driver docker option when you run the cluster-up utility.

Next Step

Namespace

Create a namespace in your new cluster.

ForgeRock recommends that you deploy the ForgeRock Identity Platform in a namespace other than the default namespace. Deploying to a non-default namespace lets you separate workloads in a cluster. Separating a workload into a namespace lets you delete the workload easily; just delete the namespace.

To create a namespace:

  1. Create a namespace in your Kubernetes cluster:

    $ kubectl create namespace my-namespace
    namespace/my-namespace created
  2. Make the new namespace your active namespace:

    $ kubens my-namespace
    Context "minikube" modified.
    Active namespace is "my-namespace".
Next Step

Hostname Resolution

Set up hostname resolution for the ForgeRock Identity Platform servers you’ll deploy in your namespace:

  1. Run the minikube ip command to get the Minikube ingress controller’s IP address:

    $ minikube ip
    192.168.99.100
  2. Choose an FQDN (referred to as the deployment FQDN) that you’ll use when you deploy the ForgeRock Identity Platform, and when you access its GUIs and REST APIs.

    Examples in this documentation use dev.example.com as the deployment FQDN. You are not required to use dev.example.com; you can specify any FQDN you like.

  3. Add an entry to the /etc/hosts file to resolve the deployment FQDN. For example:

    minikube-ip-address dev.example.com
Next Step

TLS Certificate (Optional)

This page covers several options you can use to encrypt HTTP communications over TLS in CDK deployments.

Self-Signed Certificate

By default, Minikube’s ingress controller plugin is configured with a self-signed certificate. This is the simplest encryption option—you don’t have to make any changes to the CDK to get encryption.

However, when you access one of the ForgeRock web applications from your browser, you’ll get a "Not Secure" message from your browser. You’ll need to bypass the message.

Certificate From a Certificate Authority (CA)

If you have a certificate from a CA, you can use the certificate for TLS encryption. Install the certificate and your private key in a Kubernetes secret in your namespace. Minikube’s ingress controller plugin gets the certificate from the secret, and then uses it to encrypt communications.

To use a certficate from a CA in a CDK deployment on Minikube:

  1. Obtain the certificate:

    • Make sure that the certificate is PEM-encoded.

    • A best practice is to include the entire trust chain in your .pem file.

  2. Make sure that the deployment FQDN that you specified in your /etc/hosts file works with your certificate.

  3. Create a secret named sslcert in your namespace that contains the certificate. For example:

    $ kubectl create secret tls sslcert --cert=/path/to/my-cert.crt --key=/path/to/my-key.key
Certificate Generated by the mkcert Utility

If you don’t have a certificate from a CA, you can use the mkcert utility to generate a locally trusted certificate. In many cases, it’s acceptable to use such certificates for development purposes.

To use a certificate generated by the mkcert utility in a CDK deployment on Minikube that uses dev.example.com as the deployment FQDN:

  1. If you don’t have mkcert software installed locally, install it. Firefox users also need to install certutil software. See the mkcert installation instructions for more information.

  2. If you haven’t ever done so, run the mkcert -install command to create a local certificate authority (CA) and install it in your system root store. Restart your browser after creating the local CA.

  3. Create a wildcard certificate for the iam.example.com domain:

    $ cd
    $ mkcert "*.example.com"
  4. Create a secret named sslcert in your namespace that contains the wildcard certificate. For example:

    $ kubectl create secret tls sslcert --cert=./_wildcard.example.com.pem --key=./_wildcard.example.com-key.pem
Next Step

GKE Environment Setup Checklist

forgeops Repository

Before you can deploy the CDK or the CDM, you must first get the forgeops repository and check out the release/7.1.0 branch:

  1. Clone the forgeops repository. For exmple:

    $ git clone https://github.com/ForgeRock/forgeops.git

    The forgeops repository is a public Git repository. You do not need credentials to clone it.

  2. Check out the release/7.1.0 branch:

    $ cd forgeops
    $ git checkout release/7.1.0

Depending on your organization’s repository strategy, you might need to clone the repository from a fork, instead of cloning ForgeRock’s master repository. You might also need to create a working branch from the release/7.1.0 branch. For more information, see Repository Updates.

Next Step

Third-Party Software

Before performing a demo deployment, you must obtain non-ForgeRock software and install it on your local computer.

ForgeRock recommends that you install third-party software using Homebrew on macOS and Linux[5] .

The versions listed in the following tables have been validated for deploying the ForgeRock Identity Platform and building custom Docker images for it. Earlier and later versions will probably work. If you want to try using versions that are not in the tables, it is your responsibility to validate them.

Install the following third-party software:

Software Version Homebrew package

Python 3

3.9.6

python

Kubernetes client (kubectl)

1.21.2

kubectl

Kubernetes context switcher (kubectx)

0.9.3

kubectx

Kustomize

4.2.0

kustomize

Google Cloud SDK

354.0.0

google-cloud-sdk (cask)[3]

If you plan to use the CDK to create custom Docker images for the ForgeRock Identity Platform, install the following additional software:

Software Version Homebrew package

Docker Desktop[6]

3.6.0

docker (cask)[3]

Skaffold

1.26.1

skaffold

Next Step

Cluster Details

You’ll need to get some information about the cluster from your cluster administrator. You’ll provide this information as you perform various tasks to access the cluster.

  1. Obtain the following cluster details:

    • The name of the Google Cloud project that contains the cluster.

    • The cluster name.

    • The Google Cloud zone in which the cluster resides.

    • The IP address of your cluster’s ingress controller.

    • The location of the Docker registry from which your cluster will obtain images for the ForgeRock Identity Platform.

  2. Verify that the following operators are installed on the cluster:

    • The Secret Agent operator

    • The DS operator

Next Step

Context for the Shared Cluster

Kubernetes uses contexts to access Kubernetes clusters. Before you can access the shared cluster, you must create a context on your local computer if it’s not already present.

To create a context for the shared cluster:

  1. Run the kubectx command and review the output. The current Kubernetes context is highlighted:

    • If the current context references the shared cluster, there is nothing further to do. Proceed to Namespace.

    • If the context of the shared cluster is present in the kubectx command output, set the context as follows:

      $ kubectx my-context
      Switched to context "my-context".

      After you have set the context, proceed to Namespace.

    • If the context of the shared cluster is not present in the kubectx command output, continue to the next step.

  2. Configure the Google Cloud SDK standard component to use your Google account. Run the following command:

    $ gcloud auth login
  3. A browser window prompts you to log in to Google. Log in using your Google account.

    A second screen requests several permissions. Select Allow.

    A third screen should appear with the heading, "You are now authenticated with the Google Cloud SDK!"

  4. Return to the terminal window and run the following command. Use the cluster name, zone, and project name you obtained from your cluster administrator:

    $ gcloud container clusters \
     get-credentials cluster-name --zone google-zone --project google-project
    Fetching cluster endpoint and auth data.
    kubeconfig entry generated for cluster-name.
  5. Run the kubectx command again and verify that the context for our Kubernetes cluster is now the current context.

Next Step

Namespace

Create a namespace in the shared cluster. Namespaces let you isolate your deployments from other developers' deployments.

ForgeRock recommends that you deploy the ForgeRock Identity Platform in a namespace other than the default namespace. Deploying to a non-default namespace lets you separate workloads in a cluster. Separating a workload into a namespace lets you delete the workload easily; just delete the namespace.

To create a namespace:

  1. Create a namespace in your Kubernetes cluster:

    $ kubectl create namespace my-namespace
    namespace/my-namespace created
  2. Make the new namespace your current namespace:

    $ kubens my-namespace
    Context "my-context" modified.
    Active namespace is "my-namespace".
Next Step

Hostname Resolution

You might need to set up hostname resolution for the ForgeRock Identity Platform servers you’ll deploy in your namespace:

  1. Choose an FQDN (referred to as the deployment FQDN) that you’ll use when you deploy the ForgeRock Identity Platform, and when you access its GUIs and REST APIs.

    Examples in this documentation use dev.example.com as the deployment FQDN. You are not required to use dev.example.com; you can specify any FQDN you like.

  2. If DNS does not resolve your deployment FQDN, add an entry similar to the following to the /etc/hosts file:

    ingress-ip-address dev.example.com

    For ingress-ip-address, specify the IP address of your cluster’s ingress controller that you obtained from your cluster administrator.

Next Step

Amazon EKS Environment Setup Checklist

forgeops Repository

Before you can deploy the CDK or the CDM, you must first get the forgeops repository and check out the release/7.1.0 branch:

  1. Clone the forgeops repository. For exmple:

    $ git clone https://github.com/ForgeRock/forgeops.git

    The forgeops repository is a public Git repository. You do not need credentials to clone it.

  2. Check out the release/7.1.0 branch:

    $ cd forgeops
    $ git checkout release/7.1.0

Depending on your organization’s repository strategy, you might need to clone the repository from a fork, instead of cloning ForgeRock’s master repository. You might also need to create a working branch from the release/7.1.0 branch. For more information, see Repository Updates.

Next Step

Third-Party Software

Before performing a demo deployment, you must obtain non-ForgeRock software and install it on your local computer.

ForgeRock recommends that you install third-party software using Homebrew on macOS and Linux[7] .

The versions listed in the following tables have been validated for deploying the ForgeRock Identity Platform and building custom Docker images for it. Earlier and later versions will probably work. If you want to try using versions that are not in the tables, it is your responsibility to validate them.

Install the following third-party software:

Software Version Homebrew package

Python 3

3.9.6

python

Kubernetes client (kubectl)

1.21.2

kubectl

Kubernetes context switcher (kubectx)

0.9.3

kubectx

Kustomize

4.2.0

kustomize

Amazon AWS Command Line Interface

2.2.13

awscli

AWS IAM Authenticator for Kubernetes

0.5.3

aws-iam-authenticator

If you plan to use the CDK to create custom Docker images for the ForgeRock Identity Platform, install the following additional software:

Software Version Homebrew package

Docker Desktop[8]

3.6.0

docker (cask)[3]

Skaffold

1.26.1

skaffold

Next Step

Cluster Details

You’ll need to get some information about the cluster from your cluster administrator. You’ll provide this information as you perform various tasks to access the cluster.

  1. Obtain the following cluster details:

    • Your AWS access key ID.

    • Your AWS secret access key.

    • The AWS region in which the cluster resides.

    • The cluster name.

    • The IP address of your cluster’s ingress controller.

    • The location of the Docker registry from which your cluster will obtain images for the ForgeRock Identity Platform.

  2. Verify that the following operators are installed on the cluster:

    • The Secret Agent operator

    • The DS operator

Next Step

Context for the Shared Cluster

Kubernetes uses contexts to access Kubernetes clusters. Before you can access the shared cluster, you must create a context on your local computer if it’s not already present.

To create a context for the shared cluster:

  1. Run the kubectx command and review the output. The current Kubernetes context is highlighted:

    • If the current context references the shared cluster, there is nothing further to do. Proceed to Namespace.

    • If the context of the shared cluster is present in the kubectx command output, set the context as follows:

      $ kubectx my-context
      Switched to context "my-context".

      After you have set the context, proceed to Namespace.

    • If the context of the shared cluster is not present in the kubectx command output, continue to the next step.

  2. Run the aws configure command. This command logs you in to AWS and sets the AWS region. Use the access key ID, secret access key, and region you obtained from your cluster administrator. You do not need to specify a value for the default output format:

    $ aws configure
    AWS Access Key ID [None]:
    AWS Secret Access Key [None]:
    Default region name [None]:
    Default output format [None]:
  3. Run the following command. Use the cluster name you obtained from your cluster administrator:

    $ aws eks update-kubeconfig --name my-cluster
    Added new context arn:aws:eks:us-east-1:813759318741:cluster/my-cluster
    to /Users/my-user-name/.kube/config
  4. Run the kubectx command again and verify that the context for your Kubernetes cluster is now the current context.

In Amazon EKS environments, the cluster owner must grant access to a user before the user can access cluster resources. For details about how the cluster owner can grant you access to the cluster, refer the cluster owner to Cluster Access for Multiple AWS Users.

Next Step

Namespace

Create a namespace in the shared cluster. Namespaces let you isolate your deployments from other developers' deployments.

ForgeRock recommends that you deploy the ForgeRock Identity Platform in a namespace other than the default namespace. Deploying to a non-default namespace lets you separate workloads in a cluster. Separating a workload into a namespace lets you delete the workload easily; just delete the namespace.

To create a namespace:

  1. Create a namespace in your Kubernetes cluster:

    $ kubectl create namespace my-namespace
    namespace/my-namespace created
  2. Make the new namespace your current namespace:

    $ kubens my-namespace
    Context "my-context" modified.
    Active namespace is "my-namespace".
Next Step

Hostname Resolution

You might need to set up hostname resolution for the ForgeRock Identity Platform servers you’ll deploy in your namespace:

  1. Choose an FQDN (referred to as the deployment FQDN) that you’ll use when you deploy the ForgeRock Identity Platform, and when you access its GUIs and REST APIs.

    Examples in this documentation use dev.example.com as the deployment FQDN. You are not required to use dev.example.com; you can specify any FQDN you like.

  2. If DNS does not resolve your deployment FQDN, add an entry similar to the following to the /etc/hosts file:

    ingress-ip-address dev.example.com

    For ingress-ip-address, specify the IP address of your cluster’s ingress controller that you obtained from your cluster administrator.

Next Step

AKS Environment Setup Checklist

forgeops Repository

Before you can deploy the CDK or the CDM, you must first get the forgeops repository and check out the release/7.1.0 branch:

  1. Clone the forgeops repository. For exmple:

    $ git clone https://github.com/ForgeRock/forgeops.git

    The forgeops repository is a public Git repository. You do not need credentials to clone it.

  2. Check out the release/7.1.0 branch:

    $ cd forgeops
    $ git checkout release/7.1.0

Depending on your organization’s repository strategy, you might need to clone the repository from a fork, instead of cloning ForgeRock’s master repository. You might also need to create a working branch from the release/7.1.0 branch. For more information, see Repository Updates.

Next Step

Third-Party Software

Before performing a demo deployment, you must obtain non-ForgeRock software and install it on your local computer.

ForgeRock recommends that you install third-party software using Homebrew on macOS and Linux[9] .

The versions listed in the following tables have been validated for deploying the ForgeRock Identity Platform and building custom Docker images for it. Earlier and later versions will probably work. If you want to try using versions that are not in the tables, it is your responsibility to validate them.

Install the following third-party software:

Software Version Homebrew package

Python 3

3.9.6

python

Kubernetes client (kubectl)

1.21.2

kubectl

Kubernetes context switcher (kubectx)

0.9.3

kubectx

Kustomize

4.2.0

kustomize

Azure Command Line Interface

2.25.0

azure-cli

If you plan to use the CDK to create custom Docker images for the ForgeRock Identity Platform, install the following additional software:

Software Version Homebrew package

Docker Desktop[10]

3.6.0

docker (cask)[3]

Skaffold

1.26.1

skaffold

Next Step

Cluster Details

You’ll need to get some information about the cluster from your cluster administrator. You’ll provide this information as you perform various tasks to access the cluster.

  1. Obtain the following cluster details:

    • The ID of the Azure subscription that contains the cluster. Be sure to obtain the hexadecimal subscription ID, not the subscription name.

    • The name of the resource group that contains the cluster.

    • The cluster name.

    • The IP address of your cluster’s ingress controller.

    • The location of the Docker registry from which your cluster will obtain images for the ForgeRock Identity Platform.

  2. Verify that the following operators are installed on the cluster:

    • The Secret Agent operator

    • The DS operator

Next Step

Context for the Shared Cluster

Kubernetes uses contexts to access Kubernetes clusters. Before you can access the shared cluster, you must create a context on your local computer if it’s not already present.

To create a context for the shared cluster:

  1. Run the kubectx command and review the output. The current Kubernetes context is highlighted:

    • If the current context references the shared cluster, there is nothing further to do. Proceed to Namespace.

    • If the context of the shared cluster is present in the kubectx command output, set the context as follows:

      $ kubectx my-context
      Switched to context "my-context".

      After you have set the context, proceed to Namespace.

    • If the context of the shared cluster is not present in the kubectx command output, continue to the next step.

  2. Configure the Azure CLI to use your Microsoft Azure. Run the following command:

    $ az login
  3. A browser window prompts you to log in to Azure. Log in using your Microsoft account.

    A second screen should appear with the message, "You have logged into Microsoft Azure!"

  4. Return to the terminal window and run the following command. Use the resource group, cluster name, and subscription ID you obtained from your cluster administrator:

    $ az aks get-credentials \
     --resource-group my-fr-resource-group \
     --name my-fr-cluster \
     --subscription your subscription ID \
     --overwrite-existing
  5. Run the kubectx command again and verify that the context for your Kubernetes cluster is now the current context.

Next Step

Namespace

Create a namespace in the shared cluster. Namespaces let you isolate your deployments from other developers' deployments.

ForgeRock recommends that you deploy the ForgeRock Identity Platform in a namespace other than the default namespace. Deploying to a non-default namespace lets you separate workloads in a cluster. Separating a workload into a namespace lets you delete the workload easily; just delete the namespace.

To create a namespace:

  1. Create a namespace in your Kubernetes cluster:

    $ kubectl create namespace my-namespace
    namespace/my-namespace created
  2. Make the new namespace your current namespace:

    $ kubens my-namespace
    Context "my-context" modified.
    Active namespace is "my-namespace".
Next Step

Hostname Resolution

You might need to set up hostname resolution for the ForgeRock Identity Platform servers you’ll deploy in your namespace:

  1. Choose an FQDN (referred to as the deployment FQDN) that you’ll use when you deploy the ForgeRock Identity Platform, and when you access its GUIs and REST APIs.

    Examples in this documentation use dev.example.com as the deployment FQDN. You are not required to use dev.example.com; you can specify any FQDN you like.

  2. If DNS does not resolve your deployment FQDN, add an entry similar to the following to the /etc/hosts file:

    ingress-ip-address dev.example.com

    For ingress-ip-address, specify the IP address of your cluster’s ingress controller that you obtained from your cluster administrator.

Next Step

CDK Deployment

After you’ve set up your environment, deploy the CDK:

  1. Run the cdk install command:

    $ cd /path/to/forgeops/bin
    $ ./cdk install --namespace my-namespace --fqdn dev.example.com

    By default, the cdk install command uses the evaluation-only Docker images for release 7.1.0 of the platform, available from ForgeRock’s public registry.

    However, if you have built custom images for the ForgeRock Identity Platform, the cdk install command uses your custom images.

    The cdk install command in this example deploys the entire ForgeRock Identity Platform. If you prefer, you can deploy the platform component by component. See Staged CDK Installation.

  2. In a separate terminal tab or window, run the kubectl get pods command to monitor status of the deployment. Wait until all the pods are ready.

    Your namespace should have the pods shown in this diagram.

Next Step

UI and API Access

Now that you’ve deployed the ForgeRock Identity Platform, you’ll need to know how to access its administration tools. You’ll use these tools to build customized Docker images for the platform.

This page shows you how to access the ForgeRock Identity Platform’s administrative consoles and REST APIs.

You access AM and IDM services through the Kubernetes ingress controller. Access components using their normal interfaces:

  • For AM, the console and REST APIs.

  • For IDM, the Admin UI and REST APIs.

You can’t access DS through the ingress controller, but you can use Kubernetes methods to access the DS pods.

For more information about how AM and IDM are configured in the CDK, see Configuration in the forgeops repository’s top-level README file.

AM Services

To access the AM console:

  1. Make sure that your namespace is the current namespace:

    $ kubens my-namespace
  2. Obtain the amadmin user’s password:

    $ cd /path/to/forgeops/bin
    $ ./print-secrets amadmin
    179rd8en9rffa82rcf1qap1z0gv1hcej
  3. Open a new window or tab in a web browser.

  4. Go to https://dev.example.com/platform.

    The Kubernetes ingress controller handles the request, routing it to the login-ui pod.

    The login UI prompts you to log in.

  5. Log in as the amadmin user.

    The ForgeRock Identity Platform UI appears in the browser.

  6. Select Native Consoles > Access Management.

    The AM console appears in the browser.

To access the AM REST APIs:

  1. Start a terminal window session.

  2. Run a curl command to verify that you can access the REST APIs through the ingress controller. For example:

    $ curl \
     --insecure \
     --request POST \
     --header "Content-Type: application/json" \
     --header "X-OpenAM-Username: amadmin" \
     --header "X-OpenAM-Password: 179rd8en9rffa82rcf1qap1z0gv1hcej" \
     --header "Accept-API-Version: resource=2.0" \
     --data "{}" \
     "https://dev.example.com/am/json/realms/root/authenticate"
    {
        "tokenId":"AQIC5wM2. . .TU3OQ*",
        "successUrl":"/am/console",
        "realm":"/"
    }

IDM Services

To access the IDM Admin UI:

  1. Make sure that your namespace is the current namespace:

    $ kubens my-namespace
  2. Obtain the amadmin user’s password:

    $ cd /path/to/forgeops/bin
    $ ./print-secrets amadmin
    vr58qt11ihoa31zfbjsdxxrqryfw0s31
  3. Open a new window or tab in a web browser.

  4. Go to https://dev.example.com/platform.

    The Kubernetes ingress controller handles the request, routing it to the login-ui pod.

    The login UI prompts you to log in.

  5. Log in as the amadmin user.

    The ForgeRock Identity Platform UI appears in the browser.

  6. Select Native Consoles > Identity Management.

    The IDM Admin UI appears in the browser.

To access the IDM REST APIs:

  1. Start a terminal window session.

  2. If you haven’t already done so, get the amadmin user’s password using the print-secrets command.

  3. AM authorizes IDM REST API access using the OAuth 2.0 authorization code flow. The CDK comes with the idm-admin-ui client, which is configured to let you get a bearer token using this OAuth 2.0 flow. You’ll use the bearer token in the next step to access the IDM REST API:

    1. Get a session token for the amadmin user:

      $ curl \
       --request POST \
       --insecure \
       --header "Content-Type: application/json" \
       --header "X-OpenAM-Username: amadmin" \
       --header "X-OpenAM-Password: vr58qt11ihoa31zfbjsdxxrqryfw0s31" \
       --header "Accept-API-Version: resource=2.0, protocol=1.0" \
       "https://dev.example.com/am/json/realms/root/authenticate"
      {
       "tokenId":"AQIC5wM. . .TU3OQ*",
       "successUrl":"/am/console",
       "realm":"/"}
    2. Get an authorization code. Specify the ID of the session token that you obtained in the previous step in the --Cookie parameter:

      $ curl \
       --dump-header - \
       --insecure \
       --request GET \
       --Cookie "iPlanetDirectoryPro=AQIC5wM. . .TU3OQ*" \
       "https://dev.example.com/am/oauth2/realms/root/authorize?redirect_uri=https://dev.example.com/platform/appAuthHelperRedirect.html&client_id=idm-admin-ui&scope=openid%20fr:idm:*&response_type=code&state=abc123"
      HTTP/2 302
      server: nginx/1.17.10
      date: Tue, 21 Jul 2020 16:54:20 GMT
      content-length: 0
      location: https://dev.example.com/platform/appAuthHelperRedirect.html
       ?code=3cItL9G52DIiBdfXRngv2_dAaYM&iss=http://dev.example.com:80/am/oauth2&state=abc123
       &client_id=idm-admin-ui
      set-cookie: route=1595350461.029.542.7328; Path=/am; Secure; HttpOnly
      x-frame-options: SAMEORIGIN
      x-content-type-options: nosniff
      cache-control: no-store
      pragma: no-cache
      set-cookie: OAUTH_REQUEST_ATTRIBUTES=DELETED; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/; HttpOnly
      strict-transport-security: max-age=15724800; includeSubDomains
    3. Exchange the authorization code for an access token. Specify the access code that you obtained in the previous step in the code URL parameter:

      $ curl --request POST \
       --insecure \
       --data "grant_type=authorization_code" \
       --data "code=3cItL9G52DIiBdfXRngv2_dAaYM" \
       --data "client_id=idm-admin-ui" \
       --data "redirect_uri=https://dev.example.com/platform/appAuthHelperRedirect.html" \
       "https://dev.example.com/am/oauth2/realms/root/access_token" 
      {
       "access_token":"oPzGzGFY1SeP2RkI-ZqaRQC1cDg",
       "scope":"openid fr:idm:*",
       "id_token":"eyJ0eXAiOiJKV
        . . .
        sO4HYqlQ",
       "token_type":"Bearer",
       "expires_in":239
      }
  4. Run a curl command to verify that you can access the openidm/config REST endpoint through the ingress controller. Use the access token returned in the previous step as the bearer token in the authorization header.

    The following example command provides information about the IDM configuration:

    $ curl \
     --insecure \
     --request GET \
     --header "Authorization: Bearer oPzGzGFY1SeP2RkI-ZqaRQC1cDg" \
     --data "{}" \
     "https://dev.example.com/openidm/config"
    {
     "_id":"",
     "configurations":
      [
       {
        "_id":"ui.context/admin",
        "pid":"ui.context.4f0cb656-0b92-44e9-a48b-76baddda03ea",
        "factoryPid":"ui.context"
        },
        . . .
       ]
    }

Directory Services

The DS pods in the CDK are not exposed outside of the cluster. If you need to access one of the DS pods, use a standard Kubernetes method:

  • Execute shell commands in DS pods using the kubectl exec command.

  • Forward a DS pod’s LDAPS port (1636) to your local computer. Then, you can run LDAP CLI commands like ldapsearch. You can also use an LDAP editor such as Apache Directory Studio to access the directory.

For all CDM directory pods, the directory superuser DN is uid=admin. Obtain this user’s password by running the print-secrets dsadmin command.

Next Step

Overview

This section covers how developers build custom Docker images for the ForgeRock Identity Platform. It also contains important conceptual material that you need to understand before you start creating Docker images.

Additional Setup

This page covers setup tasks that you’ll need to perform before you can develop custom Docker images for the ForgeRock Identity Platform. Complete all of the tasks on this page before proceeding.

Configure Your Environment to Write to Your Docker Registry

Set up your local environment to write Docker images:

Minikube

Set up your local environment to execute docker commands on Minikube’s Docker engine.

ForgeRock recommends using the built-in Docker engine when developing custom Docker images using Minikube. When you use Minikube’s Docker engine, you don’t have to build Docker images on a local engine and then push the images to a local or cloud-based Docker registry. Instead, you build images using the same Docker engine that Minikube uses. This streamlines development.

To set up your local computer to use Minikube’s Docker engine:

  1. Run the docker-env command in your shell:

    $ eval $(minikube docker-env)
  2. Stop Skaffold from pushing Docker images to a remote Docker registry [1]:

    $ skaffold config set --kube-context minikube local-cluster true
    set value local-cluster to true for context minikube

For more information about using Minikube’s built-in Docker engine, see Use local images by re-using the Docker daemon in the Minikube documentation.

GKE shared cluster

In the environment you’re setting up, Skaffold builds Docker images using the Docker software you’ve installed on your local computer. After it builds the images, Skaffold pushes them to a Docker registry available to your GKE cluster.

For Skaffold to be able to push the Docker images:

  • Docker must be running on your local computer.

  • Your local computer needs credentials that let Skaffold push the images to the Docker registry available to your cluster.

  • Skaffold needs to know the location of the Docker registry.

To set up your local computer to push Docker images:

  1. If it’s not already running, start Docker on your local computer. For more information, see the Docker documentation.

  2. Set up a Docker credential helper:

    $ gcloud auth configure-docker
  3. Run the kubectx command to obtain the Kubernetes context.

  4. Configure Skaffold with the Docker registry location you obtained from your cluster administrator and the Kubernetes context you obtained in Context for the Shared Cluster:

    $ skaffold config set default-repo my-docker-registry --kube-context my-kubernetes-context
EKS shared cluster

In the environment you’re setting up, Skaffold builds Docker images using the Docker software you’ve installed on your local computer. After it builds the images, Skaffold pushes them to a Docker registry available to your EKS cluster.

For Skaffold to be able to push the Docker images:

  • Docker must be running on your local computer.

  • Your local computer needs credentials that let Skaffold push the images to the Docker registry available to your cluster.

  • Skaffold needs to know the location of the Docker registry.

To set up your local computer to push Docker images:

  1. If it’s not already running, start Docker on your local computer. For more information, see the Docker documentation.

  2. Log in to Amazon ECR. Use the Docker registry location you obtained from your cluster administrator:

    $ aws ecr get-login-password | \
     docker login --username AWS --password-stdin my-docker-registry
    stdin my-docker-registry
    Login Succeeded

    ECR login sessions expire after 12 hours. Because of this, you’ll need to perform these steps again whenever your login session expires.[2]

  3. Run the kubectx command to obtain the Kubernetes context.

  4. Configure Skaffold with the Docker registry location and the Kubernetes context:

    $ skaffold config set default-repo my-docker-registry --kube-context my-kubernetes-context
AKS shared cluster

In the environment you’re setting up, Skaffold builds Docker images using the Docker software you’ve installed on your local computer. After it builds the images, Skaffold pushes them to a Docker registry available to your AKS cluster.

For Skaffold to be able to push the Docker images:

  • Docker must be running on your local computer.

  • Your local computer needs credentials that let Skaffold push the images to the Docker registry available to your cluster.

  • Skaffold needs to know the location of the Docker registry.

To set up your local computer to push Docker images:

  1. If it’s not already running, start Docker on your local computer. For more information, see the Docker documentation.

  2. Install the ACR Docker Credential Helper.

  3. Run the kubectx command to obtain the Kubernetes context.

  4. Configure Skaffold with the Docker registry location you obtained from your cluster administrator and the Kubernetes context you obtained in Context for the Shared Cluster:

    $ skaffold config set default-repo my-docker-registry --kube-context my-kubernetes-context
Create a Configuration Profile

Your configuration profile contains your customizations to ForgeRock’s canonical configuration.

To initialize your configuration profile with ForgeRock’s canonical configuration:

  • First, initialize the staging area with ForgeRock’s canonical configuration.

  • Then, save the configuration to your configuration profile in the /path/to/forgeops/config directory.

Perform these steps:

  1. Change to the /path/to/forgeops/bin directory.

  2. Initialize the staging area with the canonical CDK configuration profile for the ForgeRock Identity Platform:

    $ cd /path/to/forgeops/bin
    $ ./config.sh init --profile cdk
    Removing docker/7.0/am/config/
    Removing docker/7.0/amster/config/
    Removing docker/7.0/idm/conf/
    Removing docker/7.0/idm/ui/
    Removing docker/7.0/ig/config/
    Copying /path/to/forgeops/config/7.0/cdk/idm.
    Copying /path/to/forgeops/config/7.0/cdk/am.
    Copying /path/to/forgeops/config/7.0/cdk/ig.
    Copying /path/to/forgeops/config/7.0/cdk/amster.
    Completed

    The config.sh init --profile cdk command clears out the staging area, and then copies the canonical configuration for the CDK from the config/7.0/cdk directory to the staging area:

    Initializing the staging area.
  3. Initialize your configuration profile with the canonical AM static configuration:

    $ ./config.sh save --component am --profile my-profile
    Saving AM configuration.

    The config.sh save --component am --profile my-profile command copies AM’s static configuration from the staging area to a configuration profile. Because the configuration profile does not exist yet, the config.sh save command creates it.

    Saving the configuration from the staging area.
  4. Initialize your configuration profile with the canonical IDM static configuration:

    $ ./config.sh save --component idm --profile my-profile
    Saving IDM configuration.

    The config.sh save --component idm --profile my-profile command copies IDM’s static configuration from the staging area to a configuration profile.

    Saving the configuration from the staging area.
Next Step

About Custom Images

In Development

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.
In Production

Before you deploy the platform in production, you’ll need to stop using ForgeRock’s evaluation-only base images, and start using base images you build yourself. Building your own base images is covered in Base Docker Images. Then, customize your own base images by integrating the configuration profile you’ve developed into them:

Brief overview of containers used in production.
Next Step

Types of Configuration

The ForgeRock Identity Platform uses three types of configuration: static configuration, dynamic configuration, and identities.

Static Configuration

Static configuration consists of properties and settings used by the ForgeRock Identity Platform. Examples of static configuration include AM realms, AM authentication trees, IDM social identity provider definitions, and IDM data mapping models for reconciliation.

Static configuration is stored in JSON configuration files. Because of this, static configuration is also referred to as file-based configuration.

You build static configuration into the am and idm Docker images during development, using the following general process:

  1. Change the AM or IDM configuration in the CDK using the UIs and APIs.

  2. Export the changes to your forgeops repository clone.

  3. Build a new AM or IDM Docker image that contains the updated configuration.

  4. Restart ForgeRock Identity Platform services using the new Docker images.

  5. Test your changes. Incorrect changes to static configuration might cause the platform to become inoperable.

  6. Promote your changes to your test and production environments as desired.

See am Image and idm Image for more detailed steps.

In ForgeRock Identity Platform deployments, static configuration is immutable. Do not change static configuration in testing or production. Instead, if you need to change static configuration, return to the development phase, make your changes, and build new custom Docker images that include the changes. Then, promote the new images to your test and production environments.

Dynamic Configuration

Dynamic configuration consists of access policies, applications, and data objects used by the ForgeRock Identity Platform. Examples of dynamic configuration include AM access policies, AM agents, AM OAuth 2.0 client definitions, and IDM relationships.

Dynamic configuration can change at any time, including when the platform is running in production.

You’ll need to devise a strategy for managing AM and IDM dynamic configuration, so that you can:

  • Extract sample dynamic configuration for use by developers.

  • Back up and restore dynamic configuration.

Identities

Identities are another type of dynamic configuration. They can be modified at any time, including when the platform is running in production.

As with AM and IDM dynamic configuration, you’ll need to devise a strategy to manage identities that lets you:

  • Extract sample user identities that can be used by developers.

  • Back up and restore user identities.

Configuration Profiles

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

  • AM static configuration

  • IDM static configuration

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. 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. You run this script before you build customized Docker images for the platform. The script lets you specify which configuration profile to copy to the staging area. The cdk build command uses the profile that’s been copied to the staging area when it builds a Docker image.

Next Step

About Property Value Substitution

Many property values in ForgeRock’s canonical CDK configuration profile are specified as configuration expressions instead of as hard-coded values. Fully-qualified domain names (FQDNs), passwords, and several other properties are all specified as configuration expressions.

Configuration expressions are property values in the AM and IDM configurations that are set when AM and IDM start up. Instead of being set to fixed, hard-coded values in the AM and IDM configurations, their values vary, depending on conditions in the run-time environment.

Using configuration expressions lets you use a single configuration profile that takes different values at run-time depending on the deployment environment. For example, you can use a single configuration profile for development, test, and production deployments.

In the ForgeRock Identity Platform, configuration expressions are preceded by an ampersand and enclosed in braces. For example, &{am.encryption.key}.

The statement, am.encryption.pwd=&{am.encryption.key} in the AM configuration indicates that the value of the property, am.encryption.pwd, is determined when AM starts up. Contrast this with a statement, am.encryption.pwd=myPassw0rd, which sets the property to a hard-coded value, myPassw0rd, regardless of the run-time environment.

How Property Value Substitution Works

This example shows how property value substitution works for a value specified as a configuration expression in the AM configuration:

  1. Search the /path/to/forgeops/config/7.0/cdk directory for the string &{.

  2. Locate this line in your search results:

    "am.encryption.pwd=&{am.encryption.key}",

    Because the property am.encryption.pwd is being set to a configuration expression, its value will be determined when AM starts up.

  3. Search the forgeops repository for the string AM_ENCRYPTION_KEY. You’ll see that the secret agent operator sets the environment variable, AM_ENCRYPTION_KEY. The property, am.encryption.pwd, will be set to the value of the environment variable, AM_ENCRYPTION_KEY when AM starts up.

Configuration expressions take their values from environment variables as follows:

  • Uppercase characters replace lowercase characters in the configuration expression’s name.

  • Underscores replace periods in the configuration expression’s name.

For more information about configuration expressions, see Property Value Substitution in the IDM documentation.

AM and IDM Differences

There are several subtle but important differences between the AM and IDM implementations of configuration expressions:

  • Canonical configuration profile.

    AM: Contains configuration expressions for usernames, passwords, FQDNs, and the URL access protocol.

    IDM: Contains configuration expressions for usernames, passwords, FQDNs, the URL access protocol, and additional properties.

  • Administration console handling of configuration expressions.

    AM: The console is not aware of configuration expressions. Values specified as configuration expressions in configuration profiles are displayed as run-time values in the console. You cannot specify property values as configuration expressions in the console.

    IDM: The Admin UI is aware of configuration expressions. Values specified as configuration expressions in configuration profiles are displayed as configuration expressions in the Admin UI. You can specify property values as configuration expressions in the Admin UI.

  • Export configuration behavior.

    AM: Configuration expressions are reinserted into the AM configuration, overriding hard-coded property values you might have set using the console.

    IDM: Configuration expressions are exported to the IDM configuration profile.

  • Replacing a hard-coded property value with a configuration expression.

    AM: Edit the AM configuration manually, replacing a property value with a configuration expression. Then, open the /path/to/forgeops/config/am-config-upgrader/placeholders.groovy file, and add a rule that preserves the new configuration expression.

    IDM: Change the property’s value to a configuration expression in the Admin UI. When the configuration is exported, the exported configuration contains the configuration expression.

  • Replacing a configuration expression with a hard-coded property value.

    AM: Edit the AM configuration manually, replacing a configuration expression with a hard-coded property value. Then, open the /path/to/forgeops/config/am-config-upgrader/placeholders.groovy file, and remove the rule that preserved the configuration expression you

    IDM: Hard-code the property’s value in the IDM Admin UI. When the configuration is exported, the exported configuration contains the hard-coded property value.

  • Configuration expressions' run-time values.

    AM: Configuration expressions get their values from environment variables.

    IDM: Configuration expressions can get their values from a variety of sources: environment variables, Java system properies, and configuration files.

Next Step

am Image

The am Docker image contains the AM configuration.

Customization Overview
  • Customize AM’s configuration data by using the console and the 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

Perform the following steps iteratively when developing a custom am Docker image:

  1. If this is your first time building a custom Docker image, verify that you performed these setup activities, which are required for developers:

  2. Verify that:

    • The CDK is deployed.

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

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

    1. Run the git status command.

    2. Review the state of the config directory.

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

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

    For information about how to access the AM console or REST APIs, see AM 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 AM configuration in the running ForgeRock Identity Platform to the staging area:

    $ cd /path/to/forgeops/bin
    $ ./config.sh export --component am
    
    Exporting AM configuration..
    
    
    AM configuration files have been exported to docker/7.0/am/config.+ docker run --rm --user 501:20 --volume /Users/shankar.raman/Repositories/forgeops/docker/7.0/am:/am-config --volume /Users/shankar.raman/Repositories/forgeops/config/am-upgrader-rules:/rules gcr.io/forgerock-io/am-config-upgrader/pit1:7.2.0-latest-postcommit
    Unable to find image 'gcr.io/forgerock-io/am-config-upgrader/pit1:7.2.0-latest-postcommit' locally
    7.2.0-latest-postcommit: Pulling from forgerock-io/am-config-upgrader/pit1
    b858e2d8875f: Already exists
    4d56c0553b50: Pull complete
    cc483403b1fa: Pull complete
    a6d79257700e: Pull complete
    22ec291d0766: Pull complete
    b1c5964e597f: Pull complete
    d4ac2bbcb1f5: Pull complete
    82b17ad1853e: Pull complete
    Digest: sha256:010eea1f29f99c821763b017404a3c74ba46a734073c184cff105f9eb96f05a9
    Status: Downloaded newer image for gcr.io/forgerock-io/am-config-upgrader/pit1:7.2.0-latest-postcommit
    
    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
    SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
    SLF4J: Defaulting to no-operation (NOP) logger implementation
    SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
    Writing configuration to new location at /am-config/config/services…​
    Upgrade Completed, modified configuration saved to /am-config/config/services

    The config.sh export --component am command copies AM static configuration from the running CDK instance to the staging area.

    Exporting the configuration from the CDK to the staging area.
  6. Review the differences between the files you exported to the staging area and files that you previously saved to your configuration profile.

    Use the config.sh diff command to review the changes. For example:

    $ ./config.sh diff --component am --profile my-profile
    diff  -u --recursive config/7.0/my-profile/am docker/7.0/am
    Only in docker/7.0/am/config/services/realm/root/authenticationtreesservice/1.0/organizationconfig/default: my-tree.json
    Only in docker/7.0/am: logback.xml
  7. Save the AM configuration to your configuration profile:

    $ ./config.sh save --component am --profile my-profile
    Saving AM configuration.

    The config.sh save --component am command copies AM static configuration from the staging area to your configuration profile.

    Saving the configuration to your configuration profile.
  8. Perform version control activities on your forgeops repository clone:

    1. Run the git status command.

    2. Review the state of the config directory.

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

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

    $ ./cdk build am
    Generating tags…​
     - am → am:32005dccf
    Checking cache…​
     - am: Not found. Building
    Starting build…​
    Found [minikube] context, using local docker daemon.
    Building [am]…​
    Sending build context to Docker daemon  1.989MB
    Step 1/15 : FROM gcr.io/forgerock-io/am-base:7.1.0
     --→ 4e0b979daa5c
    . . .
    Step 15/15 : ENTRYPOINT ["/home/forgerock/custom-entrypoint.sh"]
     --→ Running in 5f85c3a0f12a
     --→ 16e5e404830e
    Successfully built 16e5e404830e
    Successfully tagged am:32005dccf
    
    Updated the image_defaulter with your new image for am: "am:16e5e4048…​"

    The cdk build command calls Skaffold to build a new am Docker image, and to push the image to your Docker registry. It also updates the image defaulter file so that the next time you install AM, the cdk install command gets AM static configuration from your new custom Docker image.

    Building the new custom Docker image.
  10. Redeploy AM:

    1. Remove AM from your CDK installation:

      $ ./cdk delete am
      Uninstalling component(s): ['am']
      OK to delete these components? [Y/N] Y
      service "am" deleted
      deployment.apps "am" deleted
    2. Redeploy AM:

      $ ./cdk install am
      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): ['am']
      
      service/am created
      deployment.apps/am created
      
      Enjoy your deployment!
    3. 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.

  11. To validate that AM has the expected configuration:

    • 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 console and verify that your configuration changes are present.

Next Step

idm Image

The idm Docker image contains the IDM configuration.

Customization Overview
  • Customize IDM’s configuration data by using the Admin UI and the 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

Perform the following steps iteratively when developing a custom idm Docker image:

  1. If this is your first time building a custom Docker image, verify that you performed these setup activities, which are required for developers:

  2. Verify that:

    • The CDK is deployed.

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

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

    1. Run the git status command.

    2. Review the state of the config 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 the staging area:

    $ cd /path/to/forgeops/bin
    $ ./config.sh export --component idm
    Exporting IDM configuration…​
    
    tar: Removing leading `/' from member names
    
    IDM configuration files have been exported to docker/7.0/idm/config.

    The config.sh export --component idm command copies IDM static configuration from the running CDK instance to the staging area.

    Exporting the configuration from the CDK to the staging area.
  6. Review the differences between the files you exported to the staging area and files that you previously saved to your configuration profile.

    Use the config.sh diff command to review the changes. For example:

    $ ./config.sh diff --component idm --profile my-profile
    diff  -u --recursive config/7.0/my-profile/idm docker/7.0/idm
    diff -u --recursive -x '.' -x Dockerfile -x '.sh' config/7.0/my-profile/idm/conf/audit.json docker/7.0/idm/conf/audit.json
    --- config/7.0/my-profile/idm/conf/audit.json	2021-04-27 09:09:48.000000000 -0700
    + docker/7.0/idm/conf/audit.json	2021-04-27 09:10:13.000000000 -0700
    @@ -136,7 +136,7 @@
         "exceptionFormatter" : {
             "type" : "text/javascript",
             "globals" : {
    -            "some-string" : "old-value"
    +            "some-string" : "new-value"
             },
             "file" : "bin/defaults/script/audit/stacktraceFormatter.js"
         }
    Only in docker/7.0/idm: resolver
    Only in docker/7.0/idm: ui
  7. Save the IDM configuration to your configuration profile:

    $ ./config.sh save --component idm --profile my-profile
    Saving IDM configuration.

    The config.sh save --component idm command copies IDM static configuration from the staging area to your configuration profile.

    Saving the configuration to your configuration profile.
  8. Perform version control activities on your forgeops repository clone:

    1. Run the git status command.

    2. Review the state of the config directory.

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

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

    $ ./cdk build idm

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

    Building the new custom Docker image.
  10. Redeploy IDM:

    1. Remove IDM from your CDK installation:

      $ cd /path/to/forgeops/bin
      $ ./cdk delete idm
      OK to delete these components? [Y/N] Y
      configmap "idm" deleted
      configmap "idm-logging-properties" deleted
      service "idm" deleted
      deployment.apps "idm" deleted
    2. Redeploy IDM:

      $ ./cdk install idm
      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.

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

CDK Shutdown and Removal

When you’re done working with the CDK, shut it down and remove it from your namespace:

  1. If you’ve made changes to the AM and IDM configurations in the Git repository on the CDK that you want to save, sync the changes to your local forgeops repository clone. If you don’t sync the configurations before you run the cdk delete command, all the changes that you’ve made to the configurations will be lost.

    For more information on syncing changes to your local forgeops repository clone, see:

  2. Run the cdk delete command which deletes all CDK artifacts, including PVCs and the AM and IDM configurations in Git:

    $ cd /path/to/forgeops/bin
    $ ./cdk delete --namespace my-namespace

    Respond Y to the OK to delete? prompt.

Cloud Deployment Model Documentation

Deploy the CDM on GKE, Amazon EKS, or AKS to quickly spin up the platform for demonstration purposes. You’ll get a feel for what it’s like to deploy the platform on a Kubernetes cluster in the cloud. When you’re done, you won’t have a production-quality deployment. But you will have a robust, reference implementation of the ForgeRock Identity Platform.

About the Cloud Deployment Model

The ForgeRock Cloud Deployment Team has developed Docker images, Kustomize bases and overlays, Skaffold workflows, shell scripts, and other artifacts expressly to build the Cloud Deployment Model (CDM). The forgeops repository on GitHub contains the CDM artifacts you can use to deploy the ForgeRock Identity Platform in a cloud environment.

The CDM is a reference implementation for ForgeRock cloud deployments. You can get a sample ForgeRock Identity Platform deployment up and running in the cloud quickly using the CDM. After deploying the CDM, you can use it to explore how you might configure your Kubernetes cluster before you deploy the platform in production.

The CDM is a robust sample deployment for demonstration and exploration purposes only. It is not a production deployment.

This documentation describes how to use the CDM to stand up a Kubernetes cluster in the cloud that runs the ForgeRock Identity Platform, and then access the platform’s GUIs and REST APIs. When you’re done, you can use the CDM to explore deployment customizations:

Illustrates the major tasks performed to deploy the CDM.

Standing up a Kubernetes cluster and deploying the platform using the CDM is an activity you might want to perform as a learning and exploration exercise before you put together a project plan for deploying the platform in production. To better understand how this activity fits in to the overall deployment process, see Deploy the CDM.

Using the CDM artifacts and this documentation, you can quickly get the ForgeRock Identity Platform running in a Kubernetes cloud environment. You deploy the CDM to begin to familiarize yourself with some of the steps you’ll need to perform when deploying the platform in the cloud for production use. These steps include creating a cluster suitable for deploying the ForgeRock Identity Platform, installing the platform, and accessing its UIs and APIs.

Standardizes the process. The ForgeRock Cloud Deployment Team’s mission is to standardize a process for deploying ForgeRock Identity Platform natively in the cloud. The Team is made up of technical consultants and cloud software developers. We’ve had numerous interactions with ForgeRock customers, and discussed common deployment issues. Based on our interactions, we standardized on Kubernetes as the cloud platform, and we developed the CDM artifacts to make deployment of the platform easier in the cloud.

Simplifies baseline deployment. We then developed artifacts—Dockerfiles, Kustomize bases and overlays, Skaffold workflows, and shell scripts—to simplify the deployment process. We deployed small-sized, medium-sized, and large-sized production-quality Kubernetes clusters, and kept them up and running 24x7. We conducted continuous integration and continuous deployment as we added new capabilities and fixed problems in the system. We maintained, benchmarked, and tuned the system for optimized performance. Most importantly, we documented the process so you could replicate it.

Eliminates guesswork. If you use our CDM artifacts and follow the instructions in this documentation without deviation, you can successfully deploy the ForgeRock Identity Platform in the cloud. The CDM takes the guesswork out out of setting up a cloud environment. It bypasses the deploy-test-integrate-test-repeat cycle many customers struggle through when spinning up the ForgeRock Identity Platform in the cloud for the first time.

Prepares you to deploy in production. After you’ve deployed the CDM, you’ll be ready to start working with experts on deploying in production. We strongly recommend that you engage a ForgeRock technical consultant or partner to assist you with deploying the platform in production.

Next Step

CDM Architecture

Once you deploy the CDM, the ForgeRock Identity Platform is fully operational within a Kubernetes cluster. forgeops artifacts provide well-tuned JVM settings, memory, CPU limits, and other CDM configurations.

Here are some of the characteristics of the CDM:

Multi-zone Kubernetes cluster

ForgeRock Identity Platform is deployed in a Kubernetes cluster.

For high availability, CDM clusters are distributed across three zones.

Go here for a diagram that shows the organization of pods in zones and node pools in a CDM cluster.

Cluster sizes

Before deploying the CDM, you specify one of three cluster sizes:

  • A small cluster with capacity to handle 1,000,000 test users

  • A medium cluster with capacity to handle 10,000,000 test users

  • A large cluster with capacity to handle 100,000,000 test users

Third-party deployment and monitoring tools
Ready-to-use ForgeRock Identity Platform components
  • Multiple DS instances are deployed for higher availability. Separate instances are deployed for Core Token Service (CTS) tokens and identities. The instances for identities also contain AM and IDM run-time data.

  • The AM configuration is file-based, stored at the path /home/forgerock/openam/config inside the AM Docker container (and in the AM pods).

  • Multiple AM instances are deployed for higher availability. The AM instances are configured to access the DS data stores.

  • Multiple IDM instances are deployed for higher availability. The IDM instances are configured to access the DS data stores.

  • An RCS Agent instance lets IDM connectors communicate with the IDM instances in the CDM.

Highly available, distributed deployment

Deployment across the three zones ensures that the ingress controller and all ForgeRock Identity Platform components are highly available.

Pods that run DS are configured to use soft anti-affinity. Because of this, Kubernetes schedules DS pods to run on nodes that don’t have any other DS pods whenever possible.

The exact placement of all other CDM pods is delegated to Kubernetes.

In small and medium CDM clusters, pods are organized across three zones in a single primary node pool [11] with six nodes. Pod placement among the nodes might vary, but the DS pods should run on nodes without any other DS pods:

Small and medium CDM clusters have three zones and one node pool. The node pool has six nodes.

In large CDM clusters, pods are distributed across two node pools — primary [11] and DS. Each node pool has six nodes. Again, pod placement among the nodes might vary, but the DS pods should run on nodes without any other DS pods:

Large CDM clusters have three zones and two node pools. The node pools have six nodes each.
Load balancing

The NGINX Ingress Controller provides load balancing services for CDM deployments. Ingress controller pods run in the nginx namespace. Implementation varies by cloud provider.

Secret generation and management

ForgeRock’s open source Secret Agent operator generates Kubernetes secrets for ForgeRock Identity Platform deployments. It also integrates with Google Cloud Secret Manager, AWS Secrets Manager, and Azure Key Vault, providing cloud backup and retrieval for secrets.

Secured communication

The ingress controller is TLS-enabled. TLS is terminated at the ingress controller. Incoming requests and outgoing responses are encrypted.

Inbound communication to DS instances occurs over secure LDAP (LDAPS).

For more information, see Secure HTTP and Secure LDAP.

Stateful Sets

The CDM uses Kubernetes stateful sets to manage the DS pods. Stateful sets protect against data loss if Kubernetes client containers fail.

The CTS data stores are configured for affinity load balancing for optimal performance:

AM connections to CTS servers use token affinity in CDM.

The AM policies, application data, and identities reside in the idrepo directory service. The deployment uses a single idrepo master that can fail over to a secondary directory service:

For all the ${am.abbr} pods
Authentication

IDM is configured to use AM for authentication.

DS replication

All DS instances are configured for full replication of identities and session tokens.

Backup and restore

The CDM is ready to back up directory data, but backups are not scheduled by default. To schedule backups, see Backup and Restore.

You can enable the automatic restore capability in CDM to create new DS instances with data from the backup of another CDM deployment with the same DS topology.

Initial data loading jobs

When it starts up, the CDM runs two jobs to load data into the environment:

  • The amster job loads application data, such as OAuth 2.0 client definitions, to the idrepo DS instance.

  • The ldif-importer job primes the DS idrepo instance, which acts as the AM application and policy store, with required schema.

Next Step

Environment Setup: GKE

Before deploying the CDM, you must set up your local computer, configure a Google Cloud project, and create a GKE cluster.

Windows users

ForgeRock supports deploying the CDK and CDM using macOS and Linux. If you have a Windows computer, you’ll need to create a Linux VM. We tested using the following configurations:

  • Hypervisor: Hyper-V, VMWare Player, or VMWare Workstation

  • Guest OS: Ubuntu 19.10 with 12 GB memory and 60 GB disk space

  • Nested virtualization enabled in the Linux VM.

Perform all the procedures in this documentation within the Linux VM. In this documentation, the local computer refers to the Linux VM for Windows users.

The Minikube implementation on Windows Subsystem for Linux (WSL2) has networking issues. As a result, consistent access to the ingress controller or the apps deployed on Minikube is not possible. This issue is tracked here. Do not deploy CDK or CDM on WSL2 until this issue is resolved.

Third-Party Software

Before installing the CDM, you must obtain non-ForgeRock software and install it on your local computer.

ForgeRock recommends that you install third-party software using Homebrew on macOS and Linux[12] .

The versions listed in the following table have been validated for deploying the CDM on Google Cloud. Earlier and later versions will probably work. If you want to try using versions that are not in the tables, it is your responsibility to validate them.

Install the following third-party software:

Software Version Homebrew package

Python 3

3.9.6

python

Kubernetes client (kubectl)

1.21.2

kubectl

Kubernetes context switcher (kubectx)

0.9.3

kubectx

Kustomize

4.2.0

kustomize

Helm

3.6.3

helm

Google Cloud SDK

354.0.0

google-cloud-sdk (cask)[3]

Docker Desktop[13]

3.6.0

docker (cask)[3]

Skaffold

1.26.1

skaffold

Next Step

Google Cloud Project Setup

This page outlines the steps that the Cloud Deployment Team took when setting up a Google Cloud project before deploying the CDM.

Perform these steps before you deploy the CDM:

  1. Log in to the Google Cloud Console and create a new project.

  2. Authenticate to the Google Cloud SDK to obtain the permissions you’ll need to create a cluster:

    1. Configure the Google Cloud SDK standard component to use your Google account. Run the following command:

      $ gcloud auth login
    2. A browser window appears, prompting you to select a Google account. Select the account you want to use for cluster creation.

      A second screen requests several permissions. Select Allow.

      A third screen should appear with the heading, "You are now authenticated with the Google Cloud SDK!"

    3. Set the Google Cloud SDK configuration to reference your new project. Specify the project ID, not the project name, in the gcloud config set project command:

      $ gcloud config set project my-project-id
  3. Assign the following roles to users who will be creating Kubernetes clusters and deploying the CDM:

    • Editor

    • Kubernetes Engine Admin

    • Kubernetes Engine Cluster Admin

    Remember, the CDM is a reference implementation, and is not for production use. The roles you assign in this step are suitable for the CDM. When you create a project plan, you’ll need to determine which Google Cloud roles are required.

  4. Determine the region where you’ll deploy the CDM. Then, set that region as the default region in your Google Cloud SDK configuration. For example:

    $ gcloud config set compute/region us-west1
  5. Determine the cluster size: small, medium, or large.

  6. Ensure that the cluster creation script will support your region:

    1. Go to Google’s Regions and Zones page.

    2. Determine if the a, b, and c zones are available in your region.

      If these zones are available, no additional action needs to be taken.

      If they’re not available:

      1. Change to the /path/to/forgeops/cluster/gke directory.

      2. Open the script that sets environment variables for your selected cluster size. For example, open the small.sh script if you’re going to deploy a small-sized cluster.

      3. Locate the statement that sets the NODE_LOCATIONS environment variable.

      4. Uncomment this statement.

      5. Change the statement to configure CDM to use three zones available in your region.

      6. Save your changes to the script.

  7. Ensure that your region has an adequate CPU quota for the CDM:

    1. Change to the /path/to/forgeops/cluster/gke directory.

    2. Open the script that sets environment variables for your selected cluster size. For example, open the small.sh script if you’re going to deploy a small-sized cluster.

    3. Locate the statements that set the MACHINE and DS_MACHINE environment variables.

    4. Your quotas need to let you allocate six machines each of MACHINE and DS_MACHINE types in your region. If your quotas are too low, request and wait for a quota increase from Google Cloud before attempting to create your CDM cluster.

Next Step

forgeops Repository

Before you can deploy the CDK or the CDM, you must first get the forgeops repository and check out the release/7.1.0 branch:

  1. Clone the forgeops repository. For exmple:

    $ git clone https://github.com/ForgeRock/forgeops.git

    The forgeops repository is a public Git repository. You do not need credentials to clone it.

  2. Check out the release/7.1.0 branch:

    $ cd forgeops
    $ git checkout release/7.1.0

Depending on your organization’s repository strategy, you might need to clone the repository from a fork, instead of cloning ForgeRock’s master repository. You might also need to create a working branch from the release/7.1.0 branch. For more information, see Repository Updates.

Next Step

Kubernetes Cluster Creation

ForgeRock provides shell scripts based on the Google Cloud SDK to use for GKE cluster creation. Use them when you deploy the CDM. After you’ve finished deploying the CDM, you can use the CDM as a sandbox to explore a different infrastructure-as-code solution, if you like.

When you Create a Project Plan, you’ll need to identify your organization’s preferred infrastructure-as-code solution, and create your own cluster creation automation scripts, if necessary.

Here are the steps the Cloud Deployment Team followed to create a Kubernetes cluster on GKE:

  1. Create the cluster:

    1. Change to the directory that contains the cluster creation script:

      $ cd /path/to/forgeops/cluster/gke
    2. Source the script that contains the configuration for your cluster size. For example:

      $ source ./small.sh
    3. Run the cluster creation script[14]:

      $ ./cluster-up.sh

      If you’re prompted to install Google Cloud SDK beta components, enter Y to install them.

      The script creates:

      • The cluster

      • The ds-pool node pool (for large clusters only)

      • The fast storage class

      • The prod namespace

      • The cluster-admin-binding cluster role binding

    4. To verify that the script created the cluster, log in to the Google Cloud console. Select the Kubernetes Engine option. You should see the new cluster in the list of Kubernetes clusters.

    5. Run the kubectx command.

      The output should contain your newly created cluster and any existing clusters.

      The current context should be set to the context for your new cluster.

  2. Set context to the prod namespace:

    $ kubens prod
  3. Check the status of the pods in your cluster until all the pods are ready:

    1. List all the pods in the cluster:

      $ kubectl get pods --all-namespaces
      NAMESPACE                         NAME                                             READY   STATUS    RESTARTS   AGE
      cnrm-system                       cnrm-deletiondefender-0                          1/1     Running   0          6m52s
      cnrm-system                       cnrm-resource-stats-recorder-7cc75c4d59-tjwvx    2/2     Running   0          6m52s
      cnrm-system                       cnrm-webhook-manager-656ffb69d5-6d7cp            1/1     Running   0          6m52s
      configconnector-operator-system   configconnector-operator-0                       1/1     Running   0          7m46s
      kube-system                       event-exporter-gke-59b99fdd9c-qtvzw              2/2     Running   0          7m49s
      kube-system                       fluentbit-gke-dm42n                              2/2     Running   0          6m37s
      . . .
    2. Review the output. Deployment is complete when:

      • The READY column indicates all running containers are available. The entry in the READY column represents [total number of containers/number of available containers].

      • All entries in the STATUS column indicate Running or Completed.

    3. If necessary, continue to query your cluster’s status until all the pods are ready.

Next Step

Secret Agent Operator

Install ForgeRock’s Secret Agent operator before you deploy the CDM.

Remember, the CDM is a reference implementation and not for production use. When you create a project plan, you’ll need to determine how to manage secrets in production.

See Secret Agent Operator for further details on the Secret Agent operator.

After you’ve finished deploying the CDM, you can use the CDM as a sandbox to explore secret management options.

To install the Secret Agent operator in your cluster:

$ kubectl apply -f https://github.com/ForgeRock/secret-agent/releases/latest/download/secret-agent.yaml
namespace/secret-agent-system created
customresourcedefinition.apiextensions.k8s.io/secretagentconfigurations.secret-agent.secrets.forgerock.io created
mutatingwebhookconfiguration.admissionregistration.k8s.io/secret-agent-mutating-webhook-configuration created
serviceaccount/secret-agent-manager-service-account created
role.rbac.authorization.k8s.io/secret-agent-leader-election-role created
clusterrole.rbac.authorization.k8s.io/secret-agent-manager-role created
rolebinding.rbac.authorization.k8s.io/secret-agent-leader-election-rolebinding created
clusterrolebinding.rbac.authorization.k8s.io/secret-agent-manager-rolebinding created
service/secret-agent-webhook-service created
deployment.apps/secret-agent-controller-manager created
validatingwebhookconfiguration.admissionregistration.k8s.io/secret-agent-validating-webhook-configuration created
Next Step

NGINX Ingress Controller

Use the NGINX ingress controller when you deploy the CDM.

Remember, the CDM is a reference implementation and not for production use. When you create a project plan, you’ll need to determine which ingress controller to use in production.

After you’ve finished deploying the CDM, you can use the CDM as a sandbox to explore deployment with a different ingress controller.

To deploy an NGINX ingress controller in a GKE cluster:

  1. Verify that you initialized your cluster by performing the steps in Kubernetes Cluster Creation.

    If you did not set up your cluster using this technique, the cluster might be missing some required configuration.

  2. Deploy the NGINX ingress controller in your cluster:

    $ /path/to/forgeops/bin/ingress-controller-deploy.sh --gke
    Deploying Ingress Controller to GKE…​
    
    namespace/nginx created
    Detected cluster of type: small
    Setting ingress pod count to 1
    "ingress-nginx" has been added to your repositories
    Release "ingress-nginx" does not exist. Installing it now.
    NAME: ingress-nginx
    LAST DEPLOYED: Mon May 10 14:15:40 2021
    NAMESPACE: nginx
    STATUS: deployed
    REVISION: 1
    TEST SUITE: None
    . . .
  3. Check the status of the pods in the nginx namespace until all the pods are ready:

    $ kubectl get pods --namespace nginx
    NAME                                          READY  STATUS    RESTARTS  AGE
    ingress-nginx-controller-d794bb476-xxx6j      1/1    Running   0         4m38s
  4. Get the ingress controller’s external IP address:

    $ kubectl get services --namespace nginx
    NAME                                 TYPE           CLUSTER-IP   EXTERNAL-IP      PORT(S)                      AGE
    ingress-nginx-controller             LoadBalancer   10.4.6.154   35.203.145.112   80:30300/TCP,443:30638/TCP   58s
    ingress-nginx-controller-admission   ClusterIP      10.4.4.9     <none>           443/TCP                      58s

    The ingress controller’s IP address should appear in the EXTERNAL-IP column. There can be a short delay while the ingress starts before the IP address appears in the kubectl get services command’s output; you might need to run the command several times.

  5. Add an entry to the /etc/hosts file to resolve the deployment FQDN used by the platform UIs and APIs. For example:

    ingress-ip-address prod.iam.example.com

    For ingress-ip-address, specify the external IP address of the ingress controller service in the previous command.

Next Step

Certificate Manager

Use cert-manager when you deploy the CDM.

Remember, the CDM is a reference implementation and not for production use. When you create a project plan, you’ll need to determine how to manage certificates in production.

After you’ve finished deploying the CDM, you can use the CDM as a sandbox to explore deployment with a different certificate manager.

To deploy the Certificate Manager:

$ /path/to/forgeops/bin/certmanager-deploy.sh
customresourcedefinition.apiextensions.k8s.io/certificaterequests.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/certificates.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/challenges.acme.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/clusterissuers.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/issuers.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/orders.acme.cert-manager.io created
namespace/cert-manager created
serviceaccount/cert-manager-cainjector created
serviceaccount/cert-manager created
serviceaccount/cert-manager-webhook created
clusterrole.rbac.authorization.k8s.io/cert-manager-cainjector created
. . .
service/cert-manager created
service/cert-manager-webhook created
deployment.apps/cert-manager-cainjector created
deployment.apps/cert-manager created
deployment.apps/cert-manager-webhook created
mutatingwebhookconfiguration.admissionregistration.k8s.io/cert-manager-webhook created
validatingwebhookconfiguration.admissionregistration.k8s.io/cert-manager-webhook created
deployment.apps/cert-manager-webhook condition met
clusterissuer.cert-manager.io/default-issuer created
secret/certmanager-ca-secret created

After you’ve deployed the Certificate Manager, check the status of the pods in the cert-manager namespace until all the pods are ready:

$ kubectl get pods --namespace cert-manager
NAME                                              READY STATUS    RESTARTS AGE
cert-manager-6d5fd89bdf-khj5w                     1/1   Running   0        3m57s
cert-manager-cainjector-7d47d59998-h5b48          1/1   Running   0        3m57s
cert-manager-webhook-6559cc8549-8vdtp             1/1   Running   0        3m56s
Next Step

Prometheus, Grafana, and Alertmanager

Use Prometheus, Grafana, and Alertmanager when you deploy the CDM.

After you’ve finished deploying the CDM, you can use the CDM as a sandbox to explore deployment with a different monitoring and alerting framework.

Remember, the CDM is a reference implementation and not for production use. When you create a project plan, you’ll need to determine how to monitor and send alerts in your production deployment.

To deploy Prometheus, Grafana, and Alertmanager:

  1. Deploy Prometheus, Grafana, and Alertmanager in your cluster:

    $ /path/to/forgeops/bin/prometheus-deploy.sh
    
    This script requires Helm version 3.04 or later due to changes in the behaviour of 'helm repo add' command.
    
    namespace/monitoring created
    "stable" has been added to your repositories
    "prometheus-community" has been added to your repositories
    Hang tight while we grab the latest from your chart repositories…​
    …​Successfully got an update from the "ingress-nginx" chart repository
    …​Successfully got an update from the "codecentric" chart repository
    …​Successfully got an update from the "prometheus-community" chart repository
    …​Successfully got an update from the "stable" chart repository
    Update Complete. ⎈Happy Helming!⎈
    Release "prometheus-operator" does not exist. Installing it now.
    NAME: prometheus-operator
    LAST DEPLOYED: . . .
    NAMESPACE: monitoring
    STATUS: deployed
    REVISION: 1
    NOTES:
    kube-prometheus-stack has been installed. Check its status by running:
      kubectl --namespace monitoring get pods -l "release=prometheus-operator"
    
    Visit https://github.com/prometheus-operator/kube-prometheus for instructions on how to create & configure Alertmanager and Prometheus instances using the Operator.
    . . .
    Release "forgerock-metrics" does not exist. Installing it now.
    NAME: forgerock-metrics
    LAST DEPLOYED: . . .
    NAMESPACE: monitoring
    STATUS: deployed
    REVISION: 1
    TEST SUITE: None
  2. Check the status of the pods in the monitoring namespace until all the pods are ready:

    $ kubectl get pods --namespace monitoring
    NAME                                                     READY   STATUS    RESTARTS   AGE
    alertmanager-prometheus-operator-kube-p-alertmanager-0   2/2     Running   0          2m49s
    prometheus-operator-grafana-7fb6687584-g7mll             2/2     Running   0          2m55s
    prometheus-operator-kube-p-operator-648f6dc47f-qsdkl     1/1     Running   0          2m55s
    prometheus-operator-kube-state-metrics-957fc5f95-jwvdz   1/1     Running   0          2m55s
    prometheus-operator-prometheus-node-exporter-dd4vz       1/1     Running   0          2m55s
    prometheus-operator-prometheus-node-exporter-dtblt       1/1     Running   0          2m56s
    prometheus-operator-prometheus-node-exporter-jvlj5       1/1     Running   0          2m55s
    prometheus-prometheus-operator-kube-p-prometheus-0       2/2     Running   1          2m49s
Next Step

docker push Setup

In the deployment environment you’re setting up, Skaffold builds Docker images using the Docker software you’ve installed on your local computer. After it builds the images, Skaffold pushes them to a Docker registry available to your GKE cluster. With the images on the remote Docker registry, Skaffold can orchestrate the ForgeRock Identity Platform, creating containers from the Docker images.

For Skaffold to be able to push the Docker images:

  • Docker must be running on your local computer.

  • Your local computer needs credentials that let Skaffold push the images to the Docker registry available to your cluster.

  • Skaffold needs to know the location of the Docker registry.

Perform the following steps to let Skaffold to push Docker images to a registry accessible to your cluster:

  1. If it’s not already running, start Docker on your local computer. For more information, see the Docker documentation.

  2. Set up a Docker credential helper:

    $ gcloud auth configure-docker
  3. Run the kubectx command to obtain the Kubernetes context.

  4. Configure Skaffold with the Docker registry location for your project and the Kubernetes context. Use your project ID (not your project name) and the Kubernetes context that you obtained in the previous step:

    $ skaffold config set default-repo gcr.io/my-project-ID -k my-kubernetes-context
Next Step

You’ve completed all the setup tasks for GKE. Now you’re ready to deploy the platform in your new cluster:

Environment Setup: EKS

Before deploying the CDM, you must set up your local computer, configure your AWS account, and create an EKS cluster.

Windows users

ForgeRock supports deploying the CDK and CDM using macOS and Linux. If you have a Windows computer, you’ll need to create a Linux VM. We tested using the following configurations:

  • Hypervisor: Hyper-V, VMWare Player, or VMWare Workstation

  • Guest OS: Ubuntu 19.10 with 12 GB memory and 60 GB disk space

  • Nested virtualization enabled in the Linux VM.

Perform all the procedures in this documentation within the Linux VM. In this documentation, the local computer refers to the Linux VM for Windows users.

The Minikube implementation on Windows Subsystem for Linux (WSL2) has networking issues. As a result, consistent access to the ingress controller or the apps deployed on Minikube is not possible. This issue is tracked here. Do not deploy CDK or CDM on WSL2 until this issue is resolved.

Architecture Overview

The following diagram provides an overview of a CDM deployment in the Amazon EKS environment:

CDM cluster uses two subnets and contains two worker nodes.
  • An AWS stack template is used to create a virtual private cloud (VPC).

  • Three subnets are configured across three availability zones.

  • A Kubernetes cluster is created over the three subnets.

  • Three worker nodes are created within the cluster. The worker nodes contain the computing infrastructure to run the CDM components.

  • A local file system is mounted to the DS pod for storing directory data backup.

Next Step

Third-Party Software

Before installing the CDM, you must obtain non-ForgeRock software and install it on your local computer.

ForgeRock recommends that you install third-party software using Homebrew on macOS and Linux[15] .

The versions listed in the following table have been validated for deploying the CDM on Amazon Web Services. Earlier and later versions will probably work. If you want to try using versions that are not in the tables, it is your responsibility to validate them.

Install the following third-party software:

Software Version Homebrew package

Python 3

3.9.6

python

Kubernetes client (kubectl)

1.21.2

kubectl

Kubernetes context switcher (kubectx)

0.9.3

kubectx

Kustomize

4.2.0

kustomize

Helm

3.6.3

helm

Amazon AWS Command Line Interface

2.2.13

awscli

AWS IAM Authenticator for Kubernetes

0.5.3

aws-iam-authenticator

eksctl

0.54.0

eksctl

Docker Desktop[16]

3.6.0

docker (cask)[3]

Skaffold

1.26.1

skaffold

Next Step

AWS Environment Setup

This page outlines the steps that the Cloud Deployment Team took when setting up AWS before deploying the CDM.

Perform these steps before you deploy the CDM:

  1. Create and configure an IAM group:

    1. Create a group with the name cdm-users.

    2. Attach the following AWS preconfigured policies to the cdm-users group:

      • IAMUserChangePassword

      • IAMReadOnlyAccess

      • AmazonEC2FullAccess

      • AmazonEC2ContainerRegistryFullAccess

      • AWSCloudFormationFullAccess

    3. Create two policies in the IAM service of your AWS account:

      1. Create the EksAllAccess policy using the eks-all-access.json file in the /path/to/forgeops/etc/aws-example-iam-policies directory.

      2. Create the IamLimitedAccess policy using the iam-limited-access.json file in the /path/to/forgeops/etc/aws-example-iam-policies directory.

    4. Attach the policies you created to the cdm-users group.

      Remember, the CDM is a reference implementation and is not for production use. The policies you create in this procedure are suitable for the CDM. When you create a project plan, you’ll need to determine how to configure AWS permissions.

    5. Assign one or more AWS users who will set up CDM to the cdm-users group.

  2. If you haven’t already done so, set up your aws command-line interface environment using the aws configure command.

  3. Verify that your AWS user is a member of the cdm-users group:

    $ aws iam list-groups-for-user --user-name my-user-name --output json
    {
        "Groups": [
            {
                "Path": "/",
                "GroupName": "cdm-users",
                "GroupId": "ABCDEFGHIJKLMNOPQRST",
                "Arn": "arn:aws:iam::048497731163:group/cdm-users",
                "CreateDate": "2020-03-11T21:03:17+00:00"
            }
        ]
    }
  4. Verify that you are using the correct user profile:

    $ aws iam get-user
    {
        "User": {
            "Path": "/",
            "UserName": "my-test-user",
            "UserId": ". . .",
            "Arn": "arn:aws:iam::01. . .3:user/my-test-user",
            "CreateDate": "2020-09-17T16:01:46+00:00",
            "PasswordLastUsed": "2021-05-10T17:07:53+00:00"
        }
    }
  5. Determine the region where you’ll deploy the CDM. Then, configure that region as your default AWS region. For example:

    $ aws configure set default.region us-east-1

    Note the following:

    • The region must support Amazon EKS.

    • The region must have at least three availability zones. (Use the aws ec2 describe-availability-zones --region region-name command to determine the availability zones for an AWS region.)

    • Objects required for your EKS cluster should reside in the same region to get the best performance. To make sure that AWS objects are created in the correct region, be sure to set your default region as shown above.

  6. Determine your cluster size: small, medium, or large.

  7. Ensure that the cluster creation script will support your region:

    1. Change to the /path/to/forgeops/cluster/eks directory.

    2. Open the configuration file for your selected cluster size. For example, open the small.yaml file if you’re going to deploy a small-sized cluster.

    3. Specify your region as the metadata/region value.

    4. Specify the three availability zones in your region as the availabilityZones values.

  8. Ensure that your region has an adequate CPU quota for the CDM:

    1. Change to the /path/to/forgeops/cluster/eks directory.

    2. Open the YAML file that contains the configuration for your selected cluster size. For example, open the small.yaml file if you’re going to deploy a small-sized cluster.

    3. Locate the two instanceType statements in the nodeGroups section.

    4. Your quotas need to let you allocate six machines of each type in your region. If your quotas are too low, request and wait for a quota increase from AWS before attempting to create your CDM cluster.

  9. Create Amazon ECR repositories for the ForgeRock Identity Platform Docker images:

    $ for i in am am-config-upgrader amster ds-cts ds-idrepo idm ldif-importer ig ds-proxy rcs-agent;
    do
      aws ecr create-repository --repository-name "forgeops/${i}";
    done
    
    {
        "repository": {
            "repositoryArn": "arn:aws:ecr:us-east-1:. . .:repository/forgeops/am",
            "registryId": ". . .",
            "repositoryName": "forgeops/am",
            "repositoryUri": ". . . .dkr.ecr.us-east-1.amazonaws.com/forgeops/am",
            "createdAt": "2020-08-03T14:19:54-08:00"
        }
    }
    . . .
Next Step

forgeops Repository

Before you can deploy the CDK or the CDM, you must first get the forgeops repository and check out the release/7.1.0 branch:

  1. Clone the forgeops repository. For exmple:

    $ git clone https://github.com/ForgeRock/forgeops.git

    The forgeops repository is a public Git repository. You do not need credentials to clone it.

  2. Check out the release/7.1.0 branch:

    $ cd forgeops
    $ git checkout release/7.1.0

Depending on your organization’s repository strategy, you might need to clone the repository from a fork, instead of cloning ForgeRock’s master repository. You might also need to create a working branch from the release/7.1.0 branch. For more information, see Repository Updates.

Next Step

Kubernetes Cluster Creation

ForgeRock provides shell scripts based on AWS CloudFormation to use for EKS cluster creation. Use them when you deploy the CDM. After you’ve finished deploying the CDM, you can use the CDM as a sandbox to explore a different infrastructure-as-code solution, if you like.

When you Create a Project Plan, you’ll need to identify your organization’s preferred infrastructure-as-code solution, and create your own cluster creation automation scripts, if necessary.

Here are the steps the Cloud Deployment Team followed to create a Kubernetes cluster on EKS:

  1. Create your cluster:

    1. Change to the directory that contains the cluster creation script:

      $ cd /path/to/forgeops/cluster/eks
    2. Run the cluster creation script. Specify the YAML file that contains the configuration for your cluster size. For example[17]:

      $ ./cluster-up.sh small.yaml

      To verify that the cluster has been created, log in to the AWS console. Select the EKS service link. You should see the new cluster in the list of Amazon EKS clusters.

    3. Run the kubectx command:

      $ kubectx
      . . .
      user.name@small.us-east-1.eksctl.io

      The output should contain your newly created cluster and any existing clusters.

      The current context should be set to the context for your new cluster.

  2. Set context to the prod namespace:

    $ kubens prod
  3. Check the status of the pods in your cluster until all the pods are ready:

    1. List all the pods in the cluster:

      $ kubectl get pods --all-namespaces
      NAMESPACE     NAME                              READY   STATUS    RESTARTS   AGE
      kube-system   aws-node-4fzmz                    1/1     Running   0          9m28s
      kube-system   aws-node-btkf9                    1/1     Running   0          9m23s
      kube-system   aws-node-gbw6b                    1/1     Running   0          9m3s
      kube-system   aws-node-gtp2x                    1/1     Running   0          9m1s
      kube-system   aws-node-klv4t                    1/1     Running   0          9m28s
      kube-system   aws-node-znjt6                    1/1     Running   0          9m4s
      kube-system   coredns-75b44cb5b4-nm824          1/1     Running   0          25m
      kube-system   coredns-75b44cb5b4-xlwpn          1/1     Running   0          25m
      kube-system   kube-proxy-4gxgw                  1/1     Running   0          9m3s
      kube-system   kube-proxy-bb4sr                  1/1     Running   0          9m28s
      kube-system   kube-proxy-knw77                  1/1     Running   0          9m28s
      kube-system   kube-proxy-kwq22                  1/1     Running   0          9m1s
      kube-system   kube-proxy-ptpnf                  1/1     Running   0          9m23s
      kube-system   kube-proxy-zt4t2                  1/1     Running   0          9m4s
      kube-system   metrics-server-5f956b6d5f-nhpmd   1/1     Running   0          12m8s
    2. Review the output. Deployment is complete when:

      • The READY column indicates all running containers are available. The entry in the READY column represents [total number of containers/number of available containers].

      • All entries in the STATUS column indicate Running or Completed.

    3. If necessary, continue to query your cluster’s status until all the pods are ready.

Next Step

Secret Agent Operator

Install ForgeRock’s Secret Agent operator before you deploy the CDM.

Remember, the CDM is a reference implementation and not for production use. When you create a project plan, you’ll need to determine how to manage secrets in production.

See Secret Agent Operator for further details on the Secret Agent operator.

After you’ve finished deploying the CDM, you can use the CDM as a sandbox to explore secret management options.

To install the Secret Agent operator in your cluster:

$ kubectl apply -f https://github.com/ForgeRock/secret-agent/releases/latest/download/secret-agent.yaml
namespace/secret-agent-system created
customresourcedefinition.apiextensions.k8s.io/secretagentconfigurations.secret-agent.secrets.forgerock.io created
mutatingwebhookconfiguration.admissionregistration.k8s.io/secret-agent-mutating-webhook-configuration created
serviceaccount/secret-agent-manager-service-account created
role.rbac.authorization.k8s.io/secret-agent-leader-election-role created
clusterrole.rbac.authorization.k8s.io/secret-agent-manager-role created
rolebinding.rbac.authorization.k8s.io/secret-agent-leader-election-rolebinding created
clusterrolebinding.rbac.authorization.k8s.io/secret-agent-manager-rolebinding created
service/secret-agent-webhook-service created
deployment.apps/secret-agent-controller-manager created
validatingwebhookconfiguration.admissionregistration.k8s.io/secret-agent-validating-webhook-configuration created
Next Step

NGINX Ingress Controller

Use the NGINX ingress controller when you deploy the CDM.

Remember, the CDM is a reference implementation and not for production use. When you create a project plan, you’ll need to determine which ingress controller to use in production.

After you’ve finished deploying the CDM, you can use the CDM as a sandbox to explore deployment with a different ingress controller.

To deploy an NGINX ingress controller in an EKS cluster:

  1. Verify that you initialized your cluster by performing the steps in Kubernetes Cluster Creation.

    If you did not set up your cluster using this technique, the cluster might be missing some required configuration.

  2. Deploy the NGINX ingress controller in your cluster:

    $ /path/to/forgeops/bin/ingress-controller-deploy.sh --eks
    Deploying Ingress Controller to EKS…​
    
    namespace/nginx created
    Detected cluster of type: cdm-small
    Setting ingress pod count to 2
    "ingress-nginx" has been added to your repositories
    Release "ingress-nginx" does not exist. Installing it now.
    NAME: ingress-nginx
    LAST DEPLOYED: Tue May 11 16:18:32 2021
    NAMESPACE: nginx
    STATUS: deployed
    REVISION: 1
    TEST SUITE: None
    NOTES:
    . . .
  3. Check the status of the pods in the nginx namespace until all the pods are ready:

    $ kubectl get pods --namespace nginx
    NAME                                       READY   STATUS    RESTARTS   AGE
    ingress-nginx-controller-bb566bf7b-c9kmk   1/1     Running   0          2m45s
    ingress-nginx-controller-bb566bf7b-l6dz6   1/1     Running   0          2m45s
  4. Obtain the DNS name (shown under the EXTERNAL-IP column) of the load balancer :

    $ kubectl get services --namespace nginx
    NAME                                 TYPE           CLUSTER-IP     EXTERNAL-IP                                    PORT(S)                      AGE
    ingress-nginx-controller             LoadBalancer   10.100.43.88   ac5f2939. . .ca4.elb.us-east-1.amazonaws.com   80:30005/TCP,443:30770/TCP   62s
    ingress-nginx-controller-admission   ClusterIP      10.100.2.215   <none>                                         443/TCP                      62s
  5. Wait for a couple of minutes for the load balancer to be assigned the external IP address. Then, get the external IP addresses of the load balancer. For example:

    $ host ac5f2939. . .42d085.elb.us-east-1.amazonaws.com
    ac5f2939. . .42d085.elb.us-east-1.amazonaws.com has address 3.210.123.210

    The host command returns several IP addresses. You can use any of the IP addresses when you modify your local hosts file in the next step for evaluation purposes. You must create an appropriate entry in your DNS servers for production deployments.

  6. Add an entry to the /etc/hosts file to resolve the deployment FQDN used by the platform UIs and APIs. For example:

    ingress-ip-address prod.iam.example.com

    For ingress-ip-address, specify the external IP of the ingress controller service in the previous command.

Next Step

Certificate Manager

Use cert-manager when you deploy the CDM.

Remember, the CDM is a reference implementation and not for production use. When you create a project plan, you’ll need to determine how to manage certificates in production.

After you’ve finished deploying the CDM, you can use the CDM as a sandbox to explore deployment with a different certificate manager.

To deploy the Certificate Manager:

$ /path/to/forgeops/bin/certmanager-deploy.sh

customresourcedefinition.apiextensions.k8s.io/certificaterequests.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/certificates.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/challenges.acme.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/clusterissuers.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/issuers.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/orders.acme.cert-manager.io created
namespace/cert-manager created
serviceaccount/cert-manager-cainjector created
serviceaccount/cert-manager created
serviceaccount/cert-manager-webhook created
clusterrole.rbac.authorization.k8s.io/cert-manager-cainjector created
. . .
service/cert-manager created
service/cert-manager-webhook created
deployment.apps/cert-manager-cainjector created
deployment.apps/cert-manager created
deployment.apps/cert-manager-webhook created
mutatingwebhookconfiguration.admissionregistration.k8s.io/cert-manager-webhook created
validatingwebhookconfiguration.admissionregistration.k8s.io/cert-manager-webhook created
deployment.extensions/cert-manager-webhook condition met
clusterissuer.cert-manager.io/default-issuer created
secret/certmanager-ca-secret created

After you’ve deployed the Certificate Manager, check the status of the pods in the cert-manager namespace until all the pods are ready:

$ kubectl get pods --namespace cert-manager

NAME                                              READY STATUS    RESTARTS AGE
cert-manager-6d5fd89bdf-khj5w                     1/1   Running   0        3m57s
cert-manager-cainjector-7d47d59998-h5b48          1/1   Running   0        3m57s
cert-manager-webhook-6559cc8549-8vdtp             1/1   Running   0        3m56s
Next Step

Prometheus, Grafana, and Alertmanager

Use Prometheus, Grafana, and Alertmanager when you deploy the CDM.

After you’ve finished deploying the CDM, you can use the CDM as a sandbox to explore deployment with a different monitoring and alerting framework.

Remember, the CDM is a reference implementation and not for production use. When you create a project plan, you’ll need to determine how to monitor and send alerts in your production deployment.

To deploy Prometheus, Grafana, and Alertmanager:

  1. Deploy Prometheus, Grafana, and Alertmanager in your cluster:

    $ /path/to/forgeops/bin/prometheus-deploy.sh
    
    This script requires Helm version 3.04 or later due to changes in the behaviour of 'helm repo add' command.
    
    namespace/monitoring created
    "stable" has been added to your repositories
    "prometheus-community" has been added to your repositories
    Hang tight while we grab the latest from your chart repositories…​
    …​Successfully got an update from the "ingress-nginx" chart repository
    …​Successfully got an update from the "codecentric" chart repository
    …​Successfully got an update from the "prometheus-community" chart repository
    …​Successfully got an update from the "stable" chart repository
    Update Complete. ⎈Happy Helming!⎈
    Release "prometheus-operator" does not exist. Installing it now.
    NAME: prometheus-operator
    LAST DEPLOYED: . . .
    NAMESPACE: monitoring
    STATUS: deployed
    REVISION: 1
    NOTES:
    . . .
    pod/prometheus-operator-prometheus-node-exporter-klgw2 condition met
    pod/prometheus-operator-prometheus-node-exporter-nv2jn condition met
    pod/prometheus-prometheus-operator-kube-p-prometheus-0 condition met
    Release "forgerock-metrics" does not exist. Installing it now.
    NAME: forgerock-metrics
    LAST DEPLOYED: . . .
    NAMESPACE: monitoring
    STATUS: deployed
    REVISION: 1
    TEST SUITE: None
  2. Check the status of the pods in the monitoring namespace until all the pods are ready:

    $ kubectl get pods --namespace monitoring
    NAME                                                     READY   STATUS    RESTARTS   AGE
    alertmanager-prometheus-operator-kube-p-alertmanager-0   2/2     Running   0          6m20s
    prometheus-operator-grafana-5c7677f88b-jzd22             2/2     Running   0          6m24s
    prometheus-operator-kube-p-operator-58cbbf67b5-4lchb     1/1     Running   0          2m1s
    prometheus-operator-kube-state-metrics-957fc5f95-fdvgz   1/1     Running   0          6m24s
    prometheus-operator-prometheus-node-exporter-6prrn       1/1     Running   0          6m24s
    prometheus-operator-prometheus-node-exporter-6wr4b       1/1     Running   0          6m24s
    prometheus-operator-prometheus-node-exporter-9qmtw       1/1     Running   0          95s
    prometheus-operator-prometheus-node-exporter-g4p7f       1/1     Running   0          110s
    prometheus-operator-prometheus-node-exporter-hjf28       1/1     Running   0          6m24s
    prometheus-operator-prometheus-node-exporter-nv2jn       1/1     Running   0          6m24s
    prometheus-prometheus-operator-kube-p-prometheus-0       2/2     Running   1          2m1s
Next Step

docker push Setup

In the deployment environment you’re setting up, Skaffold builds Docker images using the Docker software you’ve installed on your local computer. After it builds the images, Skaffold pushes them to a Docker registry available to your Amazon EKS cluster. With the images on the remote Docker registry, Skaffold can orchestrate the ForgeRock Identity Platform, creating containers from the Docker images.

For Skaffold to be able to push the Docker images:

  • Docker must be running on your local computer.

  • Your local computer needs credentials that let Skaffold push the images to the Docker registry available to the shared cluster.

  • Skaffold needs to know the location of the Docker registry.

Perform the following steps to let Skaffold to push Docker images to a registry accessible to your cluster:

  1. If it’s not already running, start Docker on your local computer. For more information, see the Docker documentation.

  2. Obtain your 12 digit AWS account ID. You’ll need it when you run subsequent steps in this procedure.

  3. Log in to Amazon ECR:

    $ aws ecr get-login-password | docker login --username AWS  \
     --password-stdin my-account-id.dkr.ecr.my-region.amazonaws.com
    Login Succeeded

    ECR login sessions expire after 12 hours. Because of this, you’ll need to log in again whenever your login session expires [18].

  4. Run the kubectx command to obtain the Kubernetes context.

  5. Configure Skaffold with your Docker registry location and the Kubernetes context:

    $ skaffold config \
     set default-repo my-account-id.dkr.ecr.my-region.amazonaws.com/forgeops \
     -k my-kubernetes-context
    set value default-repo to my-account-id.dkr.ecr.my-region.amazonaws.com/forgeops
    for context my-kubernetes-context
Next Step

You’ve completed all the setup tasks for EKS. Now you’re ready to deploy the platform in your new cluster:

Environment Setup: AKS

Before deploying the CDM, you must set up your local computer, configure an Azure subscription, and create a AKS cluster.

Windows users

ForgeRock supports deploying the CDK and CDM using macOS and Linux. If you have a Windows computer, you’ll need to create a Linux VM. We tested using the following configurations:

  • Hypervisor: Hyper-V, VMWare Player, or VMWare Workstation

  • Guest OS: Ubuntu 19.10 with 12 GB memory and 60 GB disk space

  • Nested virtualization enabled in the Linux VM.

Perform all the procedures in this documentation within the Linux VM. In this documentation, the local computer refers to the Linux VM for Windows users.

The Minikube implementation on Windows Subsystem for Linux (WSL2) has networking issues. As a result, consistent access to the ingress controller or the apps deployed on Minikube is not possible. This issue is tracked here. Do not deploy CDK or CDM on WSL2 until this issue is resolved.

Third-Party Software

Before installing the CDM, you must obtain non-ForgeRock software and install it on your local computer.

ForgeRock recommends that you install third-party software using Homebrew on macOS and Linux[19] .

The versions listed in the following table have been validated for deploying the CDM on Microsoft Azure. Earlier and later versions will probably work. If you want to try using versions that are not in the tables, it is your responsibility to validate them.

Install the following third-party software:

Software Version Homebrew package

Python 3

3.9.6

python

Kubernetes client (kubectl)

1.21.2

kubectl

Kubernetes context switcher (kubectx)

0.9.3

kubectx

Kustomize

4.2.0

kustomize

Helm

3.6.3

helm

Azure Command Line Interface

2.25.0

azure-cli

Docker Desktop[20]

3.6.0

docker (cask)[3]

Skaffold

1.26.1

skaffold

Next Step

Azure Subscription Setup

This page outlines the steps that the Cloud Deployment Team took when setting up an Azure subscription before deploying the CDM.

Perform these steps before you deploy the CDM:

  1. Assign the following roles to users who will deploy the CDM:

    • Azure Kubernetes Service Cluster Admin Role

    • Azure Kubernetes Service Cluster User Role

    • Contributor

    • User Access Administrator

    Remember, the CDM is a reference implementation, and is not for production use. The roles you assign in this step are suitable for the CDM. When you create a project plan, you’ll need to determine which Azure roles are required.

  2. Log in to Azure services as a user with the roles you assigned in the previous step:

    $ az login --username my-user-name
  3. View your current subscription ID:

    $ az account show
  4. If necessary, set the current subscription ID to the one you will use to deploy the CDM:

    $ az account set --subscription my-subscription-id
  5. Determine the region where you’ll deploy the CDM. Then, set that region as the default location for the Azure CLI. For example:

    $ az configure --defaults location=westus2

    When changing the region for deploying the CDM:

    • The region must support AKS.

    • The subscription, resource groups, and resources you create for your AKS cluster must reside in the same region.

  6. Determine the cluster size: small, medium, or large.

  7. Ensure that your region has an adequate CPU quota for the CDM:

    1. Change to the /path/to/forgeops/cluster/aks directory.

    2. Open the script that sets environment variables for your selected cluster size. For example, open the small.sh script if you’re going to deploy a small-sized cluster.

    3. Locate the statements that set the VM_SIZE and DS_VM_SIZE environment variables.

    4. Your quotas need to let you allocate six machines of each type in your region. If your quotas are too low, request and wait for a quota increase from Microsoft before attempting to create your CDM cluster.

  8. The CDM uses Azure Container Registry (ACR) for storing Docker images.

    If you do not have a container registry in your subscription, create one.

Next Step

forgeops Repository

Before you can deploy the CDK or the CDM, you must first get the forgeops repository and check out the release/7.1.0 branch:

  1. Clone the forgeops repository. For exmple:

    $ git clone https://github.com/ForgeRock/forgeops.git

    The forgeops repository is a public Git repository. You do not need credentials to clone it.

  2. Check out the release/7.1.0 branch:

    $ cd forgeops
    $ git checkout release/7.1.0

Depending on your organization’s repository strategy, you might need to clone the repository from a fork, instead of cloning ForgeRock’s master repository. You might also need to create a working branch from the release/7.1.0 branch. For more information, see Repository Updates.

Next Step

Kubernetes Cluster Creation

ForgeRock provides shell scripts based on the Azure CLI to use for AKS cluster creation. Use them when you deploy the CDM. After you’ve finished deploying the CDM, you can use the CDM as a sandbox to explore a different infrastructure-as-code solution, if you like.

When you Create a Project Plan, you’ll need to identify your organization’s preferred infrastructure-as-code solution, and create your own cluster creation automation scripts, if necessary.

Here are the steps the Cloud Deployment Team followed to create a Kubernetes cluster on AKS:

  1. Set the value of the ACR_NAME environment variable to the name of your ACS container registry. For example, my-container-registry, not my-container-registry.azurecr.io:

    $ export ACR_NAME=my-container-registry
  2. Create the cluster:

    1. Change to the directory that contains the cluster creation script:

      $ cd /path/to/forgeops/cluster/aks
    2. Source the script that contains the configuration for your cluster size. For example:

      $ source ./small.sh
    3. Run the cluster creation script[21]:

      $ ./cluster-up.sh

      The script creates:

      • The cluster

      • The DS node pool (for large clusters only)

      • The fast storage class

      • The prod namespace

      • A public static IP address

    4. To verify that the script created the cluster, log in to the Azure portal. Select the Kubernetes Engine option. You should see the new cluster in the list of Kubernetes clusters.

    5. Run the kubectx command.

      The output should contain your newly created cluster and any existing clusters.

      The current context should be set to the context for your new cluster.

  3. Check the status of the pods in your cluster until all the pods are ready:

    1. List all the pods in the cluster:

      $ kubectl get pods --all-namespaces
      NAMESPACE     NAME                                         READY   STATUS    RESTARTS   AGE
      kube-system   azure-cni-networkmonitor-7jhxs               1/1     Running   0          22m
      kube-system   azure-cni-networkmonitor-7js4b               1/1     Running   0          20m
      . . .
      kube-system   azure-ip-masq-agent-2vdnb                    1/1     Running   0          22m
      . . .
    2. Review the output. Deployment is complete when:

      • The READY column indicates all running containers are available. The entry in the READY column represents [total number of containers/number of available containers].

      • All entries in the STATUS column indicate Running or Completed.

    3. If necessary, continue to query your cluster’s status until all the pods are ready.

Next Step

Secret Agent Operator

Install ForgeRock’s Secret Agent operator before you deploy the CDM.

Remember, the CDM is a reference implementation and not for production use. When you create a project plan, you’ll need to determine how to manage secrets in production.

See Secret Agent Operator for further details on the Secret Agent operator.

After you’ve finished deploying the CDM, you can use the CDM as a sandbox to explore secret management options.

To install the Secret Agent operator in your cluster:

$ kubectl apply -f https://github.com/ForgeRock/secret-agent/releases/latest/download/secret-agent.yaml
namespace/secret-agent-system created
customresourcedefinition.apiextensions.k8s.io/secretagentconfigurations.secret-agent.secrets.forgerock.io created
mutatingwebhookconfiguration.admissionregistration.k8s.io/secret-agent-mutating-webhook-configuration created
serviceaccount/secret-agent-manager-service-account created
role.rbac.authorization.k8s.io/secret-agent-leader-election-role created
clusterrole.rbac.authorization.k8s.io/secret-agent-manager-role created
rolebinding.rbac.authorization.k8s.io/secret-agent-leader-election-rolebinding created
clusterrolebinding.rbac.authorization.k8s.io/secret-agent-manager-rolebinding created
service/secret-agent-webhook-service created
deployment.apps/secret-agent-controller-manager created
validatingwebhookconfiguration.admissionregistration.k8s.io/secret-agent-validating-webhook-configuration created
Next Step

NGINX Ingress Controller

Use the NGINX ingress controller when you deploy the CDM.

Remember, the CDM is a reference implementation and not for production use. When you create a project plan, you’ll need to determine which ingress controller to use in production.

After you’ve finished deploying the CDM, you can use the CDM as a sandbox to explore deployment with a different ingress controller.

To deploy an NGINX ingress controller in an AKS cluster:

  1. Verify that you initialized your cluster by performing the steps in Kubernetes Cluster Creation.

    If you did not set up your cluster using this technique, the cluster might be missing some required configuration.

  2. Deploy the NGINX ingress controller in your cluster:

    $ /path/to/forgeops/bin/ingress-controller-deploy.sh --aks
    namespace/nginx created
    Release "nginx-ingress" does not exist. Installing it now.
    NAME: nginx-ingress
    . . .
  3. Check the status of the pods in the nginx namespace until all the pods are ready:

    $ kubectl get pods --namespace nginx
    NAME                                              READY STATUS    RESTARTS AGE
    nginx-ingress-controller-69b755f68b-9l5n8         1/1   Running   0        4m38s
  4. Get the ingress controller’s public IP address:

    $ kubectl get services --namespace nginx
    NAME                                 TYPE           CLUSTER-IP     EXTERNAL-IP   PORT(S)                      AGE
    ingress-nginx-controller             LoadBalancer   10.0.149.206   20.51.97.25   80:30378/TCP,443:31333/TCP   25s
    ingress-nginx-controller-admission   ClusterIP      10.0.87.188    <none>        443/TCP                      25s

    The ingress controller’s IP address should appear in the EXTERNAL-IP column. There can be a short delay while the ingress starts before the IP address appears in the kubectl get services command’s output; you might need to run the command several times.

  5. Add an entry to the /etc/hosts file to resolve the deployment FQDN used by the platform UIs and APIs. For example:

    ingress-ip-address prod.iam.example.com

    For ingress-ip-address, specify the public IP address of the ingress controller service in the previous command.

Next Step

Certificate Manager

Use cert-manager when you deploy the CDM.

Remember, the CDM is a reference implementation and not for production use. When you create a project plan, you’ll need to determine how to manage certificates in production.

After you’ve finished deploying the CDM, you can use the CDM as a sandbox to explore deployment with a different certificate manager.

To deploy the Certificate Manager:

$ /path/to/forgeops/bin/certmanager-deploy.sh
customresourcedefinition.apiextensions.k8s.io/certificaterequests.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/certificates.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/challenges.acme.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/clusterissuers.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/issuers.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/orders.acme.cert-manager.io created
namespace/cert-manager created
serviceaccount/cert-manager-cainjector created
serviceaccount/cert-manager created
serviceaccount/cert-manager-webhook created
clusterrole.rbac.authorization.k8s.io/cert-manager-cainjector created
. . .
service/cert-manager created
service/cert-manager-webhook created
deployment.apps/cert-manager-cainjector created
deployment.apps/cert-manager created
deployment.apps/cert-manager-webhook created
mutatingwebhookconfiguration.admissionregistration.k8s.io/cert-manager-webhook created
validatingwebhookconfiguration.admissionregistration.k8s.io/cert-manager-webhook created
deployment.extensions/cert-manager-webhook condition met
clusterissuer.cert-manager.io/default-issuer created
secret/certmanager-ca-secret created

After you’ve deployed the Certificate Manager, check the status of the pods in the cert-manager namespace until all the pods are ready:

$ kubectl get pods --namespace cert-manager
NAME                                              READY STATUS    RESTARTS AGE
cert-manager-6d5fd89bdf-khj5w                     1/1   Running   0        3m57s
cert-manager-cainjector-7d47d59998-h5b48          1/1   Running   0        3m57s
cert-manager-webhook-6559cc8549-8vdtp             1/1   Running   0        3m56s
Next Step

Prometheus, Grafana, and Alert Manager

Use Prometheus, Grafana, and Alertmanager when you deploy the CDM.

After you’ve finished deploying the CDM, you can use the CDM as a sandbox to explore deployment with a different monitoring and alerting framework.

Remember, the CDM is a reference implementation and not for production use. When you create a project plan, you’ll need to determine how to monitor and send alerts in your production deployment.

To deploy Prometheus, Grafana, and Alertmanager:

  1. Deploy Prometheus, Grafana, and Alertmanager in your cluster:

    $ /path/to/forgeops/bin/prometheus-deploy.sh
    
    This script requires Helm version 3.04 or later due to changes in the behaviour of 'helm repo add' command.
    
    namespace/monitoring created
    "stable" has been added to your repositories
    "prometheus-community" has been added to your repositories
    . . .
    Update Complete. ⎈Happy Helming!⎈
    Release "prometheus-operator" does not exist. Installing it now.
    NAME: prometheus-operator
    LAST DEPLOYED: . . .
    NAMESPACE: monitoring
    STATUS: deployed
    REVISION: 1
    . . .
    pod/prometheus-operator-prometheus-node-exporter-lj6qb condition met
    pod/prometheus-operator-prometheus-node-exporter-tblbz condition met
    pod/prometheus-prometheus-operator-kube-p-prometheus-0 condition met
    Release "forgerock-metrics" does not exist. Installing it now.
    NAME: forgerock-metrics
    LAST DEPLOYED: . . .
    NAMESPACE: monitoring
    STATUS: deployed
    REVISION: 1
    TEST SUITE: None
  2. Check the status of the pods in the monitoring namespace until all the pods are ready:

    $ kubectl get pods --namespace monitoring
    NAME                                                      READY   STATUS    RESTARTS   AGE
    alertmanager-prometheus-operator-kube-p-alertmanager-0    2/2     Running   0          5m33s
    prometheus-operator-grafana-76985fcf94-gm557              2/2     Running   0          5m39s
    prometheus-operator-kube-p-operator-7884fb6cf7-7vtkt      1/1     Running   0          5m39s
    prometheus-operator-kube-state-metrics-847485d6bb-jgkk9   1/1     Running   0          5m39s
    prometheus-operator-prometheus-node-exporter-44fpz        1/1     Running   0          5m39s
    prometheus-operator-prometheus-node-exporter-cdl4g        1/1     Running   0          5m39s
    prometheus-operator-prometheus-node-exporter-fvvqq        1/1     Running   0          5m39s
    prometheus-operator-prometheus-node-exporter-gv5lq        1/1     Running   0          5m39s
    prometheus-operator-prometheus-node-exporter-lj6qb        1/1     Running   0          5m39s
    prometheus-operator-prometheus-node-exporter-tblbz        1/1     Running   0          5m39s
    prometheus-prometheus-operator-kube-p-prometheus-0        2/2     Running   1          5m33s
Next Step

docker push Setup

In the deployment environment you’re setting up, Skaffold builds Docker images using the Docker software you’ve installed on your local computer. After it builds the images, Skaffold pushes them to a Docker registry available to your AKS cluster. With the images on the remote Docker registry, Skaffold can orchestrate the ForgeRock Identity Platform, creating containers from the Docker images.

For Skaffold to push the Docker images:

  • Docker must be running on your local computer.

  • Your local computer needs credentials that let Skaffold push the images to the Docker repository available to your cluster.

  • Skaffold needs to know the location of the Docker repository.

Perform the following steps to let Skaffold to push Docker images to a registry accessible to your cluster:

  1. If it’s not already running, start Docker on your local computer. For more information, see the Docker documentation.

  2. If you don’t already have the name of the container registry that will hold ForgeRock Docker images, obtain it from your Azure administrator.

  3. Log in to your container registry:

    $ az acr login --name registry-name

    Azure repository logins expire after 4 hours. Because of this, you’ll need to log in to ACR whenever your login session expires [22].

  4. Run the kubectx command to obtain the Kubernetes context.

  5. Configure Skaffold with your Docker repository location and Kubernetes context:

    $ skaffold config \
     set default-repo registry-name.azurecr.io/cdm -k my-kubernetes-context

    For example:

    $ skaffold config set default-repo my-container-registry.azurecr.io/cdm -k small
Next Step

You’ve completed all the setup tasks for AKS. Now you’re ready to deploy the platform in your new cluster:

CDM Deployment

Now that you’ve set up your deployment environment following the instructions in the Environment Setup section for your cloud platform, you’re ready to deploy the CDM.

To deploy the CDM in your Kubernetes cluster using artifacts from the forgeops repository:

  1. Initialize the staging area for configuration profiles with the canonical CDK configuration profile [23] for the ForgeRock Identity Platform:

    $ cd /path/to/forgeops/bin
    $ ./config.sh init --profile cdk

    The config.sh init command copies the canonical CDK configuration profile from the master directory for configuration profiles to the staging area:

    The staging area is initialized from the canonical ${cdk.abbr} profile.

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

  2. Configure secrets for the ForgeRock Identity Platform:

    1. Make sure that context is set to the prod namespace:

      $ kubens prod
    2. Deploy the secrets:

      $ cd /path/to/forgeops/kustomize/base/secrets
      $ kubectl apply --filename secret_agent_config.yaml
    3. Verify that all the ForgeRock Identity Platform secrets have been created:

      $ kubectl get sac
      NAME            STATUS      NUMSECRETS   NUMK8SSECRETS
      forgerock-sac   Completed   14           14

      When the forgerock-sac entry reaches Completed status, all the secrets have been created.

  3. Change to the /path/to/forgeops directory and execute the skaffold run command. For example:

    $ cd /path/to/forgeops
    $ skaffold run --profile small
  4. Check the status of the pods in the prod namespace until all the pods are ready:

    1. Run the kubectl get pods command:

      $ kubectl get pods
      NAME                           READY   STATUS      RESTARTS   AGE
      admin-ui-69bc8b89bb-dtmj8      1/1     Running     0          3m30s
      am-cfc95954d-wqz6d             1/1     Running     0          3m29s
      amster-j87dl                   0/1     Completed   0          3m27s
      ds-cts-0                       1/1     Running     0          3m28s
      ds-cts-1                       1/1     Running     0          2m55s
      ds-cts-2                       1/1     Running     0          2m21s
      ds-idrepo-0                    1/1     Running     0          3m28s
      ds-idrepo-1                    1/1     Running     0          2m32s
      end-user-ui-6985574b49-dz8t9   1/1     Running     0          3m29s
      idm-57b6b86b98-hl8mj           1/1     Running     0          3m29s
      ldif-importer-m6n6x            0/1     Completed   0          3m27s
      login-ui-64b994b944-9qv7n      1/1     Running     0          3m29s
      rcs-agent-787769544d-jm7g4     1/1     Running     0          3m28s
    2. Review the output. Deployment is complete when:

      • All entries in the STATUS column indicate Running or Completed.

      • The READY column indicates all running containers are available. The entry in the READY column represents [total number of containers/number of available containers].

      • Three AM and two IDM pods are present.

      • The initial loading jobs (amster and ldif-importer) have reached Completed status.

    3. If necessary, continue to query your deployment’s status until all the pods are ready.

Next Step

UI and API Access

This page shows you how to access and monitor the ForgeRock Identity Platform components that make up the CDM.

AM and IDM are configured for access through the CDM cluster’s Kubernetes ingress controller. You can access these components using their normal interfaces:

  • For AM, the console and REST APIs.

  • For IDM, the Admin UI and REST APIs.

DS cannot be accessed through the ingress controller, but you can use Kubernetes methods to access the DS pods.

For more information about how AM and IDM have been configured in the CDM, see Configuration in the forgeops repository’s top-level README file for more information about the configurations.

AM Services

To access the AM console:

  1. Make sure that the prod namespace is the current namespace:

    $ kubens prod
  2. Obtain the amadmin user’s password:

    $ cd /path/to/forgeops/bin
    $ ./print-secrets amadmin
    vr58qt11ihoa31zfbjsdxxrqryfw0s31
  3. Open a new window or tab in a web browser.

  4. Go to https://prod.iam.example.com/platform.

    The Kubernetes ingress controller handles the request, routing it to the login-ui pod.

    The login UI prompts you to log in.

  5. Log in as the amadmin user.

    The ForgeRock Identity Platform UI appears in the browser.

  6. Select Native Consoles > Access Management.

    The AM console appears in the browser.

To access the AM REST APIs:

  1. Start a terminal window session.

  2. Run a curl command to verify that you can access the REST APIs through the ingress controller. For example:

    $ curl \
     --insecure \
     --request POST \
     --header "Content-Type: application/json" \
     --header "X-OpenAM-Username: amadmin" \
     --header "X-OpenAM-Password: vr58qt11ihoa31zfbjsdxxrqryfw0s31" \
     --header "Accept-API-Version: resource=2.0" \
     --data "{}" \
     "https://prod.iam.example.com/am/json/realms/root/authenticate"
    
    {
        "tokenId":"AQIC5wM2…​",
        "successUrl":"/am/console",
        "realm":"/"
    }

IDM Services

To access the IDM Admin UI:

  1. Make sure that the prod namespace is the current namespace:

    $ kubens prod
  2. Obtain the amadmin user’s password:

    $ cd /path/to/forgeops/bin
    $ ./print-secrets amadmin
    vr58qt11ihoa31zfbjsdxxrqryfw0s31
  3. Open a new window or tab in a web browser.

  4. Go to https://prod.iam.example.com/platform.

    The Kubernetes ingress controller handles the request, routing it to the login-ui pod.

    The login UI prompts you to log in.

  5. Log in as the amadmin user.

    The ForgeRock Identity Platform UI appears in the browser.

  6. Select Native Consoles > Identity Management.

    The IDM Admin UI appears in the browser.

To access the IDM REST APIs:

  1. Start a terminal window session.

  2. If you haven’t already done so, get the amadmin user’s password using the print-secrets command.

  3. AM authorizes IDM REST API access using the OAuth 2.0 authorization code flow. The CDM comes with the idm-admin-ui client, which is configured to let you get a bearer token using this OAuth 2.0 flow. You’ll use the bearer token in the next step to access the IDM REST API:

    1. Get a session token for the amadmin user:

      $ curl \
       --request POST \
       --insecure \
       --header "Content-Type: application/json" \
       --header "X-OpenAM-Username: amadmin" \
       --header "X-OpenAM-Password: vr58qt11ihoa31zfbjsdxxrqryfw0s31" \
       --header "Accept-API-Version: resource=2.0, protocol=1.0" \
       'https://prod.iam.example.com/am/json/realms/root/authenticate'
      {
       "tokenId":"AQIC5wM. . .TU3OQ*",
       "successUrl":"/am/console",
       "realm":"/"}
    2. Get an authorization code. Specify the ID of the session token that you obtained in the previous step in the --Cookie parameter:

      $ curl \
       --dump-header - \
       --insecure \
       --request GET \
       --Cookie "iPlanetDirectoryPro=AQIC5wM. . .TU3OQ*" \
       "https://prod.iam.example.com/am/oauth2/realms/root/authorize?redirect_uri=https://prod.iam.example.com/platform/appAuthHelperRedirect.html&client_id=idm-admin-ui&scope=openid%20fr:idm:*&response_type=code&state=abc123"
      HTTP/2 302
      server: nginx/1.17.10
      date: Mon, 10 May 2021 16:54:20 GMT
      content-length: 0
      location: https://prod.iam.example.com/platform/appAuthHelperRedirect.html
       ?code=3cItL9G52DIiBdfXRngv2_dAaYM&iss=http://prod.iam.example.com:80/am/oauth2&state=abc123
       &client_id=idm-admin-ui
      set-cookie: route=1595350461.029.542.7328; Path=/am; Secure; HttpOnly
      x-frame-options: SAMEORIGIN
      x-content-type-options: nosniff
      cache-control: no-store
      pragma: no-cache
      set-cookie: OAUTH_REQUEST_ATTRIBUTES=DELETED; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/; HttpOnly; SameSite=none
      strict-transport-security: max-age=15724800; includeSubDomains
      x-forgerock-transactionid: ee1f79612f96b84703095ce93f5a5e7b
    3. Exchange the authorization code for an access token. Specify the access code that you obtained in the previous step in the code URL parameter:

      $ curl --request POST \
       --insecure \
       --data "grant_type=authorization_code" \
       --data "code=3cItL9G52DIiBdfXRngv2_dAaYM" \
       --data "client_id=idm-admin-ui" \
       --data "redirect_uri=https://prod.iam.example.com/platform/appAuthHelperRedirect.html" \
       "https://prod.iam.example.com/am/oauth2/realms/root/access_token" 
      {
       "access_token":"oPzGzGFY1SeP2RkI-ZqaRQC1cDg",
       "scope":"openid fr:idm:*",
       "id_token":"eyJ0eXAiOiJKV
        . . .
        sO4HYqlQ",
       "token_type":"Bearer",
       "expires_in":239
      }
  4. Run a curl command to verify that you can access the openidm/config REST endpoint through the ingress controller. Use the access token returned in the previous step as the bearer token in the authorization header.

    The following example command provides information about the IDM configuration:

    $ curl \
     --insecure \
     --request GET \
     --header "Authorization: Bearer oPzGzGFY1SeP2RkI-ZqaRQC1cDg" \
     --data "{}" \
     https://prod.iam.example.com/openidm/config
    {
     "_id":"",
     "configurations":
      [
       {
        "_id":"ui.context/admin",
        "pid":"ui.context.4f0cb656-0b92-44e9-a48b-76baddda03ea",
        "factoryPid":"ui.context"
        },
        . . .
       ]
    }

Directory Services

The DS pods in the CDM are not exposed outside of the cluster. If you need to access one of the DS pods, use a standard Kubernetes method:

  • Execute shell commands in DS pods using the kubectl exec command.

  • Forward a DS pod’s LDAPS port (1636) to your local computer. Then, you can run LDAP CLI commands, for example ldapsearch. You can also use an LDAP editor such as Apache Directory Studio to access the directory.

For all CDM directory pods, the directory superuser DN is uid=admin. Obtain this user’s password by running the print-secrets dsadmin command.

CDM Monitoring

This section describes how to access Grafana dashboards and Prometheus UI.

Grafana

To access Grafana dashboards:

  1. Set up port forwarding on your local computer for port 3000:

    $ /path/to/forgeops/bin/prometheus-connect.sh -G
    Forwarding from 127.0.0.1:3000 → 3000
    Forwarding from [::1]:3000 → 3000
  2. In a web browser, navigate to http://localhost:3000 to access the Grafana dashboards.

  3. Log in as the admin user with password as the password.

When you’re done using the Grafana UI, enter Ctrl+c in the terminal window where you initiated port forwarding.

For information about Grafana, see the Grafana documentation.

Prometheus

To access the Prometheus UI:

  1. Set up port forwarding on your local computer for port 9090:

$ /path/to/forgeops/bin/prometheus-connect.sh -P
Forwarding from 127.0.0.1:9090 → 9090
Forwarding from [::1]:9090 → 9090
  1. In a web browser, navigate to http://localhost:9090 to access the Prometheus UI.

When you’re done using the Prometheus UI, enter Ctrl+c in the terminal window where you initiated port forwarding.

For information about the Prometheus, see the Prometheus documentation.

For a description of the CDM monitoring architecture and information about how to customize CDM monitoring, see CDM Monitoring.

Next Step

CDM Removal: GKE

To remove the CDM from GKE when you’re done working with it:

  1. Run the skaffold delete command to shut down your deployment and remove it from your namespace. For example:

    $ cd /path/to/forgeops
    $ skaffold delete --profile small
    Cleaning up…​
    . . .
  2. Remove your cluster:

    1. Change to the directory that contains the cluster removal script:

      $ cd /path/to/forgeops/cluster/gke
    2. Source the script that contains the configuration for your cluster size. For example:

      $ source ./small.sh
    3. Run the cluster removal script:

      $ ./cluster-down.sh
      The "small" cluster will be deleted. This action cannot be undone.
      Press any key to continue, or CTRL+C to quit
      1. Press Enter to proceed with cluster and data removal.

        Getting the cluster credentials for small in Zone my-region-a
        Fetching cluster endpoint and auth data.
        kubeconfig entry generated for small.
        Do you want to delete all PVCs allocated by this
        cluster (recommended for dev clusters)? [Y/N]
      2. Enter Y to confirm that you want to remove all the data created by this cluster, or enter N if you don’t want to delete the data.

        Draining all nodes
        node/gke-small-default-pool-05ac2046-c1xd cordoned
        node/gke-small-default-pool-5dd53b95-mr80 cordoned
        node/gke-small-default-pool-e835e4bb-0gwp cordoned
        . . .
        The following clusters will be deleted.
         - [small] in [my-region]
        Deleting cluster small…​done.
        Deleted [https://container.googleapis.com/v1/projects/my-project/zones/my-region/clusters/small].
        Check your GCP console for any orphaned project resources such as disks!
  3. Run the kubectx command.

    The Kubernetes context for the CDM cluster should not appear in the kubectx command output.

Use the Google Cloud Console to review your use of resources such as Compute Engine disks, static IP addresses, load balancers, and storage buckets. Avoid unnecessary charges by deleting resources that you’re no longer using.

CDM Removal: EKS

To remove the CDM from EKS when you’re done working with it:

  1. Run the skaffold delete command to shut down your deployment and remove it from your namespace. For example:

    $ cd /path/to/forgeops
    $ skaffold delete --profile small
    Cleaning up…​
  2. Remove your cluster:

    1. Change to the directory that contains the cluster removal script:

      $ cd /path/to/forgeops/cluster/eks
    2. Run the cluster removal script. Specify the YAML file that contains the configuration for your cluster size. For example:

      $ ./cluster-down.sh small.yaml
      The "small" cluster will be deleted. This action cannot be undone.
      Press any key to continue, or CTRL+C to quit
      1. Press Enter to proceed with cluster and data removal.

        Do you want to delete all PVCs allocated by this
        cluster (recommended for dev clusters)? [Y/N]
      2. Enter Y to confirm that you want to remove all the data created by this cluster, or enter N if you don’t want to delete the data.

        Draining all nodes
        node/ip-. . . .ec2.internal cordoned
        node/ip-. . . .ec2.internal cordoned
        . . .
        Deleting cluster "small"
        . . . [ℹ]  eksctl version 0.54.0
        . . . [ℹ]  using region us-east-1
        . . . [ℹ]  deleting EKS cluster "small"
        . . . [ℹ]  deleted 0 Fargate profile(s)
        . . . [✔]  kubeconfig has been updated
        . . . [ℹ]  cleaning up AWS load balancers created by Kubernetes objects of Kind Service or Ingress
        . . . [ℹ]  2 sequential tasks: { delete nodegroup "primary", delete cluster control plane "small" }
        . . . [ℹ]  will delete stack "eksctl-small-nodegroup-primary"
        . . . [ℹ]  waiting for stack "eksctl-small-nodegroup-primary" to get deleted
        
        . . .
        
        . . . [ℹ]  will delete stack "eksctl-small-cluster"
        . . . [ℹ]  waiting for CloudFormation stack "eksctl-small-cluster"
        
        . . .
        
        . . . [✔]  all cluster resources were deleted
  3. Run the kubectx command.

    The Kubernetes context for the CDM cluster should not appear in the kubectx command output.

CDM Removal: AKS

To remove the CDM from AKS when you’re done working with it:

  1. Run the skaffold delete command to shut down your deployment and remove it from your namespace. For example:

    $ cd /path/to/forgeops
    $ skaffold delete --profile small
    Cleaning up…​
  2. Remove your cluster:

    1. Change to the directory that contains the cluster removal script:

      $ cd /path/to/forgeops/cluster/aks
    2. Source the script that contains the configuration for your cluster size. For example:

      $ source ./small.sh
    3. Run the cluster removal script:

      $ ./cluster-down.sh
      The "small" cluster will be deleted. This action cannot be undone.
      Press any key to continue, or CTRL+C to quit
      1. Press Enter to proceed with cluster and data removal.

        Getting the cluster credentials for small in Zone my-region-a
        Fetching cluster endpoint and auth data.
        kubeconfig entry generated for small.
        Do you want to delete all PVCs allocated by this
        cluster (recommended for dev clusters)? [Y/N]
      2. Enter Y to confirm that you want to remove all the data created by this cluster, or enter N if you don’t want to delete the data.

        Draining all nodes
        node/aks-primsmall-18811554-vmss000000 cordoned
        node/aks-primsmall-18811554-vmss000001 cordoned
        node/aks-primsmall-18811554-vmss000002 cordoned
        . . .
        
        Deleting AKS cluster small…​
        Deleting resource group small-res-group…​
  3. Run the kubectx command.

    The Kubernetes context for the CDM cluster should not appear in the kubectx command output.

Next Steps

If you’ve followed the instructions for deploying the CDM without modifying configurations, then the following indicates that you’ve been successful:

  • The Kubernetes cluster and pods are up and running.

  • DS, AM, and IDM are installed and running. You can access each ForgeRock component.

  • DS is provisioned with sample users. Replication and failover work as expected.

  • Monitoring tools are installed and running. You can access a monitoring console for DS, AM, and IDM.

When you’re satisfied that all of these conditions are met, then you’ve successfully taken the first steps towards deploying the ForgeRock Identity Platform in the cloud. Congratulations!

You can use the CDM to test deployment customizations—options that you might want to use in production, but are not part of the CDM. Examples include, but are not limited to:

  • Running lightweight benchmark tests

  • Making backups of CDM data, and restoring the data

  • Securing TLS with a certificate that’s dynamically obtained from Let’s Encrypt

  • Using an ingress controller other than the NGINX ingress controller

  • Resizing the cluster to meet your business requirements

  • Configuring Alert Manager to issue alerts when usage thresholds have been reached

Now that you’re familiar with the CDM—ForgeRock’s reference implementation—you’re ready to work with a project team to plan and configure your production deployment. You’ll need a team with expertise in the ForgeRock Identity Platform, in your cloud provider, and in Kubernetes on your cloud provider. We strongly recommend that you engage a ForgeRock technical consultant or partner to assist you with deploying the platform in production.

You’ll perform these major activities:

Platform configuration. ForgeRock Identity Platform experts configure AM and IDM using the CDK, and build custom Docker images for the ForgeRock Identity Platform. The Cloud Developer’s Kit Documentation provides information about platform configuration tasks.

Cluster configuration. Cloud technology experts configure the Kubernetes cluster that will host the ForgeRock Identity Platform for optimal performance and reliability. Tasks include: configuring your Kubernetes cluster to suit your business needs; setting up monitoring and alerts to track site health and performance; backing up configuration and user data for disaster preparedness; and securing your deployment. The How-Tos and READMEs in the forgeops repository provide information about cluster configuration.

Site reliability engineering. Site reliability engineers monitor the ForgeRock Identity Platform deployment, and keep the deployment up and running based on your business requirements. These might include use cases, service-level agreements, thresholds, and load test profiles. The How-Tos, and READMEs in the forgeops repository, provide information about site reliability.

How-Tos

After you get the CDM up and running, you can use it to test deployment customizations—​options that are not part of the CDM, but which you might want to use when you deploy in production.

The ForgeRock Identity Platform serves as the basis for our simple and comprehensive identity and access management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

Base Docker Images

ForgeRock provides eleven Docker images for deploying the ForgeRock Identity Platform:

  • Eight unsupported, evaluation-only base images:

    • amster

    • am-base

    • am-config-upgrader

    • ds

    • ldif-importer

    • idm

    • rcs-agent

    • ig

  • Three supported base images that implement the platform’s user interface elements:

    • platform-admin-ui

    • platform-enduser-ui

    • platform-login-ui

All of the Docker images are publicly available in ForgeRock’s Docker registry, gcr.io/forgerock-io.

Which Docker Images Do I Deploy?

  • I am a developer using the CDK.

    • UI elements. Deploy the supported images from ForgeRock.

    • Other platform elements. Either deploy the evaluation-only images from ForgeRock or your own base images.

  • I am doing a proof-of-concept CDM deployment.

    • UI elements. Deploy the supported images from ForgeRock.

    • Other platform elements. Either deploy the evaluation-only images from ForgeRock or your own base images.

  • I am deploying the platform in production.

    • UI elements. Deploy the supported images from ForgeRock.

    • Other platform elements. Deploy your own base images. The evaluation-only images are not supported for production deployments of the ForgeRock Identity Platform.

Your Own Base Docker Images

Perform the following steps to build base images for the seven unsupported, evaluation-only Docker images. After you’ve built your own base images, push them to your Docker registry:

  1. Download the latest versions of the AM, Amster, IDM, DS, and RCS Agent .zip files from the ForgeRock Download Center. Optionally, you can also download the latest version of the IG .zip file.

  2. Build the base image for Amster. This image must be available in order to build the base image for AM in the next step:

    1. Make a directory named amster.

    2. Unzip the Amster .zip file into the new amster directory.

    3. Change to the samples/docker directory in the expanded .zip file output.

    4. Run the setup.sh script:

      $ ./setup.sh
      
      + mkdir -p build
      + find ../.. '!' -name .. '!' -name samples '!' -name docker -maxdepth 1 -exec cp -R '{}' build/ ';'
      + cp ../../docker/amster-install.sh ../../docker/docker-entrypoint.sh ../../docker/export.sh ../../docker/tar.sh build
    5. Build the amster Docker image:

      $ docker build --tag amster:7.1.0 .
      
      Sending build context to Docker daemon  59.44MB
      Step 1/12 : FROM gcr.io/forgerock-io/java-11:latest
      latest: Pulling from forgerock-io/java-11
      . . .
      ⇒ exporting to image                                                                                                                                              1.2s
       ⇒ ⇒ exporting layers                                                                                                                                             1.2s
       ⇒ ⇒ writing image sha256:bc474cb6c189e253278f831f178b8d51f63a958a6526c0189fdf122ddf8f9e52                                                                        0.0s
       ⇒ ⇒ naming to docker.io/library/amster:7.1.0
  3. Build the base image for AM:

    1. Unzip the AM .zip file.

    2. Change to the openam/samples/docker directory in the expanded .zip file output.

    3. Run the setup.sh script:

      $ chmod u+x setup.sh
      $ ./setup.sh
    4. Change to the images/am-empty directory.

    5. Build the am-empty Docker image:

      $ docker build --tag am-empty:7.1.0 .
      
      Sending build context to Docker daemon  207.7MB
      Step 1/34 : FROM tomcat:9-jdk11-adoptopenjdk-hotspot AS base
      9-jdk11-adoptopenjdk-hotspot: Pulling from library/tomcat
      . . .
      Successfully tagged am-empty:7.1.0
    6. Change to the ../am-base directory.

    7. Build the am-base Docker image:

      $ docker build --build-arg docker_tag=7.1.0 --tag my-registry/am-base:7.1.0 .
      
      Sending build context to Docker daemon  27.12MB
      Step 1/27 : ARG docker_tag=latest
      . . .
      Successfully tagged my-registry/am-base:7.1.0
  4. Now that the AM image is built, tag the base image for Amster in advance of pushing it to your private repository:

    $ docker tag amster:7.1.0 my-registry/amster:7.1.0
  5. Build the am-config-upgrader base image:

    1. Change to the openam directory in the expanded AM .zip file output.

    2. Unzip the Config-Upgrader-7.1.0.zip file.

    3. Change to the amupgrade/samples/docker directory in the expanded Config-Upgrader-7.1.0.zip file output.

    4. Run the setup.sh script:

      $ ./setup.sh
    5. Create the base am-config-upgrader image:

      docker build . --tag my-registry/am-config-upgrader:7.1.0
  6. Build the base image for DS:

    1. Unzip the DS .zip file.

    2. Change to the opendj directory in the expanded .zip file output.

    3. Run the samples/docker/setup.sh script to create a server:

      $ ./samples/docker/setup.sh
      
      + rm -f template/config/tools.properties
      + cp -r samples/docker/Dockerfile samples/docker/README.md . . .
      + rm -rf — README README.md bat '*.zip' opendj_logo.png setup.bat upgrade.bat setup.sh
      + ./setup --serverId docker --hostname localhost
      . . .
      
      Validating parameters…​.. Done
      Configuring certificates…​…​. Done
      . . .
    4. Build the ds base image:

      $ docker build --tag my-registry/ds:7.1.0 .
      
      Sending build context to Docker daemon  60.53MB
      Step 1/14 : FROM gcr.io/forgerock-io/java-11:latest
       --→ 4804ddd23a47
      . . .
      Successfully tagged my-registry/ds:7.1.0
  7. Build the ldif-importer base image:

    1. Change to the /path/to/forgeops/docker/7.0/ldif-importer directory.

    2. Open the file, Dockerfile.

    3. Change the FROM statement—the first line in the file—to reference the ds base image you created in the previous step:

      FROM my-registry/ds:7.1.0
    4. Save and close the updated file.

    5. Create the base ldif-importer image:

      $ docker build . --tag my-registry/ldif-importer:7.1.0
  8. Build the base image for IDM:

    1. Unzip the IDM .zip file.

    2. Change to the openidm directory in the expanded .zip file output.

    3. Build the idm base image:

      $ docker build . --file bin/Custom.Dockerfile --tag my-registry/idm:7.1.0
      
      Sending build context to Docker daemon  220.2MB
      Step 1/7 : FROM gcr.io/forgerock-io/java-11:latest
       --→ 4d0811d78b02
      Step 2/7 : RUN apt-get update &&     apt-get install -y ttf-dejavu
       --→ Running in e0943ff14f4b
      Get:1 http://deb.debian.org/debian stable InRelease [121 kB]
      Get:2 http://deb.debian.org/debian stable-updates InRelease [51.9 kB]
      Get:3 http://deb.debian.org/debian stable/main amd64 Packages [7905 kB]
      Get:4 http://security.debian.org/debian-security stable/updates InRelease [65.4 kB]
      Get:5 http://security.debian.org/debian-security stable/updates/main amd64 Packages [213 kB]
      Get:6 http://deb.debian.org/debian stable-updates/main amd64 Packages [7868 B]
      Fetched 8364 kB in 2s (3401 kB/s)
      Reading package lists…​
      . . .
  9. Build the base image for the RCS Agent:

    1. Create a directory named rcs-agent

    2. Unzip the RCS Agent .zip file into the new rcs-agent directory.

    3. Change to the rcs-agent directory containing the expanded .zip file output.

    4. Build the rcs-agent base image:

      $ docker build . --tag my-registry/rcs-agent:7.1.0
      
      Sending build context to Docker daemon  6.362MB
      Step 1/5 : FROM gcr.io/forgerock-io/java-11:latest
       --→ 4804ddd23a47
      . . .
      Successfully tagged my-registry/rcs-agent:7.1.0
  10. (Optional) Build the base image for IG:

    1. Unzip the IG .zip file.

    2. Change to the identity-gateway directory in the expanded .zip file output.

    3. Build the ig base image:

      $ docker build . --file docker/Dockerfile --tag my-registry/ig:7.1.0
      
      Sending build context to Docker daemon   74.2MB
      Step 1/7 : FROM gcr.io/forgerock-io/java-11:latest
       --→ 4d0811d78b02
      Step 2/7 : ENV INSTALL_DIR /opt/ig
       --→ Running in f5e061706b02
      Removing intermediate container f5e061706b02
       --→ 708270442f94
      Step 3/7 : COPY --chown=forgerock:root . "${INSTALL_DIR}"
       --→ 9352147619b8
      Step 4/7 : ENV IG_INSTANCE_DIR /var/ig
       --→ Running in 343ef5140cee
      Removing intermediate container 343ef5140cee
       --→ a9bcb4b280c6
      . . .
  11. Run the docker images command to verify that you built the base images:

    $ docker images
    
    REPOSITORY                     TAG      IMAGE ID        CREATED        SIZE
    my-registry/am-base            7.1.0    552073a1c000    1 hour ago     795MB
    my-registry/am-config-upgrader 7.1.0    d115125b1c3f    1 hour ago     795MB
    my-registry/amster             7.1.0    d9e1c735f415    1 hour ago     577MB
    my-registry/ds                 7.1.0    ac8e8ab0fda6    1 hour ago     196MB
    my-registry/idm                7.1.0    0cc1b7f70ce6    1 hour ago     387MB
    my-registry/ig                 7.1.0    9728c30c1829    1 hour ago     249MB
    my-registry/ldif-importer      7.1.0    1ef5333c4230    1 hour ago     223MB
    my-registry/rcs-agent          7.1.0    422a1d76ff28    1 hour ago     148MB
    . . .
  12. Push the new base Docker images to your Docker registry.

    See your registry provider documentation for detailed instructions. For most Docker registries, you run the docker login command to log in to the registry. Then, you run the docker push command to push a Docker image to the registry.

    However, some Docker registries have different requirements. For example, to push Docker images to Google Container Registry, you use Google Cloud SDK commands instead of using the docker push command.

    Push the following images:

    • my-registry/am-base:7.1.0

    • my-registry/amster:7.1.0

    • my-registry/am-config-upgrader:7.1.0

    • my-registry/ds:7.1.0

    • my-registry/idm:7.1.0

    • my-registry/ldif-importer:7.1.0

    • my-registry/rcs-agent:7.1.0

    If you’re deploying your own IG base image, also push the my-registry/ig:7.1.0 image.

Developer Dockerfile Changes

After you’ve pushed your own base images to your Docker registry, update the Dockerfiles that your developers use when creating customized Docker images for the ForgeRock Identity Platform. The Dockerfiles can now reference your own base images instead of the evaluation-only images from ForgeRock.

To change developer Dockerfiles to use your base images:

  1. Update the AM Dockerfile:

    1. Change to the /path/to/forgeops/docker/7.0/am directory.

    2. Open the file, Dockerfile, in that directory.

    3. Change the line:

      FROM gcr.io/forgerock-io/am-base:7.1.0

      to:

      FROM my-registry/am-base:7.1.0
  2. Make a similar change to the file, /path/to/forgeops/docker/7.0/amster/Dockerfile.

  3. Make a similar change to the file, /path/to/forgeops/docker/7.0/ds/cts/Dockerfile.

  4. Make a similar change to the file, /path/to/forgeops/docker/7.0/ds/idrepo/Dockerfile.

  5. Make a similar change to the file, /path/to/forgeops/docker/7.0/idm/Dockerfile.

  6. (Optional) Make a similar change to the file, /path/to/forgeops/docker/7.0/ig/Dockerfile.

You can now build customized Docker images for the ForgeRock Identity Platform based on your own Docker images and use them in production deployments.

The next time you run Skaffold, you must set the --no-prune and --cache-artifacts options to false to ensure that Skaffold loads the new images that you just built instead of loading previous images from cache. For example:

$ skaffold run --no-prune=false --cache-artifacts=false

Deploy IG

IG is not deployed with the CDK or the CDM by default.

To deploy IG after you have deployed the CDK or the CDM:

  1. Verify that the CDK or the CDM is up and running.

  2. Set the active namespace in your local Kubernetes context to the namespace in which you have deployed the platform components.

  3. Deploy IG:

    $ /path/to/forgeops/bin/cdk install ig
    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): ['ig']
    
    secret/openig-secrets-env created
    service/ig created
    deployment.apps/ig created
    
    Enjoy your deployment!

    By default, the cdk install command uses the evaluation-only Docker images for release 7.1.0 of the platform, available from ForgeRock’s public registry.

    However, if you have built a custom IG image, the cdk install command uses your custom image.

  4. Run the kubectl get pods command to check the status of the IG pod. Wait until the pod is ready before proceeding to the next step.

  5. Verify that IG is running.

    If you deployed IG on the CDK:

    $ curl --insecure -L -X GET https://dev.example.com/ig/openig/ping -v
    Note: Unnecessary use of -X or --request, GET is already inferred.
    *   Trying . . .
    * TCP_NODELAY set
    . . .
    > GET /ig/openig/ping HTTP/2
    > Host: dev.example.com
    > User-Agent: curl/7.64.1
    > Accept: /
    * Connection state changed (MAX_CONCURRENT_STREAMS == 128)!
    < HTTP/2 200
    < date: Thu, 29 Jul 2021 21:07:44 GMT
    <
    * Connection #0 to host dev.example.com left intact
    * Closing connection 0

    If you deployed IG on the CDM:

    $ curl --insecure -L -X GET https://prod.iam.example.com/ig/openig/ping -v
    . . .
  6. Verify that the reverse proxy to the IDM pod is running.

    If you deployed IG on the CDK:

    $ curl --insecure -L -X GET https://dev.example.com/ig/openidm/info/ping -v
    Note: Unnecessary use of -X or --request, GET is already inferred.
    *   Trying 192.168.99.155…​
    * TCP_NODELAY set
    * Connected to dev.example.com (192.168.99.155) port 443 (#0)
    * ALPN, offering h2
    * ALPN, offering http/1.1
    * successfully set certificate verify locations:
    *   CAfile: /etc/ssl/cert.pem
      CApath: none
    * TLSv1.2 (OUT), TLS handshake, Client hello (1):
    . . .
    * Using HTTP2, server supports multi-use
    * Connection state changed (HTTP/2 confirmed)
    * Copying HTTP/2 data in stream buffer to connection buffer after upgrade: len=0
    . . .
    * Connection state changed (MAX_CONCURRENT_STREAMS == 128)!
    < HTTP/2 200
    . . .
    <
    * Connection #0 to host dev.example.com left intact
    {"_id":"","_rev":"","shortDesc":"OpenIDM ready","state":"ACTIVE_READY"}* Closing connection 0

    If you deployed IG on the CDM:

    $ curl --insecure -L -X GET https://prod.iam.example.com/ig/openidm/info/ping -v
    . . .

Custom IG Image

The IG configuration provided in the CDK canonical configuration profile is an example, and is not meant for use in production. Remove this configuration and replace it with your own routes before using IG in your environment.

See the IG Deployment Guide for configuring routes.

Prerequisites

Before starting to build and deploy your custom IG image, initialize a new configuration profile and set up your local environment to write Docker images:

  1. Initialize a new configuration profile by copying the canonical CDK configuration:

    $ cd /path/to/forgeops/config/7.0
    $ cp -r cdk my-ig
  2. Configure your environment to write to your Docker registry:

    Minikube

    Set up your local environment to execute docker commands on Minikube’s Docker engine:

    1. Run the docker-env command in your shell:

      $ eval $(minikube docker-env)
    2. Stop Skaffold from pushing Docker images to a remote Docker registry:

      $ skaffold config set --kube-context minikube local-cluster true
      set value local-cluster to true for context minikube
    GKE shared cluster

    To set up your local computer to push Docker images:

    1. If it’s not already running, start Docker on your local computer. For more information, see the Docker documentation.

    2. Set up a Docker credential helper:

      $ gcloud auth configure-docker
    3. Run the kubectx command to obtain the Kubernetes context.

    4. Configure Skaffold with the Docker registry location you obtained from your cluster administrator and the Kubernetes context you obtained in Context for the Shared Cluster:

      $ skaffold config set default-repo my-docker-registry --kube-context my-kubernetes-context
    EKS shared cluster

    Set up your local computer to push Docker images to Amazon ECR:

    1. If it’s not already running, start Docker on your local computer. For more information, see the Docker documentation.

    2. Log in to Amazon ECR. Use the Docker registry location you obtained from your cluster administrator:

      $ aws ecr get-login-password | \
       docker login --username AWS --password-stdin my-docker-registry
      stdin my-docker-registry
      Login Succeeded

      ECR login sessions expire after 12 hours. Because of this, you’ll need to perform these steps again whenever your login session expires.

    3. Run the kubectx command to obtain the Kubernetes context.

    4. Configure Skaffold with the Docker registry location and the Kubernetes context:

      $ skaffold config set default-repo my-docker-registry --kube-context my-kubernetes-context
    AKS shared cluster

    Set up your local computer to push Docker images to Azure container registry:

    1. If it’s not already running, start Docker on your local computer. For more information, see the Docker documentation.

    2. Install the ACR Docker Credential Helper.

    3. Run the kubectx command to obtain the Kubernetes context.

    4. Configure Skaffold with the Docker registry location you obtained from your cluster administrator and the Kubernetes context you obtained in Context for the Shared Cluster:

      $ skaffold config set default-repo my-docker-registry --kube-context my-kubernetes-context

Build a Custom IG Image and Deploy IG

  1. Verify that the CDK is up and running.

  2. Configure IG by creating, modifying, or deleting rules in /path/to/forgeops/config/my-ig/ig/config/routes-service directory.

  3. Copy your customized IG configuration to the staging area:

    $ cd /path/to/forgeops/config/7.0/my-ig
    $ cp -r ./ig /path/to/forgeops/docker/7.0
  4. Build a new IG image that includes your custom configuration:

    $ /path/to/forgeops/bin/cdk build ig
    Generating tags…​
     - ig → ig:0a27bdfea
    Checking cache…​
     - ig: Not found. Building
    Starting build…​
    Found [minikube] context, using local docker daemon.
    Building [ig]…​
    Sending build context to Docker daemon  55.81kB
    Step 1/5 : FROM gcr.io/forgerock-io/ig/pit1:7.2.0-latest-postcommit
     --→ ba6f8150204e
    Step 2/5 : ARG CONFIG_PROFILE=cdk
    . . .
    Step 5/5 : COPY --chown=forgerock:root . /var/ig
     --→ c173995218a3
    Successfully built c173995218a3
    Successfully tagged ig:0a27bdfea
    
    Updated the image_defaulter with your new image for ig: "ig:c173995218a3c55dbca76fff08588153db0693a51ff0904e6adee34b7163340a"
  5. Uninstall the previously deployed IG from your CDK:

    1. Set the active namespace in your local Kubernetes context to the namespace in which you have deployed the IG.

    2. Delete IG:

      $ /path/to/forgeops/bin/cdk delete ig
      Uninstalling component(s): ['ig']
      OK to delete these components? [Y/N] y
      secret "openig-secrets-env" deleted
      service "ig" deleted
      deployment.apps "ig" deleted
  6. Deploy your customized IG image:

    $ /path/to/forgeops/bin/cdk install ig
    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): ['ig']
    
    secret/openig-secrets-env created
    service/ig created
    deployment.apps/ig created
    
    Enjoy your deployment!
  7. Run the kubectl get pods command to check the status of the IG pod. Wait until the IG pod is ready before proceeding to the next step.

  8. Verify that your IG routes work.

CDM Backup and Restore

The backup topology of DS in the CDM:

Diagram about backup topology.
CDM directory architecture

Five DS instances are deployed using Kubernetes stateful sets (two idrepo and three cts backends).

Backup architecture

Before you can back up CDM data, you must set up a cloud storage container, and then configure a Kubernetes secret with the container’s location and credentials in the CDM deployment.

DS data backups are stored in Google Cloud Service, Amazon S3, or Azure Blob Storage.

All backups are incremental from the previous backup. The first backup created is a full backup.

DS server instances use cryptographic keys to sign and verify the integrity of backup files, and to encrypt data. Server instances protect these keys in a deployment by encrypting them with the shared master key. For portability, servers store the encrypted keys in the backup files.

Backup scheduling

Backups must be scheduled using the schedule-backups.sh script in the /path/to/forgeops/bin path on your local computer.

By default, CTS and identity repository directory instances are backed up every hour.

The backup schedule can be customized separately for CTS and identity repository DS instances based on your recovery objectives.

By default, the backups are scheduled from the first (or -0) pod of each DS instance. You can customize and schedule backups from any pod of a DS instance. You can also schedule backups from multiple pods.

Restore

You can initialize new DS instances with data from a backup when you deploy CDM.

You can restore existing cts or idrepo DS instances from a backup.

Restoring a new or existing DS instance from a backup requires that the instance being restored has the same shared master key as the instance that performed the backup. To ensure that the master key is shared, implement cloud secret management when you deploy the CDM.

Google Cloud

Set up a Google Cloud storage bucket for the DS data backup, and configure the forgeops artifacts with the location and credentials for the bucket:

  1. Create a Google Cloud service account with sufficient privileges to write objects in a Google Cloud Storage (GCS) bucket. For example, Storage Object Creator.

  2. Add a key to the service account, and download the JSON file that contains the new key.

  3. Configure a multi-region GCS bucket for storing DS backups:

    1. Create a new bucket, or identify an existing bucket to use.

    2. Note the bucket’s Link for gsutil value.

    3. Grant permissions on the bucket to the service account you created in step 1.

  4. Make sure that your current Kubernetes context references the CDM cluster and the prod namespace.

  5. Create secrets that contain credentials to write to cloud storage. The DS pods will use these when performing backups.

    For my-sa-credential.json, specify the JSON file that contains the service account’s key:

    1. Create the cloud-storage-credentials-cts secret:

      $ kubectl create secret generic cloud-storage-credentials-cts \
       --from-file=GOOGLE_CREDENTIALS_JSON=/path/to/my-sa-credential.json \
       --dry-run --output yaml | kubectl apply --filename -
    2. Create the cloud-storage-credentials-idrepo secret:

      $ kubectl create secret generic cloud-storage-credentials-idrepo \
       --from-file=GOOGLE_CREDENTIALS_JSON=/path/to/my-sa-credential.json \
       --dry-run --output yaml | kubectl apply --filename -
  6. Set the backup location in the configuration of the running CDM instance:

    1. Get the platform-config configmap:

      $ kubectl get configmap platform-config --output yaml > my-config.yaml
    2. In the output file from the preceding step, set the DSBACKUP_DIRECTORY parameter to the Link for gsutil of the DS data backup bucket:

      For example: DSBACKUP_DIRECTORY "gs://my-backup-bucket"

    3. Apply the change to the running CDM:

      $ kubectl apply --filename my-config.yaml
  7. Apply the same change to your local Kustomization overlay file to ensure that the backup location is configured correctly the next time you deploy the CDM:

    1. Change to the /path/to/forgeops/kustomize/base/kustomizeConfig directory.

    2. Edit the kustomization.yaml file and set the DSBACKUP_DIRECTORY parameter to the location of the backup bucket.

      For example: DSBACKUP_DIRECTORY "gs://my-backup-bucket"

  8. Restart the pods that perform backups, so that DS can obtain the backup location and the credentials needed to write to the backup location:

    $ kubectl delete pods ds-cts-0
    $ kubectl delete pods ds-idrepo-0

Now you are ready to schedule backups.

AWS

Set up an S3 bucket for the DS data backup, and configure the forgeops artifacts with the location and credentials for the S3 bucket:

  1. Create or identify an existing S3 bucket for storing the DS data backup, and note the S3 link of the bucket.

  2. Make sure that your current Kubernetes context references the CDM cluster and the prod namespace.

  3. Create secrets that contain credentials to write to cloud storage. The DS pods will use these when performing backups:

    1. Create the cloud-storage-credentials-cts secret:

      $ kubectl create secret generic cloud-storage-credentials-cts \
       --from-literal=AWS_ACCESS_KEY_ID=my-access-key \
       --from-literal=AWS_SECRET_ACCESS_KEY=my-secret-access-key \
       --dry-run --output yaml | kubectl apply --filename -
    2. Create the cloud-storage-credentials-idrepo secret:

      $ kubectl create secret generic cloud-storage-credentials-idrepo \
       --from-literal=AWS_ACCESS_KEY_ID=my-access-key \
       --from-literal=AWS_SECRET_ACCESS_KEY=my-secret-access-key \
       --dry-run --output yaml | kubectl apply --filename -
  4. Set the backup location in the configuration of the running CDM instance:

    1. Get the platform-config configmap:

      $ kubectl get configmap platform-config --output yaml > my-config.yaml
    2. In the output file from the preceding step, set the DSBACKUP_DIRECTORY parameter to the S3 link of the DS data backup bucket:

      For example: DSBACKUP_DIRECTORY s3://my-backup-bucket

    3. Apply the change to the running CDM instance:

      $ kubectl apply --filename my-config.yaml
  5. Apply the same change to your local Kustomization overlay file to ensure that the backup location is configured correctly the next time you deploy the CDM:

    1. Change to the /path/to/forgeops/kustomize/base/kustomizeConfig directory.

    2. Edit the kustomization.yaml file and set the DSBACKUP_DIRECTORY parameter to the S3 link of the DS data backup bucket.

      For example: DSBACKUP_DIRECTORY s3://my-backup-bucket

  6. Restart the pods that perform backups, so that DS can obtain the backup location and the credentials needed to write to the backup location:

    $ kubectl delete pods ds-cts-0
    $ kubectl delete pods ds-idrepo-0

Now you are ready to schedule backups.

Azure

Set up an Azure Blob Storage container for the DS data backup, and configure the forgeops artifacts with the location and credentials for the container:

  1. Create or identify an existing Azure Blob Storage container for the DS data backup. For more information on how to create and use Azure Blob Storage, see Quickstart: Create, download, and list blobs with Azure CLI.

  2. Make sure that your current Kubernetes context references the CDM cluster and the prod namespace.

  3. Create secrets that contain credentials to write to cloud storage. The DS pods will use these when performing backups:

    1. Get the name and access key of the Azure storage account that contains your storage container.

    2. Create the cloud-storage-credentials-cts secret:

      $ kubectl create secret generic cloud-storage-credentials-cts \
       --from-literal=AZURE_ACCOUNT_NAME=my-storage-account-name \
       --from-literal=AZURE_ACCOUNT_KEY=my-storage-account-access-key \
       --dry-run --output yaml | kubectl apply --filename -
    3. Create the cloud-storage-credentials-idrepo secret:

      $ kubectl create secret generic cloud-storage-credentials-idrepo \
       --from-literal=AZURE_ACCOUNT_NAME=my-storage-account-name \
       --from-literal=AZURE_ACCOUNT_KEY=my-storage-account-access-key \
       --dry-run --output yaml | kubectl apply --filename -
  4. Set the backup location in the configuration of the running CDM instance:

    1. Get the platform-config configmap:

      $ kubectl get configmap platform-config --output yaml > my-config.yaml
    2. In the output file from the preceding step, set the DSBACKUP_DIRECTORY parameter to the string az://, followed by the name of the storage container:

      For example: DSBACKUP_DIRECTORY az://my-storage-container

    3. Apply the change to the running CDM:

      $ kubectl apply --filename my-config.yaml
  5. Apply the same change to your local Kustomization overlay file to ensure that the backup location is configured correctly the next time you deploy the CDM:

    1. Change to the /path/to/forgeops/kustomize/base/kustomizeConfig directory.

    2. Edit the kustomization.yaml file and set the DSBACKUP_DIRECTORY parameter to the string az://, followed by the name of the storage container.

      For example: DSBACKUP_DIRECTORY az://my-storage-container

  6. Restart the pods that perform backups, so that DS can obtain the backup location and the credentials needed to write to the backup location:

    $ kubectl delete pods ds-cts-0
    $ kubectl delete pods ds-idrepo-0

Now you are ready to schedule backups.

DS Backup Scheduling

To schedule DS backups:

  1. Make sure that you’ve set up cloud storage for your cloud provider platform:

  2. Make sure that you’ve implemented cloud secret management. DS instances on which you restore data must have the same master key as DS instances on which you perform backups. If you don’t share the master key, you won’t be able to restore from your backups.

  3. Decide whether you would prefer to use the default backup schedule or a customized backup schedule.

  4. Schedule backups:

    1. If you want to use the default backup schedule, run the schedule-backups.sh script as described in Default Backup Schedule.

    2. If you want to use a customized backup schedule, edit files, and then run the schedule-backups.sh script as described in Customized Backup Schedule.

Default Backup Schedule

The default backup schedule creates incremental backups of the idrepo instance at the beginning of every hour, and the cts instance at 10 minutes past every hour.

Run the schedule-backups.sh script to start backing up cts and idrepo instances using the default schedule:

$  /path/to/forgeops/bin/schedule-backups.sh my-namespace

In the CDM deployment, DS is deployed to the prod namespace. So you would specify prod as the namespace in the above command. If you have deployed DS in another namespace, you must specify the corresponding namespace.

Customized Backup Schedule

You can customize the backup schedule for cts and idrepo instances separately. You can also schedule backups from any DS pod.

For example, suppose you wanted to make these customizations to the default backup schedule:

  • Back up the ds-idrepo-1 directory instance (instead of the ds-idrepo-0 instance).

  • Back up the idrepo directory at the start of every hour, and at the thirtieth minute of every hour (instead of once an hour at the start of the hour).

  • Back up the cts directory at 20 minutes after the hour (instead of at 10 minutes after the hour).

To customize the schedules for the idrepo and cts instances, and to schedule backups from the ds-idrepo-1 pod instead of the ds-idrepo-0 pod:

  1. Revise the set of instances to be backed up in the configuration of the running CDM instance:

    1. Get the platform-config configmap:

      $ kubectl get configmap platform-config --output yaml > my-config.yaml
    2. In the output file from the preceding step, set the DSBACKUP_HOSTS parameter to the revised set of instances to be backed up:

      For example: DSBACKUP_HOSTS "ds-idrepo-1,ds-cts-0"

    3. Apply the change to the running CDM:

      $ kubectl apply --filename my-config.yaml
  2. Apply the same change to your local Kustomization overlay file to ensure that the set of backup instances is configured correctly the next time you deploy the CDM:

    1. Change to the /path/to/forgeops/kustomize/base/kustomizeConfig directory.

    2. Edit the kustomization.yaml file and set the DSBACKUP_HOSTS parameter to the revised set of backup instances.

      For example: DSBACKUP_HOSTS "ds-idrepo-1,ds-cts-0"

  3. Restart the pods that perform backups, so that DS can obtain the revised set of backup instances:

    $ kubectl delete pods ds-idrepo-1
    $ kubectl delete pods ds-cts-0
  4. Change the frequency of idrepo backups and the starting time of cts backups:

    1. Open the /path/to/forgeops/bin/schedule-backups.sh script.

    2. To back up the idrepo directory at the start of every hour, and at the thirtieth minute of every hour, change the line:

      BACKUP_SCHEDULE_IDREPO="0 * * * *"

      to:

      BACKUP_SCHEDULE_IDREPO="*/30 * * * *"
    3. To back up the cts directory at 20 minutes after the hour, change the line:

      BACKUP_SCHEDULE_CTS="10 * * * *"

      to:

      BACKUP_SCHEDULE_CTS="20 * * * *"
    4. Save your changes.

  5. Run the schedule-backups.sh script.

    $ /path/to/forgeops/bin/schedule-backups.sh prod

    The schedule-backups.sh script stops any previously scheduled backup jobs before initiating the new schedule.

CDM Restore

Before you attempt to restore data from backups, make sure that you’ve implemented cloud secret management. DS instances on which you restore data must have the same master key as DS instances on which you perform backups. If you don’t share the master key, you won’t be able to restore from your backups.

This page covers three options to restore data from backups:

New CDM Using DS Backup

Creating new instances from previously backed up DS data is useful when a system disaster occurs, or when directory services are lost. It is also useful when you want to port test environment data to a production deployment.

To create new DS instances with data from a previous backup:

  1. Make sure that your current Kubernetes context references the CDM cluster and the prod namespace.

  2. Update the YAML file used by the CDM to create Kubernetes secrets that contain your cloud storage credentials:

    On Google Cloud
    $ kubectl create secret generic cloud-storage-credentials \
     --from-file=GOOGLE_CREDENTIALS_JSON=/path/to/my-sa-credential.json \
     --dry-run --output yaml > /path/to/forgeops/kustomize/base/7.0/ds/base/cloud-storage-credentials.yaml

    In this example, specify the path and file name of the JSON file that contains the Google service account key for my-sa-credential.json.

    On AWS
    $ kubectl create secret generic cloud-storage-credentials \
     --from-literal=AWS_ACCESS_KEY_ID=my-access-key \
     --from-literal=AWS_SECRET_ACCESS_KEY=my-secret-access-key \
     --dry-run --output yaml > /path/to/forgeops/kustomize/base/7.0/ds/base/cloud-storage-credentials.yaml
    On Azure
    $ kubectl create secret generic cloud-storage-credentials \
     --from-literal=AZURE_ACCOUNT_NAME=my-storage-account-name \
     --from-literal=AZURE_ACCOUNT_KEY=my-storage-account-access-key \
     --dry-run --output yaml > /path/to/forgeops/kustomize/base/7.0/ds/base/cloud-storage-credentials.yaml
  3. Configure the backup bucket location and enable the automatic restore capability:

    1. Change to the /path/to/forgeops/kustomize/base/kustomizeConfig directory.

    2. Open the kustomization.yaml file.

    3. Set the DSBACKUP_DIRECTORY parameter to the location of the backup bucket. For example:

      On Google Cloud

      DSBACKUP_DIRECTORY "gs://my-backup-bucket"

      On AWS

      DSBACKUP_DIRECTORY "s3://my-backup-bucket"

      On Azure

      DSBACKUP_DIRECTORY "az://my-backup-bucket"

    4. Set the AUTORESTORE_FROM_DSBACKUP parameter to "true".

  4. Deploy the platform.

  5. Remove your credentials from the YAML file that the CDM uses to create Kubernetes secrets:

    $ kubectl create secret generic cloud-storage-credentials \
     --dry-run --output yaml > /path/to/forgeops/kustomize/base/7.0/ds/base/cloud-storage-credentials.yaml

When the platform is deployed, new DS pods are created, and the data is automatically restored from the most recent backup available in the cloud storage location you have configured.

To verify that the data has been restored:

  • Use the IDM UI or platform UI.

  • Review the logs for the DS pods' initialize container. For example:

    $ kubectl logs --container initialize ds-idrepo-0
Restore All DS Directories

To restore all the DS directories in your CDM deployment from backup:

  1. Delete all the PVCs attached to DS pods using the kubectl delete pvc command.

  2. Because PVCs might not get deleted immediately when the pods to which they’re attached are running, stop the DS pods.

    Using separate terminal windows, stop every DS pod using the kubectl delete pod command. This deletes the pods and their attached PVCs.

    Kubernetes automatically restarts the DS pods after you delete them. The automatic restore feature of CDM recreates the PVCs as the pods restart by retrieving backup data from cloud storage and restoring the DS directories from the latest backup.

  3. After the DS pods have come up, restart IDM pods to reconnect IDM to the restored PVCs:

    1. List all the pods in the prod namespace.

    2. Delete all the pods running IDM.

Restore One DS Directory

In a CDM deployment that has automatic restore enabled, you can recover a failed DS pod if the latest backup is within the replication purge delay:

  1. Delete the PVC attached to the failed DS pod using the kubectl delete pvc command.

  2. Because the PVC might not get deleted immediately if the attached pod is running, stop the failed DS pod.

    In another terminal window, stop the failed DS pod using the kubectl delete pod command. This deletes the pod and its attached PVC.

    Kubernetes automatically restarts the DS pod after you delete it. The automatic restore feature of CDM recreates the PVC as the pod restarts by retrieving backup data from cloud storage and restoring the DS directory from the latest backup.

  3. If the DS instance that you restored was the ds-idrepo instance, restart IDM pods to reconnect IDM to the restored PVC:

    1. List all the pods in the prod namespace.

    2. Delete all the pods running IDM.

For information about how to manually restore DS where the latest available backup is older than the replication purge delay, see the Restore section in the DS documentation.

Best Practices for Restoring Directories
  • Use a backup that is newer than the last replication purge.

  • When you restore a DS replica using backups that are older than the purge delay, that replica will no longer be able to participate in replication.

    Reinitialize the replica to restore the replication topology.

  • If the available backups are older than the purge delay, then initialize the DS replica from an up-to-date master instance. For more information on how to initialize a replica, see Manual Initialization in the DS documentation.

CDM Monitoring

The CDM uses Prometheus to monitor ForgeRock Identity Platform components and Kubernetes objects, Prometheus Alertmanager to send alert notifications, and Grafana to analyze metrics using dashboards.

This topic describes the use of monitoring tools in the CDM:

Monitoring Pods

The following Prometheus and Grafana pods from the prometheus-operator project run in the monitoring namespace:

Pod Description

alertmanager-prometheus-operator-kube-p-alertmanager-0

Handles Prometheus alerts by grouping them together, filtering them, and then routing them to a receiver, such as a Slack channel.

prometheus-operator-kube-state-metrics-...

Generates Prometheus metrics for cluster node resources, such as CPU, memory, and disk usage. One pod is deployed for each CDM node.

prometheus-operator-prometheus-node-exporter-...

Generates Prometheus metrics for Kubernetes objects, such as deployments and nodes.

prometheus-operator-grafana-...

Provides the Grafana service.

prometheus-prometheus-operator-kube-p-prometheus-0

Provides the Prometheus service.

prometheus-operator-kube-p-operator-...

Runs the Prometheus operator.

See the prometheus-operator Helm chart README file for more information about the pods in the preceding table.

Custom Grafana Dashboards

In addition to the pods from the prometheus-operator project, the CDM includes a set of Grafana dashboards. The import-dashboards-... pod from the forgeops repository runs after Grafana starts up. This pod imports Grafana dashboards for the ForgeRock Identity Platform and terminates after importing has completed.

You can customize, export and import Grafana dashboards using the Grafana UI or HTTP API.

For information about importing custom Grafana dashboards, see the Import Custom Grafana Dashboards section of the Prometheus and Grafana Deployment README file in the forgeops repository.

Alerts

CDM alerts are defined in the fr-alerts.yaml file in the forgeops repository.

To configure additional alerts, see the Configure Alerting Rules section of the Prometheus and Grafana Deployment README file in the forgeops repository.

CDM Security

This topic describes several options for securing a CDM deployment of the ForgeRock Identity Platform:

Secret Agent Operator

The open source Secret Agent operator randomly generates all secrets for AM, IDM, and DS services running in the CDK and the CDM. The Secret Agent operator runs as a Kubernetes deployment that must be available before AM, IDM, and DS are deployed. In addition to generating secrets, the operator integrates with Google Cloud Secret Manager, AWS Secrets Manager, and Azure Key Vault to manage secrets, providing cloud backup and retrieval for secrets.

Secret Generation

By default, the operator examines your namespace to determine whether it contains all the secrets required for ForgeRock Identity Platform deployment. If any of the required secrets are not present, the operator generates them.

See the Secret Agent project README for information about:

Cloud Secret Management

Configuring the Secret Agent operator to integrate with a cloud secret manager, such as Google Cloud Secret Manager, AWS Secret Manager, or Azure Key Vault, changes the operator’s behavior:

  • First, the operator examines your namespace to determine whether it contains all the secrets required for ForgeRock Identity Platform deployment.

  • If any of the required secrets are not in your namespace, the operator checks to see if the missing secrets are available in the cloud secret manager:

    • If any of the secrets missing from your namespace are available in the cloud secret manager, the operator gets them from the cloud secret manager and adds them to your namespace.

    • If missing secrets are not available in the cloud secret manager, the Secret Agent operator generates them.

See the Secret Agent project README for information about how to integrate the Secret Agent operator with these cloud secret managers:

Before deploying the ForgeRock Identity Platform in production, you must configure the Secret Agent operator to support cloud secret management. If you do not do so, you run the risk of not being able to access your directory data. Because directory data is encrypted by secrets that have been generated by the operator, loss of your secrets will result in data loss.
Administration Password Changes

The CDM uses six administration passwords:

  • The AM and IDM administration user, amadmin

  • The AM CTS service account, uid=openam_cts,ou=admins,ou=famrecords,ou=openam-session,ou=tokens

  • The shared identity repository service account, uid=am-identity-bind-account,ou=admins,ou=identities

  • The DS root user, uid=admin

  • RCS Agent passwords:

    • The password that RCS server instances use to connect to the RCS Agent

    • The password that IDM instances use to connect to the RCS Agent

Some organizations have a requirement to change administration passwords from time to time. Follow these steps if you need to change the CDM administration passwords:

  1. Ensure that you have configured Cloud Secret Management in your deployment.

    Cloud secret management is required when deploying the platform in production on Google Cloud, AWS, or Azure.

  2. Change the amadmin user’s password:

    1. Run the print-secrets command from the bin directory in your forgeops repository clone. Note the current password for the amadmin user.

    2. Delete the entry that contains the amadmin user’s password from the cloud secret manager:

      Google Cloud

      List the secrets managed by the cloud secret manager, locate the URI for the secret that contains the AM-PASSWORDS-AMADMIN-CLEAR password, and delete it. For example:

      $ gcloud secrets list --uri
      $ gcloud secrets delete \
       https://secretmanager.googleapis.com/. . ./prod-am-env-secrets-AM-PASSWORDS-AMADMIN-CLEAR
      AWS

      List the secrets managed by the cloud secret manager, locate the ARN for the secret that contains the AM-PASSWORDS-AMADMIN-CLEAR password, and delete it. For example:

      $ aws secretsmanager list-secrets --region=my-region
      $ aws secretsmanager delete-secret --region=my-region \
       --force-delete-without-recovery \
       --secret-id arn:aws:secretsmanager:. . .:prod-am-env-secrets-AM-PASSWORDS-AMADMIN-CLEAR-c3KfsL
      Azure

      Soft delete the secret that contains the AM-PASSWORDS-AMADMIN-CLEAR password from Azure Key Vault. For example:

      $ az keyvault secret delete --vault-name my-key-vault --name prod-am-env-secrets-AM-PASSWORDS-AMADMIN-CLEAR

      Purge the soft deleted secret from Azure Key Vault. For example:

      $ az keyvault secret purge --vault-name my-key-vault --name prod-am-env-secrets-AM-PASSWORDS-AMADMIN-CLEAR
    3. Delete the Kubernetes secret that contains the amadmin user’s password from the prod namespace:

      $ kubens prod
      $ kubectl patch secrets am-env-secrets --type=json \
       --patch='[{"op":"remove", "path": "/data/AM_PASSWORDS_AMADMIN_CLEAR"}]'
    4. Restart AM by deleting all active AM pods: list all the pods in the prod namespace, and then delete all the pods running AM.

    5. After AM comes up, run the print-secrets command again to get the current administration passwords.

      Verify that the amadmin user’s password has changed by comparing its previous value to its current value.

    6. Verify that you can log in to the platform UI using the new password.

  3. Change the CTS service account’s password:

    1. Change to the bin directory in your forgeops repository clone.

    2. Run the print-secrets command. Note the current password for the identity repository service account.

    3. Delete the entry that contains this account’s password from the cloud secret manager:

      Google Cloud

      List the secrets managed by the cloud secret manager, locate the URI for the secret that contains the AM_STORES_CTS_PASSWORD password, and delete it. For example:

      $ gcloud secrets list --uri
      $ gcloud secrets delete \
       https://secretmanager.googleapis.com/. . ./prod-ds-env-secrets-AM_STORES_CTS_PASSWORD
      AWS

      List the secrets managed by the cloud secret manager, locate the ARN for the secret that contains the AM_STORES_CTS_PASSWORD password, and delete it. For example:

      $ aws secretsmanager list-secrets --region=my-region
      $ aws secretsmanager delete-secret --region=my-region \
       --force-delete-without-recovery \
       --secret-id arn:aws:secretsmanager:. . .:prod-ds-env-secrets-AM_STORES_CTS_PASSWORD-1d4432
      Azure

      Soft delete the secret that contains the AM_STORES_CTS_PASSWORD password from Azure Key Vault. For example:

      $ az keyvault secret delete --vault-name my-key-vault --name prod-ds-env-secrets-AM_STORES_CTS_PASSWORD

      Purge the deleted secret from Azure Key Vault. For example:

      $ az keyvault secret purge --vault-name my-key-vault --name prod-ds-env-secrets-AM_STORES_CTS_PASSWORD
    4. Delete the Kubernetes secret that contains the service account’s password from the prod namespace:

      $ kubens prod
      $ kubectl patch secrets ds-env-secrets --type=json \
       --patch='[{"op":"remove", "path": "/data/AM_STORES_CTS_PASSWORD"}]'
    5. Redeploy the platform:

      $ cd /path/to/forgeops
      $ skaffold delete --profile small; skaffold run --profile small
    6. After the platform comes up, run the print-secrets command again to get the current administration passwords.

      Verify that the CTS service account’s password has changed by comparing its previous value to its current value.

  4. Change the identity repository service account’s password:

    1. Change to the bin directory in your forgeops repository clone.

    2. Run the print-secrets command. Note the current password for the the identity repository service account.

    3. Delete the entry that contains this account’s password from the cloud secret manager:

      Google Cloud

      List the secrets managed by the cloud secret manager, locate the URI for the secret that contains the AM_STORES_USER_PASSWORD password, and delete it. For example:

      $ gcloud secrets list --uri
      $ gcloud secrets delete \
       https://secretmanager.googleapis.com/. . ./prod-ds-env-secrets-AM_STORES_USER_PASSWORD
      AWS

      List the secrets managed by the cloud secret manager, locate the ARN for the secret that contains the AM_STORES_USER_PASSWORD password, and delete it. For example:

      $ aws secretsmanager list-secrets --region=my-region
      $ aws secretsmanager delete-secret --region=my-region \
       --force-delete-without-recovery \
       --secret-id arn:aws:secretsmanager:. . .:prod-ds-env-secrets-AM_STORES_USER_PASSWORD-1d4432
      Azure

      Soft delete the secret that contains the AM_STORES_USER_PASSWORD password from Azure Key Vault. For example:

      $ az keyvault secret delete --vault-name my-key-vault --name prod-ds-env-secrets-AM_STORES_USER_PASSWORD

      Purge the deleted secret from Azure Key Vault. For example:

      $ az keyvault secret purge --vault-name my-key-vault --name prod-ds-env-secrets-AM_STORES_USER_PASSWORD
    4. Delete the Kubernetes secret that contains the service account’s password from the prod namespace:

      $ kubens prod
      $ kubectl patch secrets ds-env-secrets --type=json \
       --patch='[{"op":"remove", "path": "/data/AM_STORES_USER_PASSWORD"}]'
    5. Redeploy the platform:

      $ cd /path/to/forgeops
      $ skaffold delete --profile small; skaffold run --profile small
    6. After the platform comes up, run the print-secrets command again to get the current administration passwords.

      Verify that the identity repository service account’s password has changed by comparing its previous value to its current value.

  5. Change the DS root user’s password:

    1. Change to the bin directory in your forgeops repository clone.

    2. Run the print-secrets command. Note the current password for the uid=admin account.

    3. Delete the entry that contains this account’s password from the cloud secret manager:

      Google Cloud

      List the secrets managed by the cloud secret manager, locate the URI for the secret that contains the dirmanager-pw password, and delete it. For example:

      $ gcloud secrets list --uri
      $ gcloud secrets delete \
       https://secretmanager.googleapis.com/. . ./prod-ds-passwords-dirmanager-pw
      AWS

      List the secrets managed by the cloud secret manager, locate the ARN for the secret that contains the dirmanager-pw password, and delete it. For example:

      $ aws secretsmanager list-secrets --region=my-region
      $ aws secretsmanager delete-secret --region=my-region \
       --force-delete-without-recovery \
       --secret-id arn:aws:secretsmanager:. . .:prod-ds-passwords-dirmanager-pw-2eeaa0
      Azure

      Soft delete the secret that contains the dirmanager-pw password from Azure Key Vault. For example:

      $ az keyvault secret delete --vault-name my-key-vault --name prod-ds-passwords-dirmanager-pw

      Purge the deleted secret from Azure Key Vault. For example:

      $ az keyvault secret purge --vault-name my-key-vault --name prod-ds-passwords-dirmanager-pw
    4. Delete the Kubernetes secret that contains the service account’s password from the prod namespace:

      $ kubens prod
      $ kubectl patch secrets ds-passwords --type=json \
       --patch='[{"op":"remove", "path": "/data/dirmanager.pw"}]'
    5. Redeploy the platform:

      $ cd /path/to/forgeops
      $ skaffold delete --profile small; skaffold run --profile small
    6. After the platform comes up, run the print-secrets command again to get the current administration passwords.

      Verify that the password for the uid=admin account has changed by comparing its previous value to its current value.

  6. Change the RCS Agent password:

    1. Change to the bin directory in your forgeops repository clone.

    2. Run the print-secrets command. Note the current password that’s listed as the rcs-agent RCS secret.

    3. Delete the entry that contains this password from the cloud secret manager:

      Google Cloud

      List the secrets managed by the cloud secret manager, locate the URI for the secret that contains the AGENT_RCS_SECRET password, and delete it. For example:

      $ gcloud secrets list --uri
      $ gcloud secrets delete \
       https://secretmanager.googleapis.com/. . ./prod-rcs-agent-env-secrets-AGENT_RCS_SECRET
      AWS

      List the secrets managed by the cloud secret manager, locate the ARN for the secret that contains the AGENT_RCS_SECRET password, and delete it. For example:

      $ aws secretsmanager list-secrets --region=my-region
      $ aws secretsmanager delete-secret --region=my-region \
       --force-delete-without-recovery \
       --secret-id arn:aws:secretsmanager:. . .:prod-rcs-agent-env-secrets-AGENT_RCS_SECRET-440800
      Azure

      Soft delete the secret that contains the AGENT_RCS_SECRET password from Azure Key Vault. For example:

      $ az keyvault secret delete --vault-name my-key-vault --name prod-rcs-agent-env-secrets-AGENT_RCS_SECRET

      Purge the deleted secret from Azure Key Vault. For example:

      $ az keyvault secret purge --vault-name my-key-vault --name prod-rcs-agent-env-secrets-AGENT_RCS_SECRET
    4. Delete the Kubernetes secret that contains the service account’s password from the prod namespace:

      $ kubens prod
      $ kubectl patch secrets rcs-agent-env-secrets --type=json \
       --patch='[{"op":"remove", "path": "/data/AGENT_RCS_SECRET"}]'
    5. Restart the RCS Agent by deleting the RCS Agent pod.

    6. After the RCS Agent comes up, run the print-secrets command again to get the current administration passwords.

      Verify that the RCS Agent’s password has changed by comparing its previous value to its current value.

    7. Configure all of your connectors that communicate to IDM through the agent to use the new password.

  7. Change the password that the RCS Agent uses to connect to IDM:

    1. Change to the bin directory in your forgeops repository clone.

    2. Run the print-secrets command. Note the current password that’s listed as the rcs-agent IDM secret.

    3. Delete the entry that contains this password from the cloud secret manager:

      Google Cloud

      List the secrets managed by the cloud secret manager, locate the URI for the secret that contains the AGENT_IDM_SECRET password, and delete it. For example:

      $ gcloud secrets list --uri
      $ gcloud secrets delete \
       https://secretmanager.googleapis.com/. . ./prod-rcs-agent-env-secrets-AGENT_IDM_SECRET
      AWS

      List the secrets managed by the cloud secret manager, locate the ARN for the secret that contains the AGENT_IDM_SECRET password, and delete it. For example:

      $ aws secretsmanager list-secrets --region=my-region
      $ aws secretsmanager delete-secret --region=my-region \
       --force-delete-without-recovery \
       --secret-id arn:aws:secretsmanager:. . .:prod-rcs-agent-env-secrets-AGENT_IDM_SECRET-a501c0
      Azure

      Soft delete the secret that contains the AGENT_IDM_SECRET password from Azure Key Vault. For example:

      $ az keyvault secret delete --vault-name my-key-vault --name prod-rcs-agent-env-secrets-AGENT_IDM_SECRET

      Purge the deleted secret from Azure Key Vault. For example:

      $ az keyvault secret purge --vault-name my-key-vault --name prod-rcs-agent-env-secrets-AGENT_IDM_SECRET
    4. Delete the Kubernetes secret that contains the service account’s password from the prod namespace:

      $ kubens prod
      $ kubectl patch secrets rcs-agent-env-secrets --type=json \
       --patch='[{"op":"remove", "path": "/data/AGENT_IDM_SECRET"}]'
    5. Restart IDM by deleting all active IDM pods: list all the pods in the prod namespace, and then delete all the pods running IDM.

    6. Restart the RCS Agent by deleting the RCS Agent pod.

    7. After IDM and the RCS Agent come up, run the print-secrets command again to get the current administration passwords.

      Verify that the password that IDM uses to connect to the RCS Agent has changed by comparing its previous value to its current value.

Secure HTTP and Secure LDAP

The CDK and CDM enable secure communication with ForgeRock Identity Platform services using a TLS-enabled ingress controller. Incoming requests and outgoing responses are encrypted. TLS is terminated at the ingress controller.

Inbound communication to DS instances occurs over secure LDAP (LDAPS).

You can configure communication with ForgeRock Identity Platform services other than directory services using one of the following options:

  • Over HTTPS using a self-signed certificate. Communication is encrypted, but users will receive warnings about insecure communication from some browsers.

  • Over HTTPS using a certificate with a trust chain that starts at a trusted root certificate. Communication is encrypted, and users will not receive warnings from their browsers.

  • Over HTTPS using a dynamically obtained certificate from Let’s Encrypt. Communication is encrypted and users will not receive warnings from their browsers. A cert-manager pod installed in your Kubernetes cluster calls Let’s Encrypt to obtain a certificate, and then automatically installs a Kubernetes secret.

You install a Helm chart from the cert-manager project to provision certificates. By default, the pod issues a self-signed certificate. You can also configure the pod to issue a certificate with a trust chain that begins at a trusted root certificate, or to dynamically obtain a certificate from Let’s Encrypt.

Certificate Management Automation

In the CDM, certificate management is provided by the cert-manager add-on. The certificate manager deployed in CDM generates a self-signed certificate to secure CDM communication.

In your own deployment, you can specify a different certificate issuer or DNS challenge provider by changing values in the ingress.yaml file.

For more information about configuring certificate management, see the cert-manager documentation.

Access Restriction by IP Address

When installing the ingress controller in production environments, you should consider configuring a CIDR block in the Helm chart for the ingress controller so that you restrict access to worker nodes from a specific IP address or a range of IP addresses.

To specify a range of IP addresses allowed to access resources controlled by the ingress controller, specify the --set controller.service.loadBalancerSourceRanges=your IP range option when you install your ingress controller.

For example:

$ helm install --namespace nginx --name nginx \
 --set rbac.create=true \
 --set controller.publishService.enabled=true \
 --set controller.stats.enabled=true \
 --set controller.service.externalTrafficPolicy=Local \
 --set controller.service.type=LoadBalancer \
 --set controller.image.tag="0.21.0" \
 --set controller.service.annotations."service\.beta\.kubernetes\.io/aws-load-balancer-type"="nlb" \
 --set controller.service.loadBalancerSourceRanges="{81.0.0.0/8,3.56.113.4/32}" \
 stable/nginx-ingress

Network Policies

Kubernetes network policies let you specify specify how pods are allowed to communicate with other pods, namespaces, and IP addresses.

Network Policies Example

The forgeops repository contains an example with six network policies for the ForgeRock Identity Platform. These network policies are in the netpolicies.yaml file, part of a Kustomize base named security.

Customize this example to meet your security needs, or use it to help you better understand how network policies can make Kubernetes deployments more secure.

Deploy the Example

The forgeops repository’s skaffold.yaml file contains a Skaffold profile named security that references the Kustomize security base. To deploy the platform with the example network policies, run:

$ cd /path/to/forgeops
$ skaffold run --profile security
About the Example Network Policies

All the example policies have the value Ingress in the spec.policyTypes key:

spec:
  policyTypes:
  - Ingress

Network policies with this policy type are called ingress policies, because they limit ingress traffic in a deployment.

deny-all Policy

By default, if no network policies exist in a namespace, then all ingress and egress traffic is allowed to and from pods in that namespace.

The deny-all policy modifies the default network policy for ingress. If a pod isn’t selected by another network policy in the namespace, ingress is not allowed.

For information about how Kubernetes controls pod ingress when pods are selected by multiple network policies in a namespace, see the Kubernetes documentation.

ds-idrepo-ldap Policy

The ds-idrepo-ldap policy limits access to ds-idrepo pods. Access can only be requested over port 1389, 1636, or 8080, and must come from an am, idm, or amster pod.

This part of the network policy specifies that access must be requested over port 1389, 1636, or 8080:

ingress:
- from:
  . . .
  ports:
  - protocol: TCP
    port: 1389
  - protocol: TCP
    port: 1636
  - protocol: TCP
    port: 8080

This part of the network policy specifies that access must be from an am, idm, or amster pod:

ingress:
- from:
  - podSelector:
      matchExpressions:
      - key: app
        operator: In
        values:
        - am
        - idm
        - amster

Understanding the example network policies and how to customize them requires some knowledge about labels defined in CDM deployments. For example, am pods are defined with a label, app, that has the value am. You’ll find this label in /path/to/forgeops/kustomize/base/am/kustomization.yaml file:

commonLabels:
  app.kubernetes.io/name: am
  app.kubernetes.io/instance: am
  app.kubernetes.io/component: am
  app.kubernetes.io/part-of: forgerock
  tier: middle
  app: am
ds-cts-ldap Policy

The ds-cts-ldap policy limits access to ds-cts pods. Access can only be requested over port 1389, 1636, or 8080, and must come from an am or amster pod.

ds-replication Policy

ds pods in CDM deployments are labeled with tier: ds; they’re said to reside in the ds tier of the deployment.

The ds-replication policy limits access to the pods on the ds tier. This policy specifies that access to ds tier pods over port 8989 can only come from other pods in the same tier.

Note that port 8989 is the default DS replication port. This network policy ensures that only DS pods can access the replication port.

backend-http-access Policy

The backend-http-access policy limits access to the pods in the middle tier, which contains the am, idm, and ig pods. Access can only be requested over port 8080.

front-end-http-access Policy

The front-end-http-access policy limits access to the pods in the ui tier: the login-ui, admin-ui, and end-user-ui pods. Access can only be requested over port 8080.

Note that users send HTTPS requests for the ForgeRock UIs to the ingress controller over port 443. The ingress controller terminates TLS, and then forwards requests to the UI pods over port 8080.

Cluster Access for Multiple AWS Users

It’s common for team members to share the use of a cluster. For team members to share a cluster, the cluster owner must grant access to each user:

  1. Get the ARNs and names of users who need access to your cluster.

  2. Set the Kubernetes context to your Amazon EKS cluster.

  3. Edit the authorization configuration map for the cluster using the kubectl edit command:

    $ kubectl edit -n kube-system configmap/aws-auth
  4. Under the mapRoles section, insert the mapUser section. An example is shown here with the following parameters:

    • The user ARN is arn:aws:iam::012345678901:user/new.user.

    • The user name registered in AWS is new.user.

      …​ mapUsers: |
          - userarn: arn:aws:iam::012345678901:user/new.user
            username: new.user
            groups:
              - system:masters
      …​
  5. For each additional user, insert the - userarn: entry in the mapUsers: section:

    …​ mapUsers: |
        - userarn: arn:aws:iam::012345678901:user/new.user
          username: new.user
          groups:
            - system:masters
        - userarn: arn:aws:iam::901234567890:user/second.user
          username: second.user
          groups:
            - system:masters
    …​
  6. Save the configuration map.

CDM Benchmarks

The benchmarking instructions in this part of the documentation give you a method to validate performance of your CDM deployment.

The benchmarking techniques we present are a lightweight example, and are not a substitute for load testing a production deployment. Use our benchmarking techniques to help you get started with the task of constructing your own load tests.

Remember, the CDM is a reference implementation and not for production use. When you create a project plan, you’ll need to think about how you’ll put together production-quality load tests that accurately measure your own deployment’s performance.

About CDM Benchmarking

CDM Benchmarks provides instructions for running lightweight benchmarks to give you a means for validating your own CDM deployment.

The Cloud Deployment Team runs the same benchmark tests. Our results are available upon request from ForgeRock. To get them, contact your ForgeRock sales representative.

We conduct our tests using the configurations specified for small, medium, and large CDM clusters. We create our clusters using the techniques described in the CDM documentation.

Next, we create test users:

  • 1,000,000 test users for a small cluster.

  • 10,000,000 test users for a medium cluster.

  • 100,000,000 test users for a large cluster.

Finally, we run tests that measure authentication rates and OAuth 2.0 authorization code flow performance.

If you follow the same method of deploying the CDM and running benchmarks, the results you obtain should be similar to ForgeRock’s results. However, factors beyond the scope of the CDM, or a failure to use our documented sizing and configuration, may affect your benchmark test results. These factors might include (but are not limited to): updates to cloud platform SDKs; changes to third-party software required for Kubernetes; changes you have made to sizing or configuration to suit your business needs.

The CDM is designed to:

  • Conform to DevOps best practices

  • Facilitate continuous integration and continuous deployment

  • Scale and deploy on any Kubernetes environment in the cloud

If you require higher performance than the benchmarks reported here, you can scale your deployment horizontally and vertically. Vertically scaling ForgeRock Identity Platform works particularly well in the cloud. For more information about scaling your deployment, contact your qualified ForgeRock partner or technical consultant.

Next Step

Third-Party Software

The Cloud Deployment Team used Gradle 6.8.3 to benchmark the CDM. Before you start running benchmarks, install this version of Gradle in your local environment.

Earlier and later versions will probably work. If you want to try using another version, it is your responsibility to validate it.

In addition to Gradle, you’ll need all the third-party software required to deploy the CDM:

Next Step

Test User Generation

Running the Authentication Rate and OAuth 2.0 Authorization Code Flow benchmarks requires a set of test users. This page provides instructions for generating a set of test users suitable for these two lightweight AM benchmarks. Note that these test users are not necessarily suitable for other benchmarks or load tests, and that they can’t be used with IDM.

For Small and Medium Clusters

To generate test users for lightweight AM benchmarks for small and medium clusters, to provision the CDM userstores, and to prime the directory servers:

  1. Make sure your Kubernetes context is set to the cluster in which the CDM is deployed, and that prod is the current namespace.

  2. Obtain the password for the directory superuser, uid=admin:

    $ cd /path/to/forgeops/bin
    $ ./print-secrets dsadmin

    Make a note of this password. You’ll need it for subsequent steps in this procedure.

  3. Change to the directory that contains the source for the dsutil Docker container:

    $ cd /path/to/forgeops/docker/7.0/ds/dsutil

    You’ll generate test users from a pod you create from the dsutil container.

  4. Build and push the dsutil Docker container to your container registry, and then run the container.

    The my-registry parameter varies, depending on the location of your registry:

    $ docker build --tag=my-registry/dsutil .
    $ docker push my-registry/dsutil
    $ kubectl run -it dsutil --image=my-registry/dsutil --restart=Never -- bash

    The kubectl run command creates the dsutil pod, and leaves you in a shell that lets you run commands in the pod.

  5. Generate the test users—1,000,000 users for a small CDM cluster, and 10,000,000 for a medium cluster:

    Run these substeps from the dsutil pod’s shell:

    1. Make an LDIF file that has the number of user entries for your cluster size:

      For example, for a small cluster:

      $ /opt/opendj/bin/makeldif -o data/entries.ldif \
       -c numusers=1000000 config/MakeLDIF/ds-idrepo.template
      Processed 1000 entries
      Processed 2000 entries
      Processed 3000 entries
      . . .
      Processed 1000000 entries
      LDIF processing complete. 1000003 entries written

      When the Cloud Deployment Team ran the makeldif script, it took approximately:

      • 30 seconds to run on a small cluster.

      • 4 minutes to run on a medium cluster.

    2. Create the user entries in the directory:

      $ /opt/opendj/bin/ldapmodify \
       -h ds-idrepo-0.ds-idrepo -p 1389 --useStartTls --trustAll \
       -D "uid=admin" -w directory-superuser-password --noPropertiesFile \
       --no-prompt --continueOnError --numConnections 10 data/entries.ldif

      ADD operation successful messages appear as user entries are added to the directory.

      When the Cloud Deployment Team ran the ldapmodify command, it took approximately:

      • 15 minutes to run on a small cluster.

      • 2 hours 35 minutes to run on a medium cluster.

  6. Prime the directory servers:

    1. Open a new terminal window or tab.

      Use this new terminal window—not the one running the dsutil pod’s shell—for the remaining substeps in this step.

    2. Prime the directory server running in the ds-idrepo-0 pod:

      1. Start a shell that lets you run commands in the ds-idrepo-0 pod:

        $ kubectl exec ds-idrepo-0 -it -- bash
      2. Run the following command:

        $ ldapsearch -D "uid=admin" -w directory-superuser-password \
         -p 1636 -b "ou=identities"  uid=user.*  | grep dn: | wc -l
        10000000
      3. Exit from the id-dsrepo-0 pod’s shell:

        $ exit
    3. Prime the directory server running in the ds-idrepo-1 pod.

For Large Clusters

Here are some very general steps you can follow if you want to generate test users for benchmarking or load testing a large cluster:

  1. Install DS in a VM in the cloud.

  2. Run the makeldif and ldapmodify commands, as described above.

  3. Back up your directory.

  4. Upload the backup files to cloud storage.

  5. Restore a CDM idrepo pod from your backup, following the steps outlined in CDM Restore.

Next Step

Authentication Rate

The AMRestAuthNSim.scala simulation tests authentication rates using the REST API. It measures the throughput and response times of an AM server performing REST authentications when AM is configured to use CTS-based sessions.

To run the simulation:

  1. Make sure the userstore is provisioned, and the Directory Services cache is primed.

  2. Set environment variables that specify the host on which to run the test, the number of concurrent threads to spawn when running the test, the duration of the test (in seconds), the first part of the user ID, and the user password, and the number of users for the test:

    $ export TARGET_HOST=prod.iam.example.com
    $ export CONCURRENCY=100
    $ export DURATION=60
    $ export USER_PREFIX=user.
    $ export USER_PASSWORD=T35tr0ck123
    $ export USER_POOL=n-users

    where n-users is 1000000 for a small cluster, 10000000 for a medium cluster, and 100000000 for a large cluster.

  3. Configure AM for CTS-based sessions:

    1. Log in to the platform console as the amadmin user. For details, see AM Services.

    2. Go to the native AM console.

    3. Select the top level realm.

    4. Select Properties.

    5. Make sure the Use Client-based Sessions option is disabled.

      If it’s not disabled, disable it, and then select Save Changes.

  4. Change to the /path/to/forgeops/docker/gatling directory.

  5. Run the simulation:

    $ gradle clean; gradle gatlingRun-am.AMRestAuthNSim

    When the simulation is complete, the name of a file containing the test results appears near the end of the output.

  6. Open the file containing the test results in a browser to review the results.

Next Step

OAuth 2.0 Authorization Code Flow

The AMAccessTokenSim.scala simulation tests OAuth 2.0 authorization code flow performance. It measures the throughput and response time of an AM server performing authentication, authorization, and session token management when AM is configured to use client-based sessions, and OAuth 2.0 is configured to use client-based tokens. In this test, one transaction includes all three operations.

To run the simulation:

  1. Make sure the userstore is provisioned, and the Directory Services cache is primed.

  2. Set environment variables that specify the host on which to run the test, the number of concurrent threads to spawn when running the test, the duration of the test (in seconds), the first part of the user ID, and the user password, and the number of users for the test:

    $ export TARGET_HOST=prod.iam.example.com
    $ export CONCURRENCY=100
    $ export DURATION=60
    $ export USER_PREFIX=user.
    $ export USER_PASSWORD=T35tr0ck123
    $ export USER_POOL=n-users

    where n-users is 1000000 for a small cluster, 10000000 for a medium cluster, and 100000000 for a large cluster.

  3. Configure AM for CTS-based sessions:

    1. Log in to the platform console as the amadmin user. For details, see AM Services.

    2. Go to the native AM console.

    3. Select the top level realm.

    4. Select Properties.

    5. Make sure the Use Client-based Sessions option is disabled.

      If it’s not disabled, disable it, and then select Save Changes.

  4. Configure AM for CTS-based OAuth2 tokens:

    1. Select Realms > Top Level Realm.

    2. Select Services > OAuth2 Provider.

    3. Make sure the Use Client-based Access & Refresh Tokens option is disabled.

      If it’s not disabled, disable it, and then select Save Changes.

  5. Change to the /path/to/forgeops/docker/gatling directory.

  6. Run the simulation:

    $ gradle clean; gradle gatlingRun-am.AMAccessTokenSim

    When the simulation is complete, the name of a file containing the test results appears near the end of the output.

  7. Open the file containing the test results in a browser to review the results.

Congratulations!

You’ve successfully run the CDM lightweight benchmark tests.

Troubleshooting

Kubernetes deployments are multi-layered and often complex.

Errors and misconfigurations can crop up in a variety of places. Performing a logical, systematic search for the source of a problem can be daunting.

Here are some tools you can use to troubleshoot problems with CDK and CDM deployments:

Problem Troubleshooting Tool

I’m having name resolution or other DNS issues.

Use diagnostic tools in the debug tools container.

I want to run DS utilities without disturbing a DS pod.

Use DS tools in the debug tools container.

The kubectl command requires too much typing.

Enable kubectl tab autocompletion.

Here are some techniques you can use to troubleshoot problems with CDK and CDM deployments:

Problem Troubleshooting Technique

Pods in the CDK or CDM don’t start up as expected.

Review pod descriptions and container logs.

See if your cluster is resource-constrained. Check for underconfigured clusters by using the kubectl describe nodes and kubectl get events -w commands. Pods killed with out of memory (OOM) conditions indicate that your cluster is underconfigured.

Make sure that you’re using tested versions of third-party software.

Simplify your deployment. Install ForgeRock Identity Platform components separately, instead of installing all the components with a single command. Then, make sure each component works correctly before installing the next component:

   For the CDK, use staged deployment.

   For the CDM, use each individual component’s Skaffold profile.

All the pods have started, but you can’t reach the services running in them.

Make sure you don’t have any ingress issues.

Changes you’ve made to ForgeRock’s Kustomize files don’t work as expected.

Fully expand the Kustomize output, and then examine the output for unintended effects.

Your Minikube deployment doesn’t work.

Make sure that you don’t have a problem with virtual hardware requirements.

Skaffold doesn’t run as expected.

If Skaffold cannot push a Docker image, review your push setup.

For other problems with Skaffold, you can try increasing Skaffold’s logging verbosity.

DS Diagnostic Tools

The debug tools container, named ds-util, provides a suite of diagnostic tools that you can execute inside of a running Kubernetes cluster.

The container has two types of tools:

  • DS tools. A DS instance is installed in the /opt/opendj directory of the ds-util container. DS tools, such as the ldapsearch and ldapmodify commands, are available in the /opt/opendj/bin directory.

  • Miscellaneous diagnostic tools. A set of diagnostic tools, including dig, netcat, nslookup, curl, and vi, have been installed in the container. The file, /path/to/forgeops/docker/7.0/ds/dsutil/Dockerfile, has the list of operating system packages that have been installed in the debug tools container.

To start the debug tools container:

$ kubectl run -it ds-util --image=gcr.io/forgeops-public/ds-util — bash

After you start the tools container, a command prompt appears:

root@ds-util:/opt/opendj#

You can access all the tools available in the container from this prompt. For example:

root@ds-util:/opt/opendj# nslookup am
Server:		10.96.0.10
Address:	10.96.0.10#53

Name:	am.my-namespace.svc.cluster.local
Address: 10.100.20.240

Staged CDK Installation

By default, the cdk install command installs the entire ForgeRock Identity Platform in the CDK’s namespace.

You can also install the platform in stages to help troubleshoot deployment issues.

To install the platform in stages:

  1. Verify that the namespace in which the CDK is deployed is set in your Kubernetes context.

  2. Install the base and ds components first. Other components have dependencies on these two components:

    1. Install the platform base component:

      $ cd /path/to/forgeops/bin
      $ ./cdk install base --fqdn dev.example.com
      Checking secret-agent operator and related CRDs: secret-agent CRD not found. Installing secret-agent.
      namespace/secret-agent-system created
      . . .
      
      Waiting for secret agent operator…​
      customresourcedefinition.apiextensions.k8s.io/secretagentconfigurations.secret-agent.secrets.forgerock.io condition met
      deployment.apps/secret-agent-controller-manager condition met
      pod/secret-agent-controller-manager-694f9dbf65-52cbt condition met
      
      Checking ds-operator and related CRDs: ds-operator CRD not found. Installing ds-operator.
      namespace/fr-system created
      customresourcedefinition.apiextensions.k8s.io/directoryservices.directory.forgerock.io created
      . . .
      
      Waiting for ds-operator…​
      customresourcedefinition.apiextensions.k8s.io/directoryservices.directory.forgerock.io condition met
      deployment.apps/ds-operator-ds-operator condition met
      pod/ds-operator-ds-operator-f974dd8fc-55mxw condition met
      
      Installing component(s): ['base']
      
      configmap/dev-utils created
      configmap/platform-config created
      Warning: networking.k8s.io/v1beta1 Ingress is deprecated in v1.19+, unavailable in v1.22+; use networking.k8s.io/v1 Ingress
      ingress.networking.k8s.io/end-user-ui created
      ingress.networking.k8s.io/forgerock created
      ingress.networking.k8s.io/ig-web created
      ingress.networking.k8s.io/login-ui created
      ingress.networking.k8s.io/platform-ui created
      secretagentconfiguration.secret-agent.secrets.forgerock.io/forgerock-sac created
      
      Waiting for K8s secrets
      Waiting for secret: am-env-secrets …​done
      Waiting for secret: idm-env-secrets …​…​done
      Waiting for secret: rcs-agent-env-secrets …​done
      Waiting for secret: ds-passwords .done
      Waiting for secret: ds-env-secrets .done
      
      Relevant passwords:
      . . .
      
      Relevant URLs:
      https://dev.example.com/platform
      https://dev.example.com/admin
      https://dev.example.com/am
      https://dev.example.com/enduser
      
      Enjoy your deployment!
    2. After you’ve installed the base component, install the ds component:

      $ ./cdk install ds
      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): ['ds']
      
      directoryservice.directory.forgerock.io/ds-idrepo created
      
      Enjoy your deployment!
  3. Install the other ForgeRock Identity Platform components. You can either install all the other components by using the cdk install apps command, or install them separately:

    1. Install AM:

      $ ./cdk install am
      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): ['am']
      
      service/am created
      deployment.apps/am created
      
      Enjoy your deployment!
    2. Install Amster:

      $ ./cdk install amster
      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): ['amster']
      
      job.batch/amster created
      
      Enjoy your deployment!
    3. Install IDM:

      $ ./cdk install idm
      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!
    4. Install the RCS Agent:

      $ ./cdk install rcs-agent
      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): ['rcs-agent']
      
      configmap/rcs-agent-config-properties created
      configmap/rcs-agent-logging-properties created
      service/rcs-agent created
      deployment.apps/rcs-agent created
      
      Enjoy your deployment!
  4. Install the user interface components. You can either install all the applications by using the cdk install ui command, or install them separately:

    1. Install the administration UI:

      $ ./cdk install admin-ui
      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): ['admin-ui']
      
      service/admin-ui created
      deployment.apps/admin-ui created
      
      Enjoy your deployment!
    2. Install the login UI:

      $ ./cdk install login-ui
      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): ['login-ui']
      
      service/login-ui created
      deployment.apps/login-ui created
      
      Enjoy your deployment!
    3. Install the end user UI:

      $ ./cdk install end-user-ui
      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): ['end-user-ui']
      
      service/end-user-ui created
      deployment.apps/end-user-ui created
      
      Enjoy your deployment!
  5. In a separate terminal tab or window, run the kubectl get pods command to monitor status of the deployment. Wait until all the pods are ready.

    Your namespace should have the pods shown in this diagram.

Multiple Component Installation

You can specify multiple components with a single cdk install command. For example, to install the base, ds, am, and amster components:

$ ./cdk install base ds am amster

kubectl Shell Autocompletion

The kubectl shell autocompletion extension lets you extend the Tab key completion feature of Bash and Zsh shells to the kubectl commands. While not a troubleshooting tool, this extension can make troubleshooting easier, because it lets you enter kubectl commands more easily.

For more information about the Kubernetes autocompletion extension, see Enabling shell autocompletion in the Kubernetes documentation.

Note that to install the autocompletion extension in Bash, you must be running version 4 or later of the Bash shell. To determine your bash shell version, run the bash --version command.

Logs and Other Diagnostics

Look at pod descriptions and container log files for irregularities that indicate problems.

Pod descriptions contain information about active Kubernetes pods, including their configuration, status, containers (including containers that have finished running), volume mounts, and pod-related events.

Container logs contain startup and run-time messages that might indicate problem areas. Each Kubernetes container has its own log that contains all output written to stdout by the application running in the container. The am container logs are especially important for troubleshooting AM issues in Kubernetes deployments. AM writes its debug logs to stdout. Therefore, the am container logs include all the AM debug logs.

Here’s an example of how you can use pod descriptions and container logs to troubleshoot. Events in the pod description indicate that Kubernetes was unsuccessful in pulling a Docker image required to run a container. You can review your Docker registry’s configuration to determine whether a misconfiguration caused the problem.

The debug-logs command generates the following HTML-formatted output, which you can view in a browser:

  • Descriptions of all the Kubernetes pods running the ForgeRock Identity Platform in your namespace

  • Logs for all of the containers running in these pods

Perform the following steps to run the debug-logs command and view the output in a browser:

  1. Make sure that your namespace is the current namespace in your Kubernetes context.

  2. Make sure you’ve checked out the release/7.1.0 branch of the forgeops repository.

  3. Change to the /path/to/forgeops/bin directory in your forgeops repository clone.

  4. Run the debug-logs command:

    $ ./debug-logs
    
    Open /tmp/forgeops/log.html in your browser.
  5. In a browser, go to the URL shown in the debug-logs output. For example, file:///tmp/forgeops/log.html. The browser displays a screen with a link for each ForgeRock Identity Platform pod in your namespace:

    Screen shot of debug-logs command output.
  6. (Optional) To access the information for a pod, select its link from the start of the debug-logs output.

    Selecting the link takes you to the pod’s description. Logs for each of the pod’s containers follow the pod’s description.

  7. (Optional) To modify the output to contain the latest updates to the pod descriptions and container logs, run the debug-logs command again, and then refresh your browser.

After you’ve obtained the pod descriptions and container logs, here are some things to look for:

  • Examine each pod’s event log for failures.

  • If a Docker image could not be pulled, verify that the Docker image name and tag are correct. If you are using a private registry, verify that your image pull secret is correct.

  • Examine the init containers. Did each init container complete with a zero (success) exit code? If not, examine the logs from that failed init container using the kubectl logs pod-xxx -c init-container-name command.

  • Look at the pods' logs to see if the main container entered a crashloop.

Third-Party Software Versions

ForgeRock recommends installing tested versions of third-party software in environments where you’ll run the CDK and the CDM.

See the tables that list the tested versions of third-party software for your deployment:

If you used Homebrew to install third-party software, you can use the following commands to obtain software versions:

  • Homebrew: brew list --versions

  • Homebrew casks: brew list --cask --versions

Ingress Issues

If the CDK or CDM pods are starting successfully, but you can’t reach the services in those pods, you probably have ingress issues.

To diagnose ingress issues:

  1. Use the kubectl describe ing and kubectl get ing ingress-name -o yaml commands to view the ingress object.

  2. Describe the service using the kubectl get svc; kubectl describe svc xxx command. Does the service have an Endpoint: binding? If the service endpoint binding is not present, the service did not match any running pods.

Expanded Kustomize Output

If you’ve modified any of the Kustomize bases and overlays that come with the cdk canonical configuration, you might want to see how your changes affect deployment. Use the kustomize build command to see how Kustomize expands your bases and overlays into YAML files.

For example:

$ cd /path/to/forgeops/kustomize/overlay/7.0
$ kustomize build all
2020/10/02 11:07:53 well-defined vars that were never replaced: DOMAIN,DSBACKUP_DIRECTORY,DSBACKUP_HOSTS,NAMESPACE,SUBDOMAIN,AUTORESTORE_FROM_DSBACKUP
apiVersion: v1
data:
  IDM_ENVCONFIG_DIRS: /opt/openidm/resolver
  LOGGING_PROPERTIES: /var/run/openidm/logging/logging.properties
  OPENIDM_ANONYMOUS_PASSWORD: anonymous
  OPENIDM_CLUSTER_REMOVE_OFFLINE_NODE_STATE: "true"
  OPENIDM_CONFIG_REPO_ENABLED: "false"
  PROJECT_HOME: /opt/openidm
kind: ConfigMap
metadata:
  labels:
    app: idm
    app.kubernetes.io/name: forgerock
    component: idm
    tier: middle
    vendor: forgerock
  name: idm
  namespace: prod
---
apiVersion: v1
data:
  logging.properties: |
    # Properties file that configures the operation of the JDK
    # logging facility.
    # The system will look for this configuration file, first using
    # a System property specified at startup:
    #
    # >java -Djava.util.logging.config.file=myLoggingConfigFilePath
    #
. . .

Minikube Hardware Resources

Cluster Configuration

The cluster-up command example in Minikube Cluster provides a good default virtual hardware configuration for a Minikube cluster running the CDK.

Disk Space

When the Minikube cluster runs low on disk space, it acts unpredictably. Unexpected application errors can appear.

Verify that adequate disk space is available by logging in to the Minikube cluster and running a command to display free disk space:

$ minikube ssh
$ df -h
Filesystem      Size  Used Avail Use% Mounted on
devtmpfs        3.9G     0  3.9G   0% /dev
tmpfs           3.9G     0  3.9G   0% /dev/shm
tmpfs           3.9G  383M  3.6G  10% /run
tmpfs           3.9G     0  3.9G   0% /sys/fs/cgroup
tmpfs           3.9G   64K  3.9G   1% /tmp
/dev/sda1        25G  7.7G   16G  33% /mnt/sda1
/Users          465G  219G  247G  48% /Users
$ exit
logout

In the preceding example, 16 GB of disk space is available on the Minikube cluster.

Skaffold Troubleshooting

Push Setup

If the skaffold run command fails because it does not have permissions to push a Docker image, it may be trying to push to the Docker hub. The reported image name will be something like docker.io/am.

When running on Minikube, Skaffold assumes that a push is not required, because it can docker build directly to the Docker machine. If it is attempting to push to Docker Hub, it is because Skaffold thinks it is not running on Minikube. Make sure your Minikube context is named minikube.

An alternate solution is to modify the Docker build in skaffold.yaml and set the value of the local.push key to false. For more information, see the Skaffold documentation.

Logging Verbosity

Skaffold provides different levels of debug logging information. When you encounter issues deploying the platform with Skaffold, you can set the logging verbosity to display more messages. The additional messages might help you identify problems.

For example:

$ cd /path/to/forgeops
$ skaffold dev -v debug
INFO[0000] starting gRPC server on port 50051
INFO[0000] starting gRPC HTTP server on port 50052
INFO[0000] Skaffold &{Version:v0.38.0 ConfigVersion:skaffold/v1beta14 GitVersion: GitCommit:1012d7339d0055ab93d7f88e95b7a89292ce77f6 GitTreeState:clean BuildDate:2020-09-13T02:16:09Z GoVersion:go1.13 Compiler:gc Platform:darwin/amd64}
DEBU[0000] config version (skaffold/v1beta12) out of date: upgrading to latest (skaffold/v1beta14)
DEBU[0000] found config for context "minikube"
DEBU[0000] Defaulting build type to local build
DEBU[0000] validating yamltags of struct SkaffoldConfig
DEBU[0000] validating yamltags of struct Metadata
. . .

Technology Previews

DS Operator

The DS operator is currently in technology preview status for production deployments. Do not use the operator in production deployments of the platform.

The DS operator is supported in developer and demonstration deployments. The cdk install ds command checks to see whether the DS operator is present in your cluster, and installs it if it’s not.

The DS operator uses the Kubernetes operator design pattern to let you easily deploy and manage DS instances running in a Kubernetes cluster. After you install the ds-operator custom resource definition (CRD) in a cluster, you can use it to create DS instances, scale them, and manage backup and restore.

To deploy the platform by using the DS operator, install the CDK (not the legacy CDK). During installation, progress messages indicate that the cdk command installs the DS operator:

Checking ds-operator and related CRDs: ds-operator CRD not found. Installing ds-operator.
namespace/fr-system created
customresourcedefinition.apiextensions.k8s.io/directoryservices.directory.forgerock.io created
role.rbac.authorization.k8s.io/ds-operator-leader-election-role created
clusterrole.rbac.authorization.k8s.io/ds-operator-directoryservice-editor-role created
clusterrole.rbac.authorization.k8s.io/ds-operator-manager-role created
rolebinding.rbac.authorization.k8s.io/ds-operator-leader-election-rolebinding created
clusterrolebinding.rbac.authorization.k8s.io/ds-operator-directoryservice-editor-rolebinding created
clusterrolebinding.rbac.authorization.k8s.io/ds-operator-manager-rolebinding created
deployment.apps/ds-operator-ds-operator created

Waiting for ds-operator…​
customresourcedefinition.apiextensions.k8s.io/directoryservices.directory.forgerock.io condition met
deployment.apps/ds-operator-ds-operator condition met
pod/ds-operator-ds-operator-f974dd8fc-z4vx8 condition met
. . .
Deploying ds.yaml. This is includes all directory resources.
directoryservice.directory.forgerock.io/ds-idrepo created
. . .

After you get the CDK up and running, you can explore the DS operator. Some things you might try:

  • Show the operator’s status:

    $ kubectl describe directoryservice
    
    Name:         ds-idrepo
    Namespace:    my-namespace
    Labels:       app.kubernetes.io/component=directory
                  app.kubernetes.io/instance=ds-idrepo
                  app.kubernetes.io/name=ds
                  app.kubernetes.io/part-of=forgerock
    Annotations:  <none>
    API Version:  directory.forgerock.io/v1alpha1
    Kind:         DirectoryService
    Metadata:
      Creation Timestamp:  2021-05-18T23:18:27Z
      Generation:          2
      Managed Fields:
        API Version:  directory.forgerock.io/v1alpha1
        Fields Type:  FieldsV1
        fieldsV1:
          f:metadata:
            f:annotations:
              .:
              f:kubectl.kubernetes.io/last-applied-configuration:
            f:labels:
              .:
              f:app.kubernetes.io/component:
              f:app.kubernetes.io/instance:
              f:app.kubernetes.io/name:
              f:app.kubernetes.io/part-of:
          f:spec:
            .:
            f:image:
            f:keystores:
              .:
              f:keyStoreSecretName:
            f:passwords:
              .:
              f:uid=admin:
                .:
                f:key:
                f:secretName:
              f:uid=am-config,ou=admins,ou=am-config:
    . . .
  • Scale one or both of the DS pods. For example:

    $ kubectl scale directoryservice/ds-idrepo --replicas=2
    
    directoryservice.directory.forgerock.io/ds-idrepo scaled
  • Modify DS properties:

    $ kubectl edit directoryservice/ds-idrepo

    For example, you could modify the backup properties (under spec) to enable backups, or to change the backup interval.

  • Take a volume snapshot. For more information, see Volume Snapshots (Preview) in the DS operator README.

Legacy Features

Cloud Developer’s Kit Documentation

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

The CDK is a minimal sample deployment of the ForgeRock Identity Platform. If you have access to a cluster on Google Cloud, EKS, or AKS, you can install the CDK in a namespace on your cluster. But even if you don’t have access to a cloud-based cluster, you can deploy the CDK locally in a standalone environment called Minikube, and when you’re done, you’ll have a local Kubernetes cluster with the platform installed on it.

About the Cloud Developer's Kit

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

The CDK is a minimal sample deployment for development purposes. It includes fully integrated AM, IDM, and DS installations, and randomly generated secrets. Developers deploy the CDK, and then access AM’s and IDM’s GUI consoles and REST APIs to configure the platform and build customized Docker images for the platform.

This documentation describes how to use the CDK to stand up the platform in your developer environment, then create and test customized Docker images containing your custom AM and IDM configurations:

Illustrates the major configuration tasks performed before deploying in production.

Customizing the platform using the CDK is one of the major activities required before deploying the platform in production. To better understand how this activity fits in to the overall deployment process, see Configure the Platform.

Containerization

The CDK uses Docker for containerization. The CDK leverages the following Docker capabilities:

  • File-Based Representation of Containers. Docker images contain a file system and run-time configuration information. Docker containers are running instances of Docker images.

  • Modularization. Docker images are based on other Docker images. For example, an AM image is based on a Tomcat image that is itself based on an OpenJDK JRE image. In this example, the AM container has AM software, Tomcat software, and the OpenJDK JRE.

  • Collaboration. Public and private Docker registries let users collaborate by providing cloud-based access to Docker images. Continuing with the example, the public Docker registry at https://hub.docker.com/ has Docker images for Tomcat and the OpenJDK JRE that any user can download. You build Docker images for the ForgeRock Identity Platform based on the Tomcat and OpenJDK JRE images in the public Docker registry. You can then push the Docker images to a private Docker registry that other users in your organization can access.

ForgeRock provides a set of unsupported, evaluation-only base images for the ForgeRock Identity Platform. These images are available in ForgeRock’s public Docker registry.

Developers working with the CDK use the base images from ForgeRock to build customized Docker images for a fully-configured ForgeRock Identity Platform deployment:

Brief overview of containers for developers.

Users working with the CDM also use the base images from ForgeRock to perform proof-of-concept deployments.

Except for several Docker images that implement user interface elements, the base images from ForgeRock are evaluation-only. They are unsupported for production use. Because of this, you must build your own base images before you deploy in production:

Brief overview of containers in production.

For information about how to build base images for deploying the ForgeRock Identity Platform in production, see Base Docker Images.

Orchestration

The CDK uses Kubernetes for container orchestration. The CDK has been tested on the following Kubernetes implementations:

Next Step

CDK Architecture: Minikube

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

The CDK uses Skaffold to trigger Docker image builds and Kubernetes orchestration. Here’s what Skaffold does:

  1. Calls the Docker client on the local computer to build and tag their customized Docker images for the ForgeRock Identity Platform. The customized images are based on Docker images in ForgeRock’s public Docker registry, gcr.io/forgerock-io.

  2. Pushes the Docker images to the Docker engine that’s part of the Minikube VM.

  3. Calls Kustomize to orchestrate the ForgeRock Identity Platform in your namespace. Kustomize uses the Docker images that Skaffold pushed to your Docker registry.

The following diagram illustrates how the CDK uses Skaffold to build and orchestrate Docker images on Minikube:

CDK users run Skaffold and Kustomize to deploy pods into a Kubernetes cluster on a local VM.

After deploying the ForgeRock Identity Platform, you’ll see the following pods running in your namespace:

Diagram of the deployed ${cdk.abbr}.
am

The am pod runs AM.

When AM starts, it obtains its configuration from the /home/forgerock/openam/config directory [24].

After the am pod has started, an Amster job is triggered. This job populates AM’s run-time data.

ds-cts-0

The ds-cts-0 pod runs the directory service used by the AM Core Token Service.

ds-idrepo-0

The ds-idrepo-0 pod runs the following directory services:

  • Identity repository shared by AM and IDM

  • IDM repository

  • AM application and policy store

idm

The idm pod runs IDM.

When IDM starts, it obtains its configuration from the /opt/openidm/conf directory [25].

In containerized deployments, IDM must retrieve its configuration from the file system and not from the IDM repository. The default values for the openidm.fileinstall.enabled and openidm.config.repo.enabled properties in the CDK’s system.properties file ensure that IDM retrieves its configuration from the file system. Do not override the default values for these properties.

UI pods

Several pods provide access to ForgeRock common user interfaces:

  • admin-ui

  • end-user-ui

  • login-ui

In addition to these pods, you’ll see that two jobs that load data into the environment have run to completion:

  • The amster job, which loads application data, such as OAuth 2.0 client definitions, to the idrepo DS instance.

  • The ldif-importer job, which loads policy data required by AM to the the idrepo DS instance.

The CDK also requires two other services that are external to your namespace:

  • Minikube’s ingress controller plugin, for providing external access to services in the Minikube cluster.

  • ForgeRock’s Secret Agent operator, for generating and managing Kubernetes secrets.

Next Step

CDK Architecture: Shared Cloud Cluster

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

A shared cluster lets multiple developers deploy and configure the ForgeRock Identity Platform on a single cloud-based Kubernetes cluster. A Kubernetes administrator sets up the shared cluster, then provides details to the developers so that they can access the cluster. Each developer then works in their own isolated environment within the cluster, called a namespace.

The CDK uses Skaffold to trigger Docker image builds and Kubernetes orchestration. Here’s what Skaffold does:

  1. Calls the Docker client on the local computer to build and tag their customized Docker images for the ForgeRock Identity Platform. The customized images are based on Docker images in ForgeRock’s public Docker registry, gcr.io/forgerock-io.

  2. Pushes the Docker images to a Docker registry accessible to the shared cluster.

  3. Calls Kustomize to orchestrate the ForgeRock Identity Platform in your namespace. Kustomize uses the Docker images that Skaffold pushed to your Docker registry.

The following diagram illustrates how the CDK uses Skaffold to build Docker images locally, push them to a shared registry, and orchestrate them in a shared cluster:

Diagram of a development environment that uses a shared cluster.

After deploying the ForgeRock Identity Platform, you’ll see the following pods running in your namespace:

Diagram of the deployed CDK.
am

The am pod runs AM.

When AM starts, it obtains its configuration from the /home/forgerock/openam/config directory [26].

After the am pod has started, an Amster job is triggered. This job populates AM’s run-time data.

ds-cts-0

The ds-cts-0 pod runs the directory service used by the AM Core Token Service.

ds-idrepo-0

The ds-idrepo-0 pod runs the following directory services:

  • Identity repository shared by AM and IDM

  • IDM repository

  • AM application and policy store

idm

The idm pod runs IDM.

When IDM starts, it obtains its configuration from the /opt/openidm/conf directory [27].

In containerized deployments, IDM must retrieve its configuration from the file system and not from the IDM repository. The default values for the openidm.fileinstall.enabled and openidm.config.repo.enabled properties in the CDK’s system.properties file ensure that IDM retrieves its configuration from the file system. Do not override the default values for these properties.

UI pods

Several pods provide access to ForgeRock common user interfaces:

  • admin-ui

  • end-user-ui

  • login-ui

In addition to these pods, you’ll see that two jobs that load data into the environment have run to completion:

  • The amster job, which loads application data, such as OAuth 2.0 client definitions, to the idrepo DS instance.

  • The ldif-importer job, which loads policy data required by AM to the the idrepo DS instance.

The CDK also requires three other services that are external to your namespace. These services must be installed by your cluster administrator before you attempt to install the CDK in your shared cluster:

  • An NGINX ingress controller, for providing external access to services in the shared cluster.

  • Certificate manager, for obtaining and installing security certificates.

  • ForgeRock’s Secret Agent operator, for generating and managing Kubernetes secrets.

Next Step

Environment Setup: Minikube

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Before deploying the CDK, you must set up your local environment with a Minikube cluster.

Windows users

ForgeRock supports deploying the CDK and CDM using macOS and Linux. If you have a Windows computer, you’ll need to create a Linux VM. We tested using the following configurations:

  • Hypervisor: Hyper-V, VMWare Player, or VMWare Workstation

  • Guest OS: Ubuntu 19.10 with 12 GB memory and 60 GB disk space

  • Nested virtualization enabled in the Linux VM.

Perform all the procedures in this documentation within the Linux VM. In this documentation, the local computer refers to the Linux VM for Windows users.

The Minikube implementation on Windows Subsystem for Linux (WSL2) has networking issues. As a result, consistent access to the ingress controller or the apps deployed on Minikube is not possible. This issue is tracked here. Do not deploy CDK or CDM on WSL2 until this issue is resolved.

forgeops Repository

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Before you can deploy the CDK or the CDM, you must first get the forgeops repository and check out the release/7.1.0 branch:

  1. Clone the forgeops repository. For exmple:

    $ git clone https://github.com/ForgeRock/forgeops.git

    The forgeops repository is a public Git repository. You do not need credentials to clone it.

  2. Check out the release/7.1.0 branch:

    $ cd forgeops
    $ git checkout release/7.1.0

Depending on your organization’s repository strategy, you might need to clone the repository from a fork, instead of cloning ForgeRock’s master repository. You might also need to create a working branch from the release/7.1.0 branch. For more information, see Repository Updates.

Next Step

Third-Party Software

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Before installing the CDK, you must obtain non-ForgeRock software and install it on your local computer.

ForgeRock recommends that you install third-party software using Homebrew on macOS and Linux[28] .

The versions listed in the following table have been validated for building custom Docker images for the ForgeRock Identity Platform. Earlier and later versions will probably work. If you want to try using versions that are not in the tables, it is your responsibility to validate them.

Install all of the following third-party software:

Software Version Homebrew package

Python 3

3.9.6

python

Kubernetes client (kubectl)

1.21.2

kubectl

Kubernetes context switcher (kubectx)

0.9.3

kubectx

Kustomize

4.2.0

kustomize

VirtualBox

6.1.22

virtualbox (cask)[3]

Minikube

1.23.2

minikube

Docker Desktop[29]

3.6.0

docker (cask)[3]

Skaffold

1.26.1

skaffold

Next Step

Minikube Virtual Machine

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Minikube is a tool that runs a single-node Kubernetes cluster in a virtual machine.

The following configuration has been validated for building custom Docker images for the ForgeRock Identity Platform using Minikube:

  • Kubernetes version: 1.21.4.

  • Memory: 10 GB or more.

  • Disk space: 40 GB or more.

To set up Minikube:

  1. Use the minikube start command to create a Minikube VM. In this example, the Minikube VM is created with a Kubernetes cluster suitable for building custom Docker images for the ForgeRock Identity Platform:

    $ minikube start --memory=12288 --cpus=3 --disk-size=40g --cni=true --vm=true \
     --driver=virtualbox --bootstrapper kubeadm --kubernetes-version=1.21.4 
    😄  minikube v1.23.2 on Darwin 11.5.1
    ✨  Using the virtualbox driver based on user configuration
    💿  Downloading VM boot image …​
        > minikube-v1.23.1.iso.sha256: 65 B / 65 B [-------------] 100.00% ? p/s 0s
        > minikube-v1.23.1.iso: 225.22 MiB / 225.22 MiB [ 100.00% 4.00 MiB p/s 1m2s
    👍  Starting control plane node minikube in cluster minikube
    🔥  Creating virtualbox VM (CPUs=3, Memory=12288MB, Disk=40960MB) …​
    🐳  Preparing Kubernetes v1.21.4 on Docker 20.10.6 …​
        ▪ Generating certificates and keys …​
        ▪ Booting up control plane …​
        ▪ Configuring RBAC rules …​
    🔗  Configuring CNI (Container Networking Interface) …​
        ▪ Using image gcr.io/k8s-minikube/storage-provisioner:v5
    🌟  Enabled addons: default-storageclass, storage-provisioner
    🔎  Verifying Kubernetes components. . .
    🏄  Done! kubectl is now configured to use "minikube" by default
  2. Run the following command to enable the ingress controller built into Minikube:

    $ minikube addons enable ingress
        ▪ Using image k8s.gcr.io/ingress-nginx/controller:v0.44.0
        ▪ Using image docker.io/jettech/kube-webhook-certgen:v1.5.1
        ▪ Using image docker.io/jettech/kube-webhook-certgen:v1.5.1
    🔎  Verifying ingress addon…​
    🌟  The 'ingress' addon is enabled
  3. Install the Secret Agent operator:

    $ kubectl apply -f https://github.com/ForgeRock/secret-agent/releases/latest/download/secret-agent.yaml
    namespace/secret-agent-system created
    customresourcedefinition.apiextensions.k8s.io/secretagentconfigurations.secret-agent.secrets.forgerock.io created
    serviceaccount/secret-agent-manager-service-account created
    role.rbac.authorization.k8s.io/secret-agent-leader-election-role created
    clusterrole.rbac.authorization.k8s.io/secret-agent-manager-role created
    rolebinding.rbac.authorization.k8s.io/secret-agent-leader-election-rolebinding created
    clusterrolebinding.rbac.authorization.k8s.io/secret-agent-manager-rolebinding created
    service/secret-agent-webhook-service created
    deployment.apps/secret-agent-controller-manager created
    Warning: admissionregistration.k8s.io/v1beta1 MutatingWebhookConfiguration is deprecated in v1.16+, unavailable in v1.22+; use admissionregistration.k8s.io/v1 MutatingWebhookConfiguration
    mutatingwebhookconfiguration.admissionregistration.k8s.io/secret-agent-mutating-webhook-configuration created
    Warning: admissionregistration.k8s.io/v1beta1 ValidatingWebhookConfiguration is deprecated in v1.16+, unavailable in v1.22+; use admissionregistration.k8s.io/v1 ValidatingWebhookConfiguration
    validatingwebhookconfiguration.admissionregistration.k8s.io/secret-agent-validating-webhook-configuration created
Next Step

Namespace

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Create a namespace in your new cluster.

ForgeRock recommends that you deploy the ForgeRock Identity Platform in a namespace other than the default namespace. Deploying to a non-default namespace lets you separate workloads in a cluster. Separating a workload into a namespace lets you delete the workload easily; just delete the namespace.

To create a namespace:

  1. Create a namespace in your Kubernetes cluster:

    $ kubectl create namespace my-namespace
    namespace/my-namespace created
  2. Make the new namespace your active namespace:

    $ kubens my-namespace
    Context "minikube" modified.
    Active namespace is "my-namespace".
Next Step

Hostname Resolution

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Set up hostname resolution for the ForgeRock Identity Platform servers you’ll deploy in your namespace.

  1. Run the minikube ip command to get the Minikube ingress controller’s IP address:

    $ minikube ip
    192.168.99.100
  2. Add an entry to the /etc/hosts file to resolve the deployment FQDN. For example:

    minikube-ip-address my-namespace.iam.example.com
Next Step

TLS Certificate (Optional)

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

This page covers several options you can use to encrypt HTTP communications over TLS in CDK deployments.

Self-Signed Certificate

By default, Minikube’s ingress controller plugin is configured with a self-signed certificate. This is the simplest encryption option—you don’t have to make any changes to the CDK to get encryption.

However, when you access one of the ForgeRock web applications from your browser, you’ll get a "Not Secure" message from your browser. You’ll need to bypass the message.

Certificate From a Certificate Authority (CA)

If you have a certificate from a CA, you can use the certificate for TLS encryption. Install the certificate and your private key in a Kubernetes secret in your namespace. Minikube’s ingress controller plugin gets the certificate from the secret, and then uses it to encrypt communications.

To use a certficate from a CA in a CDK deployment on Minikube:

  1. Obtain the certificate:

    • Make sure that the certificate is PEM-encoded.

    • A best practice is to include the entire trust chain in your .pem file.

    • Make sure that the certificate’s host name works with the FQDN you’ll use when you deploy the platform.

      In the CDK, the deployment FQDN is set to my-namespace.iam.example.com by default. But you’ll want to use a certificate with your own domain, not with example.com. Because of this:

      • When you deploy the CDK. you’ll need to change the deployment FQDN to use your own domain name. For example, change my-namespace.iam.example.com to my-namespace.iam.my-domain.com.

      • Your certificate should also specify this host name. If you’re using a wildcard certificate that could be used by multiple developers, the certificate’s host name should be *.iam.my-domain.com.

      • Note that you can deploy the CDK with a deployment FQDN that does not include the subdomain iam. You might want to do this if you have a wildcard certificate for *.my-domain.com. However, ForgeRock recommends that you use a subdomain, such as iam, in your deployment FQDN when possible. Using a subdomain can help you avoid FQDN collisions, provide simpler routing, and simplify DNS.

  2. Create a secret named sslcert in your namespace that contains the certificate. For example:

    $ kubectl create secret tls sslcert --cert=/path/to/my-cert.crt --key=/path/to/my-key.key
Certificate Generated by the mkcert Utility

If you don’t have a certificate from a CA, you can use the mkcert utility to generate a locally trusted certificate. In many cases, it’s acceptable to use such certificates for development purposes.

To use a certificate generated by the mkcert utility in a CDK deployment on Minikube:

  1. If you don’t have mkcert software installed locally, install it. Firefox users also need to install certutil software. See the mkcert installation instructions for more information.

  2. If you haven’t ever done so, run the mkcert -install command to create a local certificate authority (CA) and install it in your system root store. Restart your browser after creating the local CA.

  3. Create a wildcard certificate for the iam.example.com domain:

    $ cd
    $ mkcert "*.iam.example.com"
  4. Create a secret named sslcert in your namespace that contains the wildcard certificate. For example:

    $ kubectl create secret tls sslcert --cert=./_wildcard.iam.example.com.pem --key=./_wildcard.iam.example.com-key.pem
Next Step

Minikube’s Docker Engine

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Set up your local environment to execute docker commands on Minikube’s Docker engine.

ForgeRock recommends using the built-in Docker engine when developing custom Docker images using Minikube. When you use Minikube’s engine, you don’t have to build Docker images on a local engine and then push the images to a local or cloud-based Docker registry. Instead, you build images using the same Docker engine that Minikube uses. This streamlines development.

To set up your local computer to use Minikube’s Docker engine:

  1. Run the docker-env command in your shell:

    $ eval $(minikube docker-env)
  2. Stop Skaffold from pushing Docker images to a remote Docker registry [30]:

    $ skaffold config set --kube-context minikube local-cluster true
    set value local-cluster to true for context minikube

For more information about using Minikube’s built-in Docker engine, see Use local images by re-using the Docker daemon in the Minikube documentation.

Next Step

You’ve completed all the setup tasks for Minikube. Now you’re ready to deploy the platform in the Minikube cluster:

Environment Setup: Shared Cloud Cluster

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Before deploying the CDK, you must set up your local environment to communicate with the shared cluster.

Windows users

ForgeRock supports deploying the CDK and CDM using macOS and Linux. If you have a Windows computer, you’ll need to create a Linux VM. We tested using the following configurations:

  • Hypervisor: Hyper-V, VMWare Player, or VMWare Workstation

  • Guest OS: Ubuntu 19.10 with 12 GB memory and 60 GB disk space

  • Nested virtualization enabled in the Linux VM.

Perform all the procedures in this documentation within the Linux VM. In this documentation, the local computer refers to the Linux VM for Windows users.

The Minikube implementation on Windows Subsystem for Linux (WSL2) has networking issues. As a result, consistent access to the ingress controller or the apps deployed on Minikube is not possible. This issue is tracked here. Do not deploy CDK or CDM on WSL2 until this issue is resolved.

forgeops Repository

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Before you can deploy the CDK or the CDM, you must first get the forgeops repository and check out the release/7.1.0 branch:

  1. Clone the forgeops repository. For exmple:

    $ git clone https://github.com/ForgeRock/forgeops.git

    The forgeops repository is a public Git repository. You do not need credentials to clone it.

  2. Check out the release/7.1.0 branch:

    $ cd forgeops
    $ git checkout release/7.1.0

Depending on your organization’s repository strategy, you might need to clone the repository from a fork, instead of cloning ForgeRock’s master repository. You might also need to create a working branch from the release/7.1.0 branch. For more information, see Repository Updates.

Next Step

Third-Party Software

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Before installing the CDK, you must obtain non-ForgeRock software and install it on your local computer.

ForgeRock recommends that you install third-party software using Homebrew on macOS and Linux[31] .

The versions listed in the table below have been validated for building custom Docker images for the ForgeRock Identity Platform. Earlier and later versions will probably work. If you want to try using versions that are not in the table, it is your responsibility to validate them.

Install the following third-party software:

Software Version Homebrew package

Python 3

3.9.6

python

Kubernetes client (kubectl)

1.21.2

kubectl

Kubernetes context switcher (kubectx)

0.9.3

kubectx

Kustomize

4.2.0

kustomize

Google Cloud SDK

354.0.0

google-cloud-sdk (cask)[3]

Docker Desktop[32]

3.6.0

docker (cask)[3]

Skaffold

1.26.1

skaffold

Next Step

Cluster Details

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

You’ll need to get some information about the cluster from your cluster administrator. You’ll provide this information as you perform various tasks to access the cluster.

  1. Obtain the following cluster details:

    • The name of the Google Cloud project that contains the cluster.

    • The cluster name.

    • The Google Cloud zone in which the cluster resides.

    • The IP address of your cluster’s ingress controller.

    • The location of the Docker registry from which your cluster will obtain images for the ForgeRock Identity Platform.

  2. Verify that the Secret Agent operator is installed in the cluster.

Next Step

Context for the Shared Cluster

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Kubernetes uses contexts to access Kubernetes clusters. Before you can access the shared cluster, you must create a context on your local computer if it’s not already present.

To create a context for the shared cluster:

  1. Run the kubectx command and review the output. The current Kubernetes context is highlighted:

    • If the current context references the shared cluster, there is nothing further to do. Proceed to Namespace.

    • If the context of the shared cluster is present in the kubectx command output, set the context as follows:

      $ kubectx my-context
      Switched to context "my-context".

      After you have set the context, proceed to Namespace.

    • If the context of the shared cluster is not present in the kubectx command output, continue to the next step.

  2. Configure the Google Cloud SDK standard component to use your Google account. Run the following command:

    $ gcloud auth login
  3. A browser window prompts you to log in to Google. Log in using your Google account.

    A second screen requests several permissions. Select Allow.

    A third screen should appear with the heading, "You are now authenticated with the Google Cloud SDK!"

  4. Return to the terminal window and run the following command. Use the cluster name, zone, and project name you obtained from your cluster administrator:

    $ gcloud container clusters \
     get-credentials cluster-name --zone google-zone --project google-project
    Fetching cluster endpoint and auth data.
    kubeconfig entry generated for cluster-name.
  5. Run the kubectx command again and verify that the context for our Kubernetes cluster is now the current context.

Next Step

Namespace

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Create a namespace in the shared cluster. Namespaces let you isolate your deployments from other developers' deployments.

ForgeRock recommends that you deploy the ForgeRock Identity Platform in a namespace other than the default namespace. Deploying to a non-default namespace lets you separate workloads in a cluster. Separating a workload into a namespace lets you delete the workload easily; just delete the namespace.

To create a namespace:

  1. Create a namespace in your Kubernetes cluster:

    $ kubectl create namespace my-namespace
    namespace/my-namespace created
  2. Make the new namespace your current namespace:

    $ kubens my-namespace
    Context "my-context" modified.
    Active namespace is "my-namespace".
Next Step

Hostname Resolution

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

You might need to set up hostname resolution for the ForgeRock Identity Platform servers you’ll deploy in your namespace.

Take the following actions:

  1. Determine whether DNS resolves the hostname, my-namespace.iam.example.com.

  2. If DNS does not resolve the hostname, add an entry to the /etc/hosts file similar to the following:

    ingress-ip-address my-namespace.iam.example.com

    For ingress-ip-address, specify the IP address of your cluster’s ingress controller that you obtained from your cluster administrator.

Next Step

docker push Setup

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

In the environment you’re setting up, Skaffold builds Docker images using the Docker software you’ve installed on your local computer. After it builds the images, Skaffold pushes them to a Docker registry available to your GKE cluster. With the images on the remote Docker registry, Skaffold can orchestrate the ForgeRock Identity Platform, creating containers from the Docker images.

For Skaffold to be able to push the Docker images:

  • Docker must be running on your local computer.

  • Your local computer needs credentials that let Skaffold push the images to the Docker registry available to your cluster.

  • Skaffold needs to know the location of the Docker registry.

To set up your local computer to push Docker images:

  1. If it’s not already running, start Docker on your local computer. For more information, see the Docker documentation.

  2. Set up a Docker credential helper:

    $ gcloud auth configure-docker
  3. Run the kubectx command to obtain the Kubernetes context.

  4. Configure Skaffold with the Docker registry location you obtained from your cluster administrator and the Kubernetes context you obtained in Context for the Shared Cluster:

    $ skaffold config set default-repo my-docker-registry -k my-kubernetes-context
Next Step

You’ve completed all the setup tasks required before deploying the ForgeRock Identity Platform in a shared GKE cluster. Now you’re ready to deploy the platform in your namespace on the shared cluster:

forgeops Repository

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Before you can deploy the CDK or the CDM, you must first get the forgeops repository and check out the release/7.1.0 branch:

  1. Clone the forgeops repository. For exmple:

    $ git clone https://github.com/ForgeRock/forgeops.git

    The forgeops repository is a public Git repository. You do not need credentials to clone it.

  2. Check out the release/7.1.0 branch:

    $ cd forgeops
    $ git checkout release/7.1.0

Depending on your organization’s repository strategy, you might need to clone the repository from a fork, instead of cloning ForgeRock’s master repository. You might also need to create a working branch from the release/7.1.0 branch. For more information, see Repository Updates.

Next Step

Third-Party Software

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Before installing the CDK, you must obtain non-ForgeRock software and install it on your local computer.

ForgeRock recommends that you install third-party software using Homebrew on macOS and Linux[33] .

The versions listed in the table below have been validated for building custom Docker images for the ForgeRock Identity Platform. Earlier and later versions will probably work. If you want to try using versions that are not in the table, it is your responsibility to validate them.

Install the following third-party software:

Software Version Homebrew package

Python 3

3.9.6

python

Kubernetes client (kubectl)

1.21.2

kubectl

Kubernetes context switcher (kubectx)

0.9.3

kubectx

Kustomize

4.2.0

kustomize

Amazon AWS Command Line Interface

2.2.13

awscli

AWS IAM Authenticator for Kubernetes

0.5.3

aws-iam-authenticator

Docker Desktop[34]

3.6.0

docker (cask)[3]

Skaffold

1.26.1

skaffold

Next Step

Cluster Details

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

You’ll need to get some information about the cluster from your cluster administrator. You’ll provide this information as you perform various tasks to access the cluster.

  1. Obtain the following cluster details:

    • Your AWS access key ID.

    • Your AWS secret access key.

    • The AWS region in which the cluster resides.

    • The cluster name.

    • The IP address of your cluster’s ingress controller.

    • The location of the Docker registry from which your cluster will obtain images for the ForgeRock Identity Platform.

  2. Verify that the Secret Agent operator is installed in the cluster.

Next Step

Context for the Shared Cluster

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Kubernetes uses contexts to access Kubernetes clusters. Before you can access the shared cluster, you must create a context on your local computer if it’s not already present.

To create a context for the shared cluster:

  1. Run the kubectx command and review the output. The current Kubernetes context is highlighted:

    • If the current context references the shared cluster, there is nothing further to do. Proceed to Namespace.

    • If the context of the shared cluster is present in the kubectx command output, set the context as follows:

      $ kubectx my-context
      Switched to context "my-context".

      After you have set the context, proceed to Namespace.

    • If the context of the shared cluster is not present in the kubectx command output, continue to the next step.

  2. Run the aws configure command. This command logs you in to AWS and sets the AWS region. Use the access key ID, secret access key, and region you obtained from your cluster administrator. You do not need to specify a value for the default output format:

    $ aws configure
    AWS Access Key ID [None]:
    AWS Secret Access Key [None]:
    Default region name [None]:
    Default output format [None]:
  3. Run the following command. Use the cluster name you obtained from your cluster administrator:

    $ aws eks update-kubeconfig --name my-cluster
    Added new context arn:aws:eks:us-east-1:813759318741:cluster/my-cluster
    to /Users/my-user-name/.kube/config
  4. Run the kubectx command again and verify that the context for your Kubernetes cluster is now the current context.

In Amazon EKS environments, the cluster owner must grant access to a user before the user can access cluster resources. For details about how the cluster owner can grant you access to the cluster, refer the cluster owner to Cluster Access for Multiple AWS Users.

Next Step

Namespace

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Create a namespace in the shared cluster. Namespaces let you isolate your deployments from other developers' deployments.

ForgeRock recommends that you deploy the ForgeRock Identity Platform in a namespace other than the default namespace. Deploying to a non-default namespace lets you separate workloads in a cluster. Separating a workload into a namespace lets you delete the workload easily; just delete the namespace.

To create a namespace:

  1. Create a namespace in your Kubernetes cluster:

    $ kubectl create namespace my-namespace
    namespace/my-namespace created
  2. Make the new namespace your current namespace:

    $ kubens my-namespace
    Context "my-context" modified.
    Active namespace is "my-namespace".
Next Step

Hostname Resolution

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

You might need to set up hostname resolution for the ForgeRock Identity Platform servers you’ll deploy in your namespace.

Take the following actions:

  1. Determine whether DNS resolves the hostname, my-namespace.iam.example.com.

  2. If DNS does not resolve the hostname, add an entry to the /etc/hosts file similar to the following:

    ingress-ip-address my-namespace.iam.example.com

    For ingress-ip-address, specify the IP address of your cluster’s ingress controller that you obtained from your cluster administrator.

Next Step

docker push Setup

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

In the environment you’re setting up, Skaffold builds Docker images using the Docker software you’ve installed on your local computer. After it builds the images, Skaffold pushes them to a Docker registry available to your EKS cluster. With the images on the remote Docker registry, Skaffold can orchestrate the ForgeRock Identity Platform, creating containers from the Docker images.

For Skaffold to be able to push the Docker images:

  • Docker must be running on your local computer.

  • Your local computer needs credentials that let Skaffold push the images to the Docker registry available to your cluster.

  • Skaffold needs to know the location of the Docker registry.

To set up your local computer to push Docker images:

  1. If it’s not already running, start Docker on your local computer. For more information, see the Docker documentation.

  2. Log in to Amazon ECR. Use the Docker registry location you obtained from your cluster administrator:

    $ aws ecr get-login-password | \
     docker login --username AWS --password-stdin my-docker-registry
    stdin my-docker-registry
    Login Succeeded

    ECR login sessions expire after 12 hours. Because of this, you’ll need to perform these steps again whenever your login session expires.[35]

  3. Run the kubectx command to obtain the Kubernetes context.

  4. Configure Skaffold with the Docker registry location and the Kubernetes context:

    $ skaffold config set default-repo my-docker-registry -k my-kubernetes-context
Next Step

You’ve completed all the setup tasks required before deploying the ForgeRock Identity Platform in a shared EKS cluster. Now you’re ready to deploy the platform in your namespace on the shared cluster:

forgeops Repository

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Before you can deploy the CDK or the CDM, you must first get the forgeops repository and check out the release/7.1.0 branch:

  1. Clone the forgeops repository. For exmple:

    $ git clone https://github.com/ForgeRock/forgeops.git

    The forgeops repository is a public Git repository. You do not need credentials to clone it.

  2. Check out the release/7.1.0 branch:

    $ cd forgeops
    $ git checkout release/7.1.0

Depending on your organization’s repository strategy, you might need to clone the repository from a fork, instead of cloning ForgeRock’s master repository. You might also need to create a working branch from the release/7.1.0 branch. For more information, see Repository Updates.

Next Step

Third-Party Software

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Before installing the CDK, you must obtain non-ForgeRock software and install it on your local computer.

ForgeRock recommends that you install third-party software using Homebrew on macOS and Linux[36] .

The versions listed in the table below have been validated for building custom Docker images for the ForgeRock Identity Platform. Earlier and later versions will probably work. If you want to try using versions that are not in the table, it is your responsibility to validate them.

Install the following third-party software:

Software Version Homebrew package

Python 3

3.9.6

python

Kubernetes client (kubectl)

1.21.2

kubectl

Kubernetes context switcher (kubectx)

0.9.3

kubectx

Kustomize

4.2.0

kustomize

Azure Command Line Interface

2.25.0

azure-cli

Docker Desktop[37]

3.6.0

docker (cask)[3]

Skaffold

1.26.1

skaffold

Next Step

Cluster Details

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

You’ll need to get some information about the cluster from your cluster administrator. You’ll provide this information as you perform various tasks to access the cluster.

  1. Obtain the following cluster details:

    • The ID of the Azure subscription that contains the cluster. Be sure to obtain the hexadecimal subscription ID, not the subscription name.

    • The name of the resource group that contains the cluster.

    • The cluster name.

    • The IP address of your cluster’s ingress controller.

    • The location of the Docker registry from which your cluster will obtain images for the ForgeRock Identity Platform.

  2. Verify that the Secret Agent operator is installed in the cluster.

Next Step

Context for the Shared Cluster

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Kubernetes uses contexts to access Kubernetes clusters. Before you can access the shared cluster, you must create a context on your local computer if it’s not already present.

To create a context for the shared cluster:

  1. Run the kubectx command and review the output. The current Kubernetes context is highlighted:

    • If the current context references the shared cluster, there is nothing further to do. Proceed to Namespace.

    • If the context of the shared cluster is present in the kubectx command output, set the context as follows:

      $ kubectx my-context
      Switched to context "my-context".

      After you have set the context, proceed to Namespace.

    • If the context of the shared cluster is not present in the kubectx command output, continue to the next step.

  2. Configure the Azure CLI to use your Microsoft Azure. Run the following command:

    $ az login
  3. A browser window prompts you to log in to Azure. Log in using your Microsoft account.

    A second screen should appear with the message, "You have logged into Microsoft Azure!"

  4. Return to the terminal window and run the following command. Use the resource group, cluster name, and subscription ID you obtained from your cluster administrator:

    $ az aks get-credentials \
     --resource-group my-fr-resource-group \
     --name my-fr-cluster \
     --subscription your subscription ID \
     --overwrite-existing
  5. Run the kubectx command again and verify that the context for your Kubernetes cluster is now the current context.

Next Step

Namespace

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Create a namespace in the shared cluster. Namespaces let you isolate your deployments from other developers' deployments.

ForgeRock recommends that you deploy the ForgeRock Identity Platform in a namespace other than the default namespace. Deploying to a non-default namespace lets you separate workloads in a cluster. Separating a workload into a namespace lets you delete the workload easily; just delete the namespace.

To create a namespace:

  1. Create a namespace in your Kubernetes cluster:

    $ kubectl create namespace my-namespace
    namespace/my-namespace created
  2. Make the new namespace your current namespace:

    $ kubens my-namespace
    Context "my-context" modified.
    Active namespace is "my-namespace".
Next Step

Hostname Resolution

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

You might need to set up hostname resolution for the ForgeRock Identity Platform servers you’ll deploy in your namespace.

Take the following actions:

  1. Determine whether DNS resolves the hostname, my-namespace.iam.example.com.

  2. If DNS does not resolve the hostname, add an entry to the /etc/hosts file similar to the following:

    ingress-ip-address my-namespace.iam.example.com

    For ingress-ip-address, specify the IP address of your cluster’s ingress controller that you obtained from your cluster administrator.

Next Step

docker push Setup

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

In the environment you’re setting up, Skaffold builds Docker images using the Docker software you’ve installed on your local computer. After it builds the images, Skaffold pushes them to a Docker registry available to your AKS cluster. With the images on the remote Docker registry, Skaffold can orchestrate the ForgeRock Identity Platform, creating containers from the Docker images.

For Skaffold to be able to push the Docker images:

  • Docker must be running on your local computer.

  • Your local computer needs credentials that let Skaffold push the images to the Docker registry available to your cluster.

  • Skaffold needs to know the location of the Docker registry.

To set up your local computer to push Docker images:

  1. If it’s not already running, start Docker on your local computer. For more information, see the Docker documentation.

  2. Install the ACR Docker Credential Helper.

  3. Run the kubectx command to obtain the Kubernetes context.

  4. Configure Skaffold with the Docker registry location you obtained from your cluster administrator and the Kubernetes context you obtained in Context for the Shared Cluster:

    $ skaffold config set default-repo my-docker-registry -k my-kubernetes-context
Next Step

You’ve completed all the setup tasks required before deploying the ForgeRock Identity Platform in a shared AKS cluster. Now you’re ready to deploy the platform in your namespace on the shared cluster:

CDK Deployment

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

After you’ve set up your development environment, your next step is to deploy the platform.

To deploy the ForgeRock Identity Platform in your namespace:

  1. Change the deployment namespace for the all environment from the default namespace to your namespace:

    1. Change to the directory containing the all environment:

      $ cd /path/to/forgeops/kustomize/overlay/7.0/all
    2. Open the kustomization.yaml file.

    3. Modify two lines in the file so that the platform is deployed in your namespace:

      Original Text Revised Text

      namespace: default

      namespace: my-namespace

      FQDN: "default.iam.example.com"

      FQDN: "my-namespace.iam.example.com"

    4. Save the updated kustomization.yaml file.

  2. Initialize the staging area for configuration profiles with the canonical CDK configuration profile for the ForgeRock Identity Platform:

    $ cd /path/to/forgeops/bin
    $ ./config.sh init --profile cdk
    Removing docker/7.0/am/config/
    Removing docker/7.0/amster/config/
    Removing docker/7.0/idm/conf/
    Removing docker/7.0/idm/ui/
    Removing docker/7.0/ig/config/
    Copying /Users/david/Repositories/forgeops/config/7.0/cdk/idm.
    Copying /Users/david/Repositories/forgeops/config/7.0/cdk/am.
    Copying /Users/david/Repositories/forgeops/config/7.0/cdk/ig.
    Copying /Users/david/Repositories/forgeops/config/7.0/cdk/amster.
    Completed

    The config.sh init command copies the canonical CDK configuration profile from the master directory for configuration profiles to the staging area:

    This diagram shows how the staging area is initialized from the canonical ${cdk.abbr} profile.

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

  3. Configure secrets for the ForgeRock Identity Platform:

    1. Make sure that context is set to your namespace:

      $ kubens my-namespace
    2. Deploy the secrets:

      $ cd /path/to/forgeops/kustomize/base/secrets
      $ kubectl apply --filename secret_agent_config.yaml
    3. Verify that all the ForgeRock Identity Platform secrets have been created:

      $ kubectl get sac
      NAME            STATUS      NUMSECRETS   NUMK8SSECRETS
      forgerock-sac   Completed   14           14

      When the forgerock-sac entry reaches Completed status, all the secrets have been created.

  4. Run Skaffold to build Docker images and deploy the ForgeRock Identity Platform:

    $ cd /path/to/forgeops
    $ skaffold run
    Generating tags. . .
     - am → am:. . .
     - amster → amster:. . .
     - idm → idm:. . .
     - ds-cts → ds-cts:. . .
    . . .
  5. In a separate terminal tab or window, run the kubectl get pods command to monitor status of the deployment. Wait until all the pods are ready.

    Your namespace should have the pods shown in this diagram.

Next Step

UI and API Access

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Now that you’ve deployed the ForgeRock Identity Platform, you’ll need to know how to access its administration tools. You’ll use these tools to build customized Docker images for the platform.

This page shows you how to access the ForgeRock Identity Platform’s administrative consoles and REST APIs.

You access AM and IDM services through the Kubernetes ingress controller. Access components using their normal interfaces:

  • For AM, the console and REST APIs.

  • For IDM, the Admin UI and REST APIs.

You can’t access DS through the ingress controller, but you can use Kubernetes methods to access the DS pods.

For more information about how AM and IDM are configured in the CDK, see Configuration in the forgeops repository’s top-level README file.

AM Services

To access the AM console:

  1. Make sure that your namespace is the current namespace:

    $ kubens my-namespace
  2. Obtain the amadmin user’s password:

    $ cd /path/to/forgeops/bin
    $ ./print-secrets amadmin
    179rd8en9rffa82rcf1qap1z0gv1hcej
  3. Open a new window or tab in a web browser.

  4. Go to https://my-namespace.iam.example.com/platform.

    The Kubernetes ingress controller handles the request, routing it to the login-ui pod.

    The login UI prompts you to log in.

  5. Log in as the amadmin user.

    The ForgeRock Identity Platform UI appears in the browser.

  6. Select Native Consoles > Access Management.

    The AM console appears in the browser.

To access the AM REST APIs:

  1. Start a terminal window session.

  2. Run a curl command to verify that you can access the REST APIs through the ingress controller. For example:

    $ curl \
     --insecure \
     --request POST \
     --header "Content-Type: application/json" \
     --header "X-OpenAM-Username: amadmin" \
     --header "X-OpenAM-Password: 179rd8en9rffa82rcf1qap1z0gv1hcej" \
     --header "Accept-API-Version: resource=2.0" \
     --data "{}" \
     "https://my-namespace.iam.example.com/am/json/realms/root/authenticate"
    {
        "tokenId":"AQIC5wM2. . .TU3OQ*",
        "successUrl":"/am/console",
        "realm":"/"
    }

IDM Services

To access the IDM Admin UI:

  1. Make sure that your namespace is the current namespace:

    $ kubens my-namespace
  2. Obtain the amadmin user’s password:

    $ cd /path/to/forgeops/bin
    $ ./print-secrets amadmin
    vr58qt11ihoa31zfbjsdxxrqryfw0s31
  3. Open a new window or tab in a web browser.

  4. Go to https://my-namespace.iam.example.com/platform.

    The Kubernetes ingress controller handles the request, routing it to the login-ui pod.

    The login UI prompts you to log in.

  5. Log in as the amadmin user.

    The ForgeRock Identity Platform UI appears in the browser.

  6. Select Native Consoles > Identity Management.

    The IDM Admin UI appears in the browser.

To access the IDM REST APIs:

  1. Start a terminal window session.

  2. If you haven’t already done so, get the amadmin user’s password using the print-secrets command.

  3. AM authorizes IDM REST API access using the OAuth 2.0 authorization code flow. The CDK comes with the idm-admin-ui client, which is configured to let you get a bearer token using this OAuth 2.0 flow. You’ll use the bearer token in the next step to access the IDM REST API:

    1. Get a session token for the amadmin user:

      $ curl \
       --request POST \
       --insecure \
       --header "Content-Type: application/json" \
       --header "X-OpenAM-Username: amadmin" \
       --header "X-OpenAM-Password: vr58qt11ihoa31zfbjsdxxrqryfw0s31" \
       --header "Accept-API-Version: resource=2.0, protocol=1.0" \
       "https://my-namespace.iam.example.com/am/json/realms/root/authenticate"
      {
       "tokenId":"AQIC5wM. . .TU3OQ*",
       "successUrl":"/am/console",
       "realm":"/"}
    2. Get an authorization code. Specify the ID of the session token that you obtained in the previous step in the --Cookie parameter:

      $ curl \
       --dump-header - \
       --insecure \
       --request GET \
       --Cookie "iPlanetDirectoryPro=AQIC5wM. . .TU3OQ*" \
       "https://my-namespace.iam.example.com/am/oauth2/realms/root/authorize?redirect_uri=https://my-namespace.iam.example.com/platform/appAuthHelperRedirect.html&client_id=idm-admin-ui&scope=openid%20fr:idm:*&response_type=code&state=abc123"
      HTTP/2 302
      server: nginx/1.17.10
      date: Tue, 21 Jul 2020 16:54:20 GMT
      content-length: 0
      location: https://my-namespace.iam.example.com/platform/appAuthHelperRedirect.html
       ?code=3cItL9G52DIiBdfXRngv2_dAaYM&iss=http://my-namespace.iam.example.com:80/am/oauth2&state=abc123
       &client_id=idm-admin-ui
      set-cookie: route=1595350461.029.542.7328; Path=/am; Secure; HttpOnly
      x-frame-options: SAMEORIGIN
      x-content-type-options: nosniff
      cache-control: no-store
      pragma: no-cache
      set-cookie: OAUTH_REQUEST_ATTRIBUTES=DELETED; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/; HttpOnly
      strict-transport-security: max-age=15724800; includeSubDomains
    3. Exchange the authorization code for an access token. Specify the access code that you obtained in the previous step in the code URL parameter:

      $ curl --request POST \
       --insecure \
       --data "grant_type=authorization_code" \
       --data "code=3cItL9G52DIiBdfXRngv2_dAaYM" \
       --data "client_id=idm-admin-ui" \
       --data "redirect_uri=https://my-namespace.iam.example.com/platform/appAuthHelperRedirect.html" \
       "https://my-namespace.iam.example.com/am/oauth2/realms/root/access_token" 
      {
       "access_token":"oPzGzGFY1SeP2RkI-ZqaRQC1cDg",
       "scope":"openid fr:idm:*",
       "id_token":"eyJ0eXAiOiJKV
        . . .
        sO4HYqlQ",
       "token_type":"Bearer",
       "expires_in":239
      }
  4. Run a curl command to verify that you can access the openidm/config REST endpoint through the ingress controller. Use the access token returned in the previous step as the bearer token in the authorization header.

    The following example command provides information about the IDM configuration:

    $ curl \
     --insecure \
     --request GET \
     --header "Authorization: Bearer oPzGzGFY1SeP2RkI-ZqaRQC1cDg" \
     --data "{}" \
     https://my-namespace.iam.example.com/openidm/config
    {
     "_id":"",
     "configurations":
      [
       {
        "_id":"ui.context/admin",
        "pid":"ui.context.4f0cb656-0b92-44e9-a48b-76baddda03ea",
        "factoryPid":"ui.context"
        },
        . . .
       ]
    }

Directory Services

The DS pods in the CDK are not exposed outside of the cluster. If you need to access one of the DS pods, use a standard Kubernetes method:

  • Execute shell commands in DS pods using the kubectl exec command.

  • Forward a DS pod’s LDAPS port (1636) to your local computer. Then, you can run LDAP CLI commands like ldapsearch. You can also use an LDAP editor such as Apache Directory Studio to access the directory.

For all CDM directory pods, the directory superuser DN is uid=admin. Obtain this user’s password by running the print-secrets dsadmin command.

Next Step

Custom Docker Image Development

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

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.

Repeat this process as you develop custom Docker images:

  • 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’ll need to stop using ForgeRock’s evaluation-only base images, and start using base images you build yourself. Building your own base images is covered in Base Docker Images.

Types of Configuration

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

The ForgeRock Identity Platform uses three types of configuration: static configuration, dynamic configuration, and identities.

Static Configuration

Static configuration consists of properties and settings used by the ForgeRock Identity Platform. Examples of static configuration include AM realms, AM authentication trees, IDM social identity provider definitions, and IDM data mapping models for reconciliation.

Static configuration is stored in JSON configuration files. Because of this, static configuration is also referred to as file-based configuration.

You build static configuration into the am and idm Docker images during development, using the following general process:

  1. Change the AM or IDM configuration in the CDK using the UIs and APIs.

  2. Export the changes to your forgeops repository clone.

  3. Build a new AM or IDM Docker image that contains the updated configuration.

  4. Restart ForgeRock Identity Platform services using the new Docker images.

  5. Test your changes. Incorrect changes to static configuration might cause the platform to become inoperable.

  6. Promote your changes to your test and production environments as desired.

See AM and IDM Images for more detailed steps.

In ForgeRock Identity Platform deployments, static configuration is immutable. Do not change static configuration in testing or production. Instead, if you need to change static configuration, return to the development phase, make your changes, and build new custom Docker images that include the changes. Then, promote the new images to your test and production environments.

Dynamic Configuration

Dynamic configuration consists of access policies, applications, and data objects used by the ForgeRock Identity Platform. Examples of dynamic configuration include AM access policies, AM OAuth 2.0 client definitions, and IDM relationships.

In ForgeRock Identity Platform deployments, dynamic configuration is not immutable. You can change dynamic configuration at any time, including when the platform is running in production.

You’ll need to devise a strategy for managing AM and IDM dynamic configuration, so that you can:

  • Extract sample dynamic configuration for use by developers.

  • Back up and restore dynamic configuration.

The CDK and CDM run an Amster job when they start. The job loads dynamic configuration required by the CDK and CDM into the AM application and policy store.

The required dynamic configuration is stored in the amster Docker image. You can include additional dynamic configuration in this Docker image as a convenient way of loading your own applications and policies during CDK and CDM startup.

See xref:legacy/cdk/develop/am-idm.adoc for detailed steps to build the amster Docker image.

Identities

Identities are another type of dynamic configuration. They can be modified at any time, including when the platform is running in production. Identities are never incorporated into Docker images for the platform.

As with AM and IDM dynamic configuration, you’ll need to devise a strategy to manage identities that lets you:

  • Extract sample user identities that can be used by developers.

  • Back up and restore user identities.

Configuration Profiles

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

  • AM static configuration.

  • IDM static configuration.

  • AM dynamic configuration to be loaded into the AM application and policy store when the CDK and CDM start up.

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. 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. You run this script before you build customized Docker images for the platform. The script lets you specify which configuration profile to copy to the staging area. The skaffold run command uses the profile that’s been copied to the staging area when it builds a Docker image.

AM and IDM Images

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

AM Images

AM uses two Docker images, am and amster:

  • The am image contains your custom AM configuration.

  • The amster image contains your custom AM run-time data.

With AM up and running, you can iteratively update the am Docker image:

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

  • Run Skaffold to detect the changes, rebuild the am Docker image, and restart AM. You can then test changes you’ve made to the AM configuration based on the updated Docker image.

You can also iteratively update the amster image:

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

    AM run-time data includes:

    • OAuth 2.0 clients

    • OpenID Connect 1.0 clients

    • IG, Web, Java, and SOAP STS agents

    • Policies

    • SAML v2.0 circles of trust and entities

  • Run Skaffold to detect the changes and rebuild the amster Docker image.

am Image

The am Docker image contains the AM configuration.

Perform the following steps iteratively when developing 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. Make sure that context is set to your namespace:

    $ kubens my-namespace
  3. 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.

    See 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 AM configuration to your forgeops repository clone:

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

    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.

  5. List the changed files using the config.sh diff -c am command:

    $ ./config.sh diff --component am
    diff  -u --recursive config/7.0/cdk/am docker/7.0/am
    Only in docker/7.0/am/config/services/realm/root/authenticationtreesservice/1.0/organizationconfig/default: my-test-tree.json
    Only in docker/7.0/am: logback.xml
    . . .
  6. Save the exported configuration to your profile:

    $ ./config.sh save --component am --profile my-profile 
    Saving AM configuration..

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

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

  8. Delete the existing deployment:

    $ cd /path/to/forgeops/
    $ skaffold delete
    Cleaning up…​
     - configmap "idm" deleted
     - configmap "idm-logging-properties" deleted
     - configmap "platform-config" deleted
    . . .
  9. Redeploy with changes using the skaffold run command:

    $ skaffold run

    Skaffold builds a new am Docker image and redeploys AM.

  10. To validate that AM has the expected configuration, obtain the new password for amadmin user, 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 steps iteratively when developing 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 AM run-time data using the AM console or the REST APIs.

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

    AM run-time data includes:

    • OAuth 2.0 clients

    • OpenID Connect 1.0 clients

    • IG, Web, Java, and SOAP STS agents

    • Policies

    • SAML v2.0 circles of trust and entities

  3. Make sure that context is set to your namespace:

    $ kubens my-namespace
  4. 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
    /Users/. . ./forgeops/bin/amster export docker/7.0/amster/config
    Cleaning up any previous amster jobs…​
    starting the amster job
    kustomize build /Users/. . ./forgeops/bin/../kustomize/base/amster-export | kubectl  apply -f -
    job.batch/amster created
    kubectl  get pod -l app=amster --output=jsonpath={.items[0].metadata.name}
    Waiting for pod amster-95v45
    kubectl  wait --for=condition=ready pod amster-95v45 --timeout=90s
    kubectl  cp -c pause amster-95v45:/var/tmp/amster/realms docker/7.0/amster/config/realms
    tar: Removing leading `/' from member names
    kubectl  delete job amster
    job.batch "amster" deleted
    
    Saving Amster configuration
    
    * APPLYING FIXES *
    Adding back amsterVersion placeholder …​
    Adding back FQDN placeholder …​
    Removing 'userpassword-encrypted' fields …​
    
    Adding back password placeholder with defaults in these files:
    
    idm-provisioning.json
    idm-resource-server.json
    resource-server.json
    oauth2.json
    ig-agent.json
    
    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.

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

  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. Make sure that context is set to your namespace:

    $ kubens my-namespace
  8. Reinitialize the staging area with your configuration profile:

    $ cd /path/to/forgeops/bin
    $ ./config.sh init --profile my-profile
    Removing docker/7.0/am/config/
    Removing docker/7.0/amster/config/
    Removing docker/7.0/idm/conf/
    Removing docker/7.0/idm/ui/
    Removing docker/7.0/ig/config/
    Copying /path/to/forgeops/config/7.0/my-profile/idm.
    Copying /path/to/forgeops/config/7.0/my-profile/am.
    Copying /path/to/forgeops/config/7.0/my-profile/ig.
    Copying /path/to/forgeops/config/7.0/my-profile/amster.
    Completed
  9. (Optional) If you have customized DS data in the idrepo directory, take a backup of those changes, so you can restore your DS data after redeploying your customized amster image.

  10. Shut down your ForgeRock Identity Platform deployment, and remove the PVCs. See CDK Shutdown and Removal for details.

  11. Redeploy the ForgeRock Identity Platform:

    $ cd /path/to/forgeops
    $ skaffold run
  12. (Optional) If needed, restore any user identity data that you have customized in your environment.

  13. (Optional) Suppose you have sample AM run-time data that you want to use for testing, but you don’t want to include the sample data in the amster Docker image.

  14. Make sure that context is set to your namespace:

    $ kubens my-namespace
    • You can import the sample data to your running CDK deployment:

      $ cd /path/to/forgeops/bin
      $ ./amster import /path/to/run-time-data
      Cleaning up amster components
      job.batch "amster" deleted
      Packing and uploading configs
      configmap/amster-import created
      Deploying amster
      job.batch/amster created
      
      Waiting for amster job to complete. This can take several minutes.
      . . .
      Amster output ***
      java.util.prefs.FileSystemPreferences$1 run
      INFO: Created user preferences directory.
      am> :load amster-scripts/import.amster
      Importing directory /opt/amster/config
      Imported /opt/amster/config/realms/root/OAuth2Clients/MyClient.json
      Import completed successfully
      import done
      Cleaning up amster components
      job.batch "amster" deleted
      configmap "amster-import" deleted

      In this example, /path/to/run-time-data is a directory that contains JSON files with run-time AM data. JSON files in all of this path’s subdirectories are imported into AM.

    • Be sure to delete the sample AM data before you export the Amster component. If you do not delete the sample data, it will be incorporated into the amster Docker image the next time you build the image.

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

IDM Image

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.

  • Run Skaffold to detect the changes, rebuild the idm Docker image, and restart IDM. You can then test changes you’ve made to the IDM configuration based on the updated Docker image.

idm Image

The idm Docker image contains the IDM configuration.

Perform the following steps iteratively when developing 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.

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

  3. Make sure that context is set to your namespace:

    $ kubens my-namespace
  4. 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
    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.

  5. Execute the skaffold run command:

    $ cd /path/to/forgeops
    $ skaffold run

    Skaffold builds a new idm Docker image and redeploys IDM.

  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. To validate that IDM has the expected configuration, start the Admin UI, and verify that your configuration changes are present.

Property Value Substitution

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

Many property values in ForgeRock’s canonical CDK configuration profile are specified as configuration expressions instead of as hard-coded values. Fully-qualified domain names (FQDNs), passwords, and several other properties are all specified as configuration expressions.

Configuration expressions are property values in the AM and IDM configurations that are set when AM and IDM start up. Instead of being set to fixed, hard-coded values in the AM and IDM configurations, their values vary, depending on conditions in the run-time environment.

Using configuration expressions lets you use a single configuration profile that takes different values at run-time depending on the deployment environment. For example, you can use a single configuration profile for development, test, and production deployments.

In the ForgeRock Identity Platform, configuration expressions are preceded by an ampersand and enclosed in braces. For example, &{am.encryption.key}.

The statement, am.encryption.pwd=&{am.encryption.key} in the AM configuration indicates that the value of the property, am.encryption.pwd, is determined when AM starts up. Contrast this with a statement, am.encryption.pwd=myPassw0rd, which sets the property to a hard-coded value, myPassw0rd, regardless of the run-time environment.

How Property Value Substitution Works

This example shows how property value substitution works for a value specified as a configuration expression in the AM configuration:

  1. Search the /path/to/forgeops/config/7.0/cdk directory for the string &{.

  2. Locate this line in your search results:

    "am.encryption.pwd=&{am.encryption.key}",

    Because the property am.encryption.pwd is being set to a configuration expression, its value will be determined when AM starts up.

  3. Search the forgeops repository for the string AM_ENCRYPTION_KEY. You’ll see that the secret agent operator sets the environment variable, AM_ENCRYPTION_KEY. The property, am.encryption.pwd, will be set to the value of the environment variable, AM_ENCRYPTION_KEY when AM starts up.

Configuration expressions take their values from environment variables as follows:

  • Uppercase characters replace lowercase characters in the configuration expression’s name.

  • Underscores replace periods in the configuration expression’s name.

For more information about configuration expressions, see Property Value Substitution in the IDM documentation.

AM and IDM Differences

There are several subtle but important differences between the AM and IDM implementations of configuration expressions:

  • Canonical configuration profile.

    AM: Contains configuration expressions for usernames, passwords, FQDNs, and the URL access protocol.

    IDM: Contains configuration expressions for usernames, passwords, FQDNs, the URL access protocol, and additional properties.

  • Administration console handling of configuration expressions.

    AM: The console is not aware of configuration expressions. Values specified as configuration expressions in configuration profiles are displayed as run-time values in the console. You cannot specify property values as configuration expressions in the console.

    IDM: The Admin UI is aware of configuration expressions. Values specified as configuration expressions in configuration profiles are displayed as configuration expressions in the Admin UI. You can specify property values as configuration expressions in the Admin UI.

  • Export configuration behavior.

    AM: Configuration expressions are reinserted into the AM configuration, overriding hard-coded property values you might have set using the console.

    IDM: Configuration expressions are exported to the IDM configuration profile.

  • Replacing a hard-coded property value with a configuration expression.

    AM: Edit the AM configuration manually, replacing a property value with a configuration expression. Then, open the /path/to/forgeops/docker/7.0/am-config-upgrader/rules/placeholders.groovy file and add a rule that preserves the new configuration expression.

    IDM: Change the property’s value to a configuration expression in the Admin UI. When the configuration is exported, the exported configuration contains the configuration expression.

  • Replacing a configuration expression with a hard-coded property value.

    AM: Edit the AM configuration manually, replacing a configuration expression with a hard-coded property value. Then, open the /path/to/forgeops/docker/7.0/am-config-upgrader/rules/placeholders.groovy file and remove the rule that preserved the configuration expression you replaced.

    IDM: Hard-code the property’s value in the IDM Admin UI. When the configuration is exported, the exported configuration contains the hard-coded property value.

  • Configuration expressions' run-time values.

    AM: Configuration expressions get their values from environment variables.

    IDM: Configuration expressions can get their values from a variety of sources: environment variables, Java system properies, and configuration files.

CDK Shutdown and Removal

This documentation describes the legacy CDK implementation, which will be deprecated in an upcoming release. We strongly recommend that you transition to the current CDK implementation as soon as possible.

When you’re done working with your ForgeRock Identity Platform deployment, shut it down and remove it from your namespace:

  1. Go to the terminal window where you started Skaffold.

  2. Run the skaffold delete command to shut down your deployment and remove it from your namespace:

    $ cd /path/to/forgeops
    $ skaffold delete
    Cleaning up…​
    . . .
  3. Delete DS persistent volume claims (PVCs) from your namespace:

    $ kubectl delete pvc --all
    persistentvolumeclaim "data-ds-cts-0" deleted
    persistentvolumeclaim "data-ds-idrepo-0" deleted

DevOps Release Notes

Click here for recommended Kubernetes versions for deploying ForgeRock Identity Platform 7.1.

Click here for recommended NGINX ingress versions for deploying ForgeRock Identity Platform 7.1.

Click here for limitations when deploying ForgeRock Identity Platform 7.1 on Kubernetes.

Click here for more information about the rapidly evolving nature of the forgeops repository, including technology previews, legacy features, and feature deprecation and removal.

May 12, 2021

This major new release of the forgeops repository supports ForgeRock Identity Platform 7.1. In addition to enabling new features in the platform, this release adds usability and security enhancements.

2020 Release Notes Archive

Click here.

Support From ForgeRock

This appendix contains information about support options for the ForgeRock Cloud Developer’s Kit, the ForgeRock Cloud Deployment Model, and the ForgeRock Identity Platform.

ForgeRock DevOps Support

ForgeRock has developed artifacts in the forgeops Git repository for the purpose of deploying the ForgeRock Identity Platform in the cloud. The companion DevOps documentation provides examples, including the ForgeRock Cloud Developer’s Kit (CDK) and the ForgeRock Cloud Deployment Model (CDM), to help you get started.

These artifacts and documentation are provided on an "as is" basis. ForgeRock does not guarantee the individual success developers may have in implementing the code on their development platforms or in production configurations.

Commercial Support

ForgeRock provides commercial support for the following DevOps resources:

  • Artifacts in the forgeops Git repository:

    • Files used to build Docker images for the ForgeRock Identity Platform:

      • Dockerfiles

      • Scripts and configuration files incorporated into ForgeRock’s Docker images

      • Canonical configuration profiles for the platform

    • Kustomize bases and overlays

    • Skaffold configuration files

  • ForgeRock DevOps Documentation

ForgeRock provides commercial support for the ForgeRock Identity Platform. For supported components, containers, and Java versions, see the following:

Support Limitations

ForgeRock provides no commercial support for the following:

  • Artifacts other than Dockerfiles, Kustomize bases, Kustomize overlays, and Skaffold YAML configuration files in the forgeops Git repository. Examples include scripts, example configurations, and so forth.

  • Non-ForgeRock infrastructure. Examples include Docker, Kubernetes, Google Cloud Platform, Amazon Web Services, Microsoft Azure, and so forth.

  • Non-ForgeRock software. Examples include Java, Apache Tomcat, NGINX, Apache HTTP Server, Certificate Manager, Prometheus, and so forth.

  • Production deployments that use ForgeRock’s evaluation-only Docker images. When deploying the ForgeRock Identity Platform using Docker images, you must build and use your own images for production deployments, except for several Docker images from ForgeRock that implement user interface elements. For information about which Docker images you’ll need to build for your production deployment, and how to build them, see Base Docker Images.

Third-Party Kubernetes Services

The ForgeRock Identity Platform is tested on Google Kubernetes Engine (GKE), Amazon Elastic Kubernetes Service (Amazon EKS), and Microsoft Azure Kubernetes Service (AKS). While the platform is known to work on a variety of Cloud Native Computing Foundation (CNCF)-certified Kubernetes distributions, ForgeRock is only able to replicate issues on the core distributions listed above. The tested versions are listed in the Release Notes, and are updated semi-annually.

Among CNCF distributions, there is considerable variation in components such as persistent disks, volume snapshots, load balancing (ingress and egress), DNS, and network connectivity. As of this writing, there are over 90 CNCF-certified offerings, making it impractical to test against all distributions.

ForgeRock supports running the platform on Kubernetes. ForgeRock does not support Kubernetes itself. You must have a support contract in place with your Kubernetes vendor to resolve infrastructure issues. To avoid any misunderstandings, it must be clear that ForgeRock cannot troubleshoot underlying Kubernetes issues.

Modifications to ForgeRock’s deployment assets may be required in order to adapt the platform to your Kubernetes implementation. For example, ingress routes, storage classes, NAT gateways, etc., might need to be modified. Making the modifications requires competency in Kubernetes, and familiarity with your chosen distribution.

Documentation Access

ForgeRock publishes comprehensive documentation online:

  • The ForgeRock Knowledge Base offers a large and increasing number of up-to-date, practical articles that help you deploy and manage ForgeRock software.

    While many articles are visible to community members, ForgeRock customers have access to much more, including advanced information for customers using ForgeRock software in a mission-critical capacity.

  • ForgeRock developer documentation, such as this site, aims to be technically accurate with respect to the sample that is documented. It is visible to everyone.

Problem Reports and Feedback

If you are a named customer Support Contact, contact ForgeRock using the Customer Support Portal to request information, or report a problem with Dockerfiles, Kustomize bases, Kustomize overlays, or Skaffold YAML configuration files in the CDK or the CDM.

When requesting help with a problem, include the following information:

  • Description of the problem, including when the problem occurs and its impact on your operation.

  • Steps to reproduce the problem.

    If the problem occurs on a Kubernetes system other than Minikube, GKE, EKS, or AKS, we might ask you to reproduce the problem on one of those.

  • HTML output from the debug-logs command. For more information, see Logs and Other Diagnostics.

  • Description of the environment, including the following information:

    • Environment type: Minikube, GKE, EKS, or AKS.

    • Software versions of supporting components:

      • Oracle VirtualBox (Minikube environments only).

      • Docker client (all environments).

      • Minikube (all environments).

      • kubectl command (all environments).

      • Kustomize (all environments).

      • Skaffold (all environments).

      • Google Cloud SDK (GKE environments only).

      • Amazon AWS Command Line Interface (EKS environments only).

      • Azure Command Line Interface (AKS environments only).

    • forgeops repository branch.

    • Any patches or other software that might be affecting the problem.

Contact Information

ForgeRock provides support services, professional services, training through ForgeRock University, and partner services to assist you in setting up and maintaining your deployments. For a general overview of these services, see https://www.forgerock.com.

ForgeRock has staff members around the globe who support our international customers and partners. For details on ForgeRock’s support offering, including support plans and service-level agreements (SLAs), visit https://www.forgerock.com/support.

Glossary

affinity (AM)

AM affinity deployment lets AM spread the LDAP reqests load over multiple directory server instances. Once a CTS token is created and assigned to a session, AM sends all subsequent token operations to the same token origin directory server from any AM node. This ensures that the load of CTS token management is spread across directory servers.

Amazon EKS

Amazon Elastic Container Service for Kubernetes (Amazon EKS) is a managed service that makes it easy for you to run Kubernetes on Amazon Web Services without needing to set up or maintain your own Kubernetes control plane.

ARN (AWS)

An Amazon Resource Name (ARN) uniquely identifies an Amazon Web Service (AWS) resource. AWS requires an ARN when you need to specify a resource unambiguously across all of AWS, such as in IAM policies and API calls.

AWS IAM Authenticator for Kubernetes

The AWS IAM Authenticator for Kubernetes is an authentication tool that lets you use Amazon Web Services (AWS) credentials for authenticating to a Kubernetes cluster.

Azure Kubernetes Service (AKS)

AKS is a managed container orchestration service based on Kubernetes. AKS is available on the Microsoft Azure public cloud. AKS manages your hosted Kubernetes environment, making it quick and easy to deploy and manage containerized applications.

cloud-controller-manager

The cloud-controller-manager daemon runs controllers that interact with the underlying cloud providers. The cloud-controller-manager daemon runs provider-specific controller loops only.

Cloud Developer’s Kit (CDK)

The developer artifacts in the forgeops Git repository, together with the ForgeRock Identity Platform documentation, form the Cloud Developer’s Kit (CDK). Use the CDK to set up the platform in your developer environment.

Cloud Deployment Model (CDM)

The Cloud Deployment Model (CDM) is a common use ForgeRock Identity Platform architecture, designed to be easy to deploy and easy to replicate. The ForgeRock Cloud Deployment Team has developed Kustomize bases and overlays, Skaffold configuration files, Docker images, and other artifacts expressly to build the CDM.

CloudFormation (AWS)

CloudFormation is a service that helps you model and set up your AWS resources. You create a template that describes all the AWS resources that you want. AWS CloudFormation takes care of provisioning and configuring those resources for you.

CloudFormation template (AWS)

An AWS CloudFormation template describes the resources that you want to provision in your AWS stack. AWS CloudFormation templates are text files formatted in JSON or YAML.

cluster

A container cluster is the foundation of Kubernetes Engine. A cluster consists of at least one cluster master and multiple worker machines called nodes. The Kubernetes objects that represent your containerized applications all run on top of a cluster.

cluster master

A cluster master schedules, runs, scales, and upgrades the workloads on all nodes of the cluster. The cluster master also manages network and storage resources for workloads.

ConfigMap

A configuration map, called ConfigMap in Kubernetes manifests, binds the configuration files, command-line arguments, environment variables, port numbers, and other configuration artifacts to the assigned containers and system components at runtime. The configuration maps are useful for storing and sharing non-sensitive, unencrypted configuration information.

container

A container is an allocation of resources such as CPU, network I/O, bandwidth, block I/O, and memory that can be "contained" together and made available to specific processes without interference from the rest of the system. Containers decouple applications from underlying host infrastructure.

DaemonSet

A set of daemons, called DaemonSet in Kubernetes manifests, manages a group of replicated pods. Usually, the daemon set follows a one-pod-per-node model. As you add nodes to a node pool, the daemon set automatically distributes the pod workload to the new nodes as needed.

deployment

A Kubernetes deployment represents a set of multiple, identical pods. Deployment runs multiple replicas of your application and automatically replaces any instances that fail or become unresponsive.

deployment controller

A deployment controller provides declarative updates for pods and replica sets. You describe a desired state in a deployment object, and the deployment controller changes the actual state to the desired state at a controlled rate. You can define deployments to create new replica sets, or to remove existing deployments and adopt all their resources with new deployments.

Docker container

A Docker container is a runtime instance of a Docker image. The container is isolated from other containers and its host machine. You can control how isolated your container’s network, storage, or other underlying subsystems are from other containers or from the host machine.

Docker daemon

The Docker daemon (dockerd) listens for Docker API requests and manages Docker objects such as images, containers, networks, and volumes. A Docker daemon can also communicate with other Docker daemons to manage Docker services.

Docker Engine

The Docker Engine is a client-server application with these components:

  • A server, which is a type of long-running program called a daemon process (the dockerd command)

  • A REST API, which specifies interfaces that programs can use to talk to the daemon and tell it what to do

  • A command-line interface (CLI) client (the docker command)

Dockerfile

A Dockerfile is a text file that contains the instructions for building a Docker image. Docker uses the Dockerfile to automate the process of building a Docker image.

Docker Hub

Docker Hub provides a place for you and your team to build and ship Docker images. You can create public repositories that can be accessed by any other Docker Hub user, or you can create private repositories you can control access to.

Docker image

A Docker image is an application you would like to run. A container is a running instance of an image.

An image is a read-only template with instructions for creating a Docker container. Often, an image is based on another image, with some additional customization.

An image includes the application code, a runtime engine, libraries, environment variables, and configuration files that are required to run the application.

Docker namespace

Docker namespaces provide a layer of isolation. When you run a container, Docker creates a set of namespaces for that container. Each aspect of a container runs in a separate namespace and its access is limited to that namespace.

The PID namespace is the mechanism for remapping process IDs inside the container. Other namespaces such as net, mnt, ipc, and uts provide the isolated environments we know as containers. The user namespace is the mechanism for remapping user IDs inside a container.

Docker registry

A Docker registry stores Docker images. Docker Hub and Docker Cloud are public registries that anyone can use, and Docker is configured to look for images on Docker Hub by default. You can also run your own private registry.

Docker repository

A Docker repository is a public, certified repository from vendors and contributors to Docker. It contains Docker images that you can use as the foundation to build your applications and services.

dynamic volume provisioning

The process of creating storage volumes on demand is called dynamic volume provisioning. Dynamic volume provisioning lets you create storage volumes on demand. It automatically provisions storage when it is requested by users.

egress

An egress controls access to destinations outside the network from within a Kubernetes network. For an external destination to be accessed from a Kubernetes environment, the destination should be listed as an allowed destination in the whitelist configuration.

firewall rule

A firewall rule lets you allow or deny traffic to and from your virtual machine instances based on a configuration you specify. Each Kubernetes network has a set of firewall rules controlling access to and from instances in its subnets. Each firewall rule is defined to apply to either incoming (ingress) or outgoing (egress) traffic, not both.

garbage collection

Garbage collection is the process of deleting unused objects. Kubelets perform garbage collection for containers every minute, and garbage collection for images every five minutes. You can adjust the high and low threshold flags and garbage collection policy to tune image garbage collection.

Google Kubernetes Engine (GKE)

The Google Kubernetes Engine (GKE) is an environment for deploying, managing, and scaling your containerized applications using Google infrastructure. The GKE environment consists of multiple machine instances grouped together to form a container cluster.

horizontal pod autoscaler

The horizontal pod autoscaler lets a Kubernetes cluster to automatically scale the number of pods in a replication controller, deployment, replica set, or stateful set based on observed CPU utilization. Users can specify the CPU utilization target to enable the controller to adjust athe number of replicas.

Source: Horizontal Pod Autoscaler in the Kubernetes documentation.

ingress

An ingress is a collection of rules that allow inbound connections to reach the cluster services.

instance group

An instance group is a collection of instances of virtual machines. The instance groups lets you easily monitor and control the group of virtual machines together.

instance template

An instance template is a global API resource to create VM instances and managed instance groups. Instance templates define the machine type, image, zone, labels, and other instance properties. They are very helpful in replicating the environments.

kubectl

The kubectl command-line tool supports several different ways to create and manage Kubernetes objects.

kube-controller-manager

The Kubernetes controller manager is a process that embeds core controllers shipped with Kubernetes. Each controller is a separate process. To reduce complexity, the controllers are compiled into a single binary and run in a single process.

kubelet

A kubelet is an agent that runs on each node in the cluster. It ensures that containers are running in a pod.

kube-scheduler

The kube-scheduler component is on the master node. It watches for newly created pods that do not have a node assigned to them, and selects a node for them to run on.

Kubernetes

Kubernetes is an open source platform designed to automate deploying, scaling, and operating application containers.

Kubernetes DNS

A Kubernetes DNS pod is a pod used by the kubelets and the individual containers to resolve DNS names in the cluster.

Kubernetes namespace

Kubernetes supports multiple virtual clusters backed by the same physical cluster. A Kubernetes namespace is a virtual cluster that provides a way to divide cluster resources between multiple users. Kubernetes starts with three initial namespaces:

  • default: The default namespace for user created objects which don’t have a namespace

  • kube-system: The namespace for objects created by the Kubernetes system

  • kube-public: The automatically created namespace that is readable by all users

Let’s Encrypt

Let’s Encrypt is a free, automated, and open certificate authority.

Microsoft Azure

Microsoft Azure is the Microsoft cloud platform, including infrastructure as a service (IaaS) and platform as a service (PaaS) offerings.

network policy

A Kubernetes network policy specifies how groups of pods are allowed to communicate with each other and with other network endpoints.

node (Kubernetes)

A Kubernetes node is a virtual or physical machine in the cluster. Each node is managed by the master components and includes the services needed to run the pods.

node controller (Kubernetes)

A Kubernetes node controller is a Kubernetes master component that manages various aspects of the nodes, such as: lifecycle operations, operational status, and maintaining an internal list of nodes.

node pool (Kubernetes)

A Kubernetes node pool is a collection of nodes with the same configuration. At the time of creating a cluster, all the nodes created in the default node pool. You can create your custom node pools for configuring specific nodes that have a different resource requirements such as memory, CPU, and disk types.

persistent volume

A persistent volume (PV) is a piece of storage in the cluster that has been provisioned by an administrator. It is a resource in the cluster just like a node is a cluster resource. PVs are volume plugins that have a lifecycle independent of any individual pod that uses the PV.

persistent volume claim

A persistent volume claim (PVC) is a request for storage by a user. A PVC specifies size, and access modes such as:

pod anti-affinity (Kubernetes)

Kubernetes pod anti-affinity constrains which nodes can run your pod, based on labels on the pods that are already running on the node, rather than based on labels on nodes. Pod anti-affinity lets you control the spread of workload across nodes and also isolate failures to nodes.

pod (Kubernetes)

A Kubernetes pod is the smallest, most basic deployable object in Kubernetes. A pod represents a single instance of a running process in a cluster. Containers within a pod share an IP address and port space.

region (Azure)

An Azure region, also known as a location, is an area within a geography, containing one or more data centers.

replication controller (Kubernetes)

A replication controller ensures that a specified number of Kubernetes pod replicas are running at any one time. The replication controller ensures that a pod or a homogeneous set of pods is always up and available.

resource group (Azure)

A resource group is a container that holds related resources for an application. The resource group can include all of the resources for an application, or only those resources that are logically grouped together.

secret (Kubernetes)

A Kubernetes secret is a secure object that stores sensitive data, such as passwords, OAuth 2.0 tokens, and SSH keys in your clusters.

security group (AWS)

A security group acts as a virtual firewall that controls the traffic for one or more compute instances.

service (Kubernetes)

A Kubernetes service is an abstraction which defines a logical set of pods and a policy by which to access them. This is sometimes called a microservice.

service principal (Azure)

An Azure service principal is an identity created for use with applications, hosted services, and automated tools to access Azure resources. Service principals let applications access resources with the restrictions imposed by the assigned roles instead of accessing resources as a fully privileged user.

shard

Sharding is a way of partitioning directory data so that the load can be shared by multiple directory servers. Each data partition, also known as a shard, exposes the same set of naming contexts, but only a subset of the data. For example, a distribution might have two shards. The first shard contains all users whose names begins with A-M, and the second contains all users whose names begins with N-Z. Both have the same naming context.

stack (AWS)

A stack is a collection of AWS resources that you can manage as a single unit. You can create, update, or delete a collection of resources by using stacks. All the resources in a stack are defined by the AWS template.

stack set (AWS)

A stack set is a container for stacks. You can provision stacks across AWS accounts and regions by using a single AWS template. All the resources included in each stack of a stack set are defined by the same template.

subscription (Azure)

An Azure subscription is used for pricing, billing, and payments for Azure cloud services. Organizations can have multiple Azure subscriptions, and subscriptions can span multiple regions.

volume (Kubernetes)

A Kubernetes volume is a storage volume that has the same lifetime as the pod that encloses it. Consequently, a volume outlives any containers that run within the pod, and data is preserved across container restarts. When a pod ceases to exist, the Kubernetes volume also ceases to exist.

VPC (AWS)

A virtual private cloud (VPC) is a virtual network dedicated to your AWS account. It is logically isolated from other virtual networks in the AWS Cloud.

worker node (AWS)

An Amazon Elastic Container Service for Kubernetes (Amazon EKS) worker node is a standard compute instance provisioned in Amazon EKS.

workload (Kubernetes)

A Kubernetes workload is the collection of applications and batch jobs packaged into a container. Before you deploy a workload on a cluster, you must first package the workload into a container.

Click here for legal information about product documentation published by ForgeRock.

About ForgeRock Identity Platform Software

The ForgeRock® Identity Platform serves as the basis for our simple and comprehensive identity and access management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

The platform includes the following components:

  • ForgeRock® Access Management (AM)

  • ForgeRock® Identity Management (IDM)

  • ForgeRock® Directory Services (DS)

  • ForgeRock® Identity Gateway (IG)

Copyright © 2017 by Dave Gandy, https://fontawesome.com/. This Font Software is licensed under the SIL Open Font License, Version 1.1. See https://opensource.org/licenses/OFL-1.1.

End of Consolidated File


1. If your cluster’s context is not minikube, replace minikube with the actual context name in the skaffold config set command.
2. You can automate logging into ECR every 12 hours by using the cron utility.
3. The Linux version of Homebrew does not support installing software it maintains as casks. Because of this, if you’re setting up an environment on Linux, you won’t be able to use Homebrew to install software in several cases. You’ll need to refer to the software’s documentation for information about how to install the software on a Linux system.
4. Install Docker Desktop on macOS. On Linux computers, install Docker CE instead. For more information, see the Docker documentation.
5. The Linux version of Homebrew does not support installing software it maintains as casks. Because of this, if you’re setting up an environment on Linux, you won’t be able to use Homebrew to install software in several cases. You’ll need to refer to the software’s documentation for information about how to install the software on a Linux system.
6. Install Docker Desktop on macOS. On Linux computers, install Docker CE instead. For more information, see the Docker documentation.
7. The Linux version of Homebrew does not support installing software it maintains as casks. Because of this, if you’re setting up an environment on Linux, you won’t be able to use Homebrew to install software in several cases. You’ll need to refer to the software’s documentation for information about how to install the software on a Linux system.
8. Install Docker Desktop on macOS. On Linux computers, install Docker CE instead. For more information, see the Docker documentation.
9. The Linux version of Homebrew does not support installing software it maintains as casks. Because of this, if you’re setting up an environment on Linux, you won’t be able to use Homebrew to install software in several cases. You’ll need to refer to the software’s documentation for information about how to install the software on a Linux system.
10. Install Docker Desktop on macOS. On Linux computers, install Docker CE instead. For more information, see the Docker documentation.
11. On GKE, the node pool shown in the diagram as Primary is named default-pool.
12. The Linux version of Homebrew does not support installing software it maintains as casks. Because of this, if you’re setting up an environment on Linux, you won’t be able to use Homebrew to install software in several cases. You’ll need to refer to the software’s documentation for information about how to install the software on a Linux system.
13. Install Docker Desktop on macOS. On Linux computers, install Docker CE instead. For more information, see the Docker documentation.
14. The cluster creation script adds a set of required labels to clusters created by ForgeRock employees. The first time you run the script, it prompts you to specify whether you’re a ForgeRock employee or not, so that it can add these labels if appropriate. You should not receive this prompt during subsequent executions of the script.
15. The Linux version of Homebrew does not support installing software it maintains as casks. Because of this, if you’re setting up an environment on Linux, you won’t be able to use Homebrew to install software in several cases. You’ll need to refer to the software’s documentation for information about how to install the software on a Linux system.
16. Install Docker Desktop on macOS. On Linux computers, install Docker CE instead. For more information, see the Docker documentation.
17. The cluster creation script adds a set of required labels to clusters created by ForgeRock employees. The first time you run the script, it prompts you to specify whether you’re a ForgeRock employee or not, so that it can add these labels if appropriate. You should not receive this prompt during subsequent executions of the script.
18. You can automate logging into ECR every 12 hours by using the cron utility.
19. The Linux version of Homebrew does not support installing software it maintains as casks. Because of this, if you’re setting up an environment on Linux, you won’t be able to use Homebrew to install software in several cases. You’ll need to refer to the software’s documentation for information about how to install the software on a Linux system.
20. Install Docker Desktop on macOS. On Linux computers, install Docker CE instead. For more information, see the Docker documentation.
21. The cluster creation script adds a set of required labels to clusters created by ForgeRock employees. The first time you run the script, it prompts you to specify whether you’re a ForgeRock employee or not, so that it can add these labels if appropriate. You should not receive this prompt during subsequent executions of the script.
22. You can automate logging in to ACR by using the cron utility.
23. The CDM and the CDK both use the CDK canonical configuration profile.
24. When you build the am Docker image, the AM configuration files are copied from the /path/to/forgeops/docker/7.0/am/config directory to the /home/forgerock/openam/config directory.
25. When you build the idm Docker image, the IDM configuration files are copied from the /path/to/forgeops/docker/7.0/idm/conf directory to the /opt/openidm/conf directory.
26. When you build the am Docker image, the AM configuration files are copied from the /path/to/forgeops/docker/7.0/am/config directory to the /home/forgerock/openam/config directory.
27. When you build the idm Docker image, the IDM configuration files are copied from the /path/to/forgeops/docker/7.0/idm/conf directory to the /opt/openidm/conf directory.
28. The Linux version of Homebrew does not support installing software it maintains as casks. Because of this, if you’re setting up an environment on Linux, you won’t be able to use Homebrew to install software in several cases. You’ll need to refer to the software’s documentation for information about how to install the software on a Linux system.
29. Install Docker Desktop on macOS. On Linux computers, install Docker CE instead. For more information, see the Docker documentation.
30. If your cluster’s context is not minikube, replace minikube with the actual context name in the skaffold config set command.
31. The Linux version of Homebrew does not support installing software it maintains as casks. Because of this, if you’re setting up an environment on Linux, you won’t be able to use Homebrew to install software in several cases. You’ll need to refer to the software’s documentation for information about how to install the software on a Linux system.
32. Install Docker Desktop on macOS. On Linux computers, install Docker CE instead. For more information, see the Docker documentation.
33. The Linux version of Homebrew does not support installing software it maintains as casks. Because of this, if you’re setting up an environment on Linux, you won’t be able to use Homebrew to install software in several cases. You’ll need to refer to the software’s documentation for information about how to install the software on a Linux system.
34. Install Docker Desktop on macOS. On Linux computers, install Docker CE instead. For more information, see the Docker documentation.
35. You can automate logging into ECR every 12 hours by using the cron utility.
36. The Linux version of Homebrew does not support installing software it maintains as casks. Because of this, if you’re setting up an environment on Linux, you won’t be able to use Homebrew to install software in several cases. You’ll need to refer to the software’s documentation for information about how to install the software on a Linux system.
37. Install Docker Desktop on macOS. On Linux computers, install Docker CE instead. For more information, see the Docker documentation.