Information for deploying ForgeRock Identity Platform™ version 6.5 in DevOps environments. Includes late-breaking news about features, known issues, and using the forgeops repository.

Preface

Read these release notes before you deploy ForgeRock® software in DevOps environments or update your existing deployment.

These release notes cover the prerequisites for deployment, known issues and improvements, changes and deprecated functionality, and other important information.

Before You Begin

Before deploying the ForgeRock Identity Platform in a DevOps environment, read the important information in Start Here.

About ForgeRock Identity Platform Software

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.

Chapter 1. What's New

This chapter covers new features and improvements in the version 6.5 of the ForgeRock DevOps Examples and Cloud Deployment Model.

FeatureMore Information
Cloud Deployment Model (CDM) artifacts and documentation

The CDM, completely new in version 6.5, demonstrates a common use ForgeRock Identity Platform architecture installed in a DevOps environment.

The forgeops repository contains the CDM deployment artifacts.

The Cloud Deployment Model Cookbook for GKE describes the CDM deployment and its behaviors, and provides steps for replicating the model on Google Kubernetes Engine (GKE).

The Site Reliability Guide for GKE describes customizing the CDM on GKE to meet your organization's needs.

Helm chart for configuration repository details

The new frconfig Helm chart deploys configuration items used by other pods in a ForgeRock deployment:

  • The configuration repository's URL

  • The configuration repository branch that contains the AM, IDM, and IG configurations

  • The private key needed to access the configuration repository

  • A signing certificate that the certificate manager uses to create an SSL certificate to secure communication with ForgeRock services

You can install more than one frconfig-like chart. Installing multiple charts is useful if you want your deployment to obtain ForgeRock component configurations from multiple configuration repositories.

For information about how to deploy the frconfig Helm chart, see "Installing the frconfig Helm Chart" in the DevOps Developer's Guide.

For information about using multiple configuration repositories, see the commented values.yaml file for the frconfig Helm chart in the forgeops repository.

downloader Docker image

The method for building Docker images has changed in version 6.5. The downloader image, which automatically downloads ForgeRock binaries, now serves as the base image for the openam, amster, openidm, openig, and ds Docker images.

With the ForgeRock Docker images using the downloader image as their base image, you no longer need to manually download the binary files from ForgeRock before you build Docker images.

For more information, see "Building and Pushing Docker Images" in the DevOps Developer's Guide.

Communication to ForgeRock Identity Platform services is HTTPS-only

In version 6.5, all communication to ForgeRock Identity Platform services is over HTTPS. You can secure communication by using any of the following:

  • A self-signed certificate

  • A certificate with a trust chain that starts at a trusted root certificate

  • A certificate obtained dynamically from Let's Encrypt

For more information, see "About Securing Communication With ForgeRock Services" in the DevOps Developer's Guide.

debug-logs.sh script

The new debug-logs.sh script 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

For more information, see "Running the debug-logs.sh Script" in the DevOps Developer's Guide.

Apache HTTP Server web agent example

A Helm chart for deploying Apache HTTP Server with a web agent has been added to the DevOps Examples.

For more information, see the README file in the /path/to/forgeops/helm/apache-agent directory.

The AM configuration, policies, and application data reside in the configuration store

In AM 6.5, you can maintain policies and application data in their own external data stores.

In the DevOps Examples and CDM, policies and application data reside in the configuration store rather than in separate data stores.

Chapter 2. Before You Deploy

This chapter covers software prerequisites for deploying and running the DevOps Examples and the CDM.

2.1. About the DevOps Repositories on GitHub

The ForgeRock DevOps Examples and CDM use the following two Git repositories:

  • forgeops

  • forgeops-init

You must obtain these Git repositories before you can use the DevOps Examples or the CDM.

This section describes the repositories' content and how to get them.

2.1.1. forgeops Repository

The forgeops repository provides reference implementations for the DevOps Examples and the CDM. The repository contains:

  • Dockerfiles and other artifacts for building Docker images

  • Helm charts and Kubernetes manifests for orchestrating the DevOps Examples and the CDM

  • Utility scripts

Deploying the reference implementations of the DevOps Examples and the CDM requires minor modifications to the forgeops repository.

Perform the following steps to obtain the forgeops repository:

To Obtain the forgeops Repository

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

  1. Clone the forgeops repository:

    $ git clone https://github.com/ForgeRock/forgeops.git
  2. Check out the release/6.5.0 branch:

    $ cd forgeops
    $ git checkout release/6.5.0

2.1.2. forgeops-init Repository

The forgeops-init repository is the basis for a configuration repository.

When you deploy the ForgeRock Identity Platform in a DevOps environment, the AM, IDM, and IG configurations are retrieved from JSON files. The JSON files are stored in a cloud-based Git configuration repository.

The forgeops-init repository contains:

  • Sets of JSON files that define sample configurations for AM, IDM, and IG

  • README files that contain detailed information about:

    • The structure of the repository

    • Each sample configuration in the repository

Before you can deploy the ForgeRock Identity Platform in a DevOps environment, you must duplicate, fork, or use the forgeops-init repository. For more information, see "Creating Your Configuration Repository" in the DevOps Developer's Guide.

2.2. Installing Required Third-Party Software

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

The DevOps Examples and the CDM have been validated with the third-party software versions listed in this section. The examples might also work with older or newer versions of the software.

Review the tables in this section to determine which software and versions to install on your local computer.

2.2.1. Software Requirements for All Environments

Install the software listed in the following table on your local computer:

SoftwareVersionURL for More Information
Docker Desktop (Mac and Windows)2.0.0.0 https://www.docker.com/products/docker-desktop
Docker client (Linux)18.09.0 https://docs.docker.com/install/linux/docker-ce/binaries
Kubernetes client (kubectl)1.12.3 https://kubernetes.io/docs/tasks/kubectl/install
Kubernetes Helm2.11.0 https://github.com/helm/helm
Kubernetes context switching utilities (kubectx and kubens)0.6.2 https://github.com/ahmetb/kubectx
Kubernetes log display utility (stern)1.10.0 https://github.com/wercker/stern

2.2.2. Software Requirements for Minikube Environments

Minikube is the only supported local environment for the DevOps Examples. The CDM is not supported on local environments; it runs in cloud environments only.

Before implementing the DevOps Examples in a local environment, you must install the software listed in "Software Requirements for All Environments" on your computer. You must also install the software listed in the following table on your computer:

SoftwareVersionURL for More Information
VirtualBox5.2.22 https://www.virtualbox.org/wiki/downloads
Minikube0.30.0 http://kubernetes.io/docs/getting-started-guides/minikube

2.2.2.1. Required Workaround for Minikube Environments

To run the DevOps Examples successfully on Minikube, you must work around Minikube issue 1568. Run the following command every time you restart the Minikube virtual machine to enable pods deployed on Minikube to be able to reach themselves on the network:

$ minikube ssh sudo ip link set docker0 promisc on

2.2.3. Software Requirements for GKE Environments

GKE is a supported cloud-based environment for running the DevOps Examples and the CDM.

Before implementing the DevOps Examples and the CDM in a GKE environment, you must install the software listed in "Software Requirements for All Environments" on your computer. You must also install the software listed in the following table on your local computer:

SoftwareVersionURL for More Information
Google Cloud SDK226.0.0 https://cloud.google.com/sdk/downloads

2.2.4. Software Requirements for Amazon EKS Environments

EKS is a supported cloud-based environment for running the DevOps Examples and the CDM.

Before implementing DevOps Examples and the CDM in an Amazon EKS environment, you must install the software listed in "Software Requirements for All Environments" on your computer. You must also install the software listed in the following table on local computer:

SoftwareVersionURL for More Information
Amazon AWS Command Line Interface1.16.61 https://docs.aws.amazon.com/cli/latest/userguide/awscli-install-bundle.html
AWS IAM Authenticator for Kubernetes0.3.0 https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html

After you install the aws-iam-authenticator binary, ensure that the binary is executable and is in the PATH.

Chapter 3. Upgrading

Before upgrading from version 6.0 to version 6.5 of the DevOps Examples, read "What's New" and "Changes and Deprecated Functionality" for information about new, changed, and removed features.

Then perform the following steps to facilitate upgrading to version 6.5:

StepMore Information
Install updated versions of third-party software.

Update to newer versions of third-party software.

See "Installing Required Third-Party Software" for supported third-party software versions.

Clone the updated forgeops repository.

Delete existing clones of the forgeops repository, and then reclone the forgeops repository.

For more information, see "forgeops Repository".

Start with a new Kubernetes namespace.

Before attempting to deploy the DevOps Examples 6.5 examples, create a new namespace.

For more information, see the pertinent sections in "Implementing DevOps Environments" in the DevOps Developer's Guide.

Rebuild and push your Docker images.

If you are not using the evaluation-only Docker images from ForgeRock's public Docker registry, build new Docker images with updated ForgeRock binaries, and then push them to your Docker registry.

Note that the method for building Docker images has changed in version 6.5. The downloader image, which automatically downloads ForgeRock binaries, now serves as the base image for other ForgeRock Docker images.

See "Building and Pushing Docker Images" in the DevOps Developer's Guide for more information.

Upgrade existing ForgeRock component configurations.

Upgrade AM and IDM configurations in your configuration repository.

For more information, see the following sections in the ForgeRock documentation:

Reorganize your custom.yaml files.

For version 6.5, specify custom values for deploying the DevOps Examples in separate .yaml files for each component rather than in a single custom.yaml file.

Review the recommendations for .yaml files in the following sections, and reorganize your .yaml files accordingly:

Install separate Helm charts for the AM and IDM examples instead of composite Helm charts.

For version 6.5, the cmp-am-dj and cmp-idm-dj-postgres Helm charts have been removed from the forgeops repository.

Additionally, the forgerock-charts Helm repository is no longer available.

Change AM deployments to install the openam, amster, and several ds Helm charts from your forgeops repository clone.

Change IDM deployments to install the openidm, ds, and postgres-openidm Helm charts from your forgeops repository clone.

Change IG deployments to install the openig Helm chart from your forgeops repository clone.

For more information, see the following sections:

If necessary, revise your customize-am.sh script.

The customize-am.sh script, described in "Customizing the AM Web Application" in the DevOps Developer's Guide, lets you customize the AM web container before AM starts.

See Environment variables available to the customize-am.sh script have changed in "Changes to Existing Functionality" for more information.

Revise your secure communication configuration.

Communication to ForgeRock Identity Platform services is now secured by a certificate created by the certificate manager. For more information, see "About Securing Communication With ForgeRock Services" in the DevOps Developer's Guide.

Copy your configuration repository's private key into the frconfig Helm chart.

The Kubernetes secret that contains the configuration repository's private key is now built dynamically. The private key must be copied into the frconfig Helm chart before you install this chart. For more information, see "About the Configuration Repository's Private Key" in the DevOps Developer's Guide.

Chapter 4. Changes and Deprecated Functionality

This appendix covers changed, deprecated, and removed features in version 6.5.

4.1. Changes to Existing Functionality

This following table lists changes to existing functionality in version 6.5:

ChangeMore Information
Composite Helm charts for the AM and IDM examples are no longer available.

In version 6.5, the composite Helm charts for the AM and IDM examples have been removed from the forgeops repository. Now you install Helm charts for each required ForgeRock Identity Platform component. This change simplifies deployment troubleshooting.

For more information, see the following sections:

Note that the cmp-am-platform composite Helm chart remains in the forgeops repository for deploying the example in the DevOps Quick Start Guide. Do not use this Helm chart for purposes other than to get started with the DevOps Examples.

The forgerock-charts Helm repository is no longer available.

In previous versions, Helm charts were installed from the forgerock-charts Helm repository.

This Helm repository is no longer available. In version 6.5, install Helm charts from your clone of the forgeops repository.

forgeops repository artifacts have been renamed.

In version 6.5, the opendj Helm chart and Docker image have both been renamed to ds.

.yaml file properties have been modified and reorganized.

Instead of specifying custom values for deploying the DevOps Examples or the CDM in a single custom.yaml file, use separate .yaml files for each component.

For more information about .yaml file revisions, see the following sections:

The method for configuring secure communication has changed.

Communication to ForgeRock Identity Platform services is now secured by a certificate created by the certificate manager. For more information, see "About Securing Communication With ForgeRock Services" in the DevOps Developer's Guide.

Obtaining and storing SSL certificates is now managed by the Kubernetes certificate manager add-on.

In previous versions of the DevOps Examples, you were required to manage the process of obtaining SSL certificates and storing them as Kubernetes secrets.

In version 6.5, the DevOps Examples and the CDM use the Kubernetes certificate manager add-on to automate that process.

For more information, see "About the Configuration Repository's Private Key" in the DevOps Developer's Guide.

Environment variables available to the customize-am.sh script have changed.

The customize-am.sh script, described in "Customizing the AM Web Application" in the DevOps Developer's Guide, lets you customize the AM web container before AM starts.

The set of environment variables that can be accessed by the customize-am.sh script has changed in version 6.5.

If you use the customize-am.sh script in an existing AM deployment, review your script before orchestrating version 6.5 of the DevOps Examples as follows:

  1. If you have not already done so, include the env command in your script, as shown in the example script in "Customizing the AM Web Application" in the DevOps Developer's Guide.

  2. Orchestrate AM.

  3. Review the logs from the openam container in the openam pod. Use a command similar to the following:

    $ kubectl logs openam-xxxxxxxxxx-yyyyy -c openam

The DevOps Guide has been renamed.

The DevOps Guide has been renamed to the DevOps Developer's Guide.

With the introduction of the CDM, the DevOps Developer's Guide is now aimed primarily at developers. Production deployment is addressed by the new CDM Cookbooks and Site Reliability Guides.

For more information about ForgeRock DevOps documentation, see the "Documentation Roadmap" in the Start Here document.

IDM is deployed using a StatefulSet object.

In version 6.5, the openidm pod is deployed using a StatefulSet object to achieve greater stability.

In previous releases, the IDM pod was deployed using a Deployment object.

The IDM configuration is read-only (immutable) by default.

IDM 6.5 includes a new option for making its configuration read-only. By default, the DevOps Examples and the CDM run with read-only configuration for IDM.

Set the openidm Helm chart's config.immutable key to false to make IDM's configuration read/write.

For more information, see "openidm.yaml" in the DevOps Developer's Guide.

The IG example runs in production mode.

In version 6.5, IG deployments are configured with read-only configuration. The IG documentation refers to read-only configuration as production mode.

Note that IG Studio is not available for IG production mode deployments. In previous releases of the DevOps Examples, IG ran in development mode, and IG Studio was available.

The default AM server URL has changed.

In version 6.5, the default AM server URL is now https://login.my-namespace.example.com.

In previous versions of the DevOps Examples, the default AM server URL was http://openam.my-namespace.example.com/openam.

4.2. Deprecated Features

The following features are deprecated in version 6.5 of the DevOps Examples:

FeatureMore Information

sedFilter key in the openidm Helm chart

Support for using the sedFilter key in the openidm Helm chart is deprecated.

After issue OPENIDM-11529 has been resolved, you will be able to use IDM configuration expressions for pattern substitution. At that time, support for the sedFilter key will be removed from all Helm charts in the DevOps Examples.

4.3. Removed Features

The following features have been removed from version 6.5 of the DevOps Examples:

FeatureMore Information
AM and IDM composite Helm charts

The cmp-am-dj and cmp-idm-dj-postgres Helm charts have been removed from the forgeops repository. Instead of installing these Helm charts, install one or more non-composite charts.

For more information, see the following sections:

numberSampleUsers key in the ds Helm chart

The numberSampleUsers key is no longer used to specify an initial number of sample users to be created in DS directories. Instead, the ds Docker image is pre-built with a small number of sample user entries.

If you need a larger number of sample user entries in your DS directories, create a customized Docker DS image.

useTLS key in several Helm charts

The useTLS key is no longer supported. Communication to ForgeRock Identity Platform services is now secured by a certificate created by the certificate manager. For more information, see "About Securing Communication With ForgeRock Services" in the DevOps Developer's Guide.

sedFilter key in the openam and openig Helm charts

The sedFilter key is no longer supported in the openam and openig Helm charts. Use AM and IG configuration expressions to substitute text in a configuration instead of specifying a sedFilter Helm chart key.

Note that the sedFilter key in the openidm Helm chart is deprecated.

Chapter 5. Limitations

This chapter covers release 6.5 limitations.

5.1. DS Limitations

DS live data and logs should reside on fast disks.

DS data requires high performance, low latency disk. Use external volumes on solid-state drives (SSDs) for directory data when running in production. Do not use network file systems such as NFS except for storing directory backups.

DS does not scale elastically.

DS does not support elastic scaling. Be sure to design your DS deployment architecture carefully, with this limitation in mind.

The dsreplication command cannot run in a container.

The dsreplication command does not support configuration expressions, which are used by artifacts in the forgeops repository. Therefore, do not execute the dsreplication command in a Kubernetes pod.

For more information, see Setting Up Replication in the Directory Services Deployment Guide.

The DS restore command must be used if you need to recover DS directory data.

You cannot use the dsreplication command with a DS instance in a replication topology, because the command cannot run using configuration expressions for property value substitution. To restore directory data, use the DS restore command. For information about restoring directory data from a backup in a DevOps environment, see "Using CDM Restore" in the Site Reliability Guide for GKE.

Fully test your backup and recovery procedures before deploying DS in a production DevOps environment. Failure to do so might result in data loss.

5.2. AM Limitations

Several AM operations are stateful.

Several operations in AM are stateful, requiring flows to return to the same server instance several times. For example, browser-based authentication that uses authentication chains and SAML flows are both stateful operations. If your deployment uses any stateful AM operations, you must configure your load balancer to use sticky sessions.

Even if your deployment does not use any stateful AM operations, it is recommended that you configure your load balancer to use sticky sessions to achieve better performance.

SAML single logout is not supported.

SAML single logout is not supported when you run AM in a container because it is stateful and requires server identity.

5.3. DevOps Examples Limitations

Docker images are not available for use in production deployments.

Docker images for use in production deployments of the ForgeRock Identity Platform are not available. Unsupported, evaluation-only images are available from ForgeRock's public Docker registry. These images can be used for evaluation purposes only. For more information, see "Building and Pushing Docker Images" in the DevOps Developer's Guide.

When deploying ForgeRock Identity Platform in production, you must build Docker images. For more information about building images for the ForgeRock Identity Platform, see "Building and Pushing Docker Images" in the DevOps Developer's Guide.

Docker images with the ssoadm command are not available.

The DevOps Examples do not include example deployments of the AM ssoadm command. However, you can use the AM REST API and the amster command with the AM and DS deployment example.

The IDM repository is not configured for high availablity.

The IDM repository configuration used with the DevOps Examples is not suitable for production deployments. When running IDM in production, configure your repository for high availability. For more information about ensuring high availability of the identity management service, see Clustering, Failover, and Availability in the ForgeRock Identity Management Integrator's Guide.

Chapter 6. Documentation Updates

The following changes have been made to the documentation since the release of 6.5 of the DevOps Examples and the CDM:

DateDescription
2018-12-14

Updated and moved the architecture diagrams in the following sections:

Corrected the steps and terminal window output in the following procedures:

Mentioned in "Changes and Deprecated Functionality" that the forgerock-charts Helm repository is no longer available, and that users should now access Helm charts from their forgeops repository clones.

Mentioned in "Changes and Deprecated Functionality" that the IG example now runs in production mode; therefore, IG cannot be accessed after you deploy the example.

Corrected "Secure Communication With ForgeRock Identity Platform Services" in the DevOps Quick Start Guide, which incorrectly stated that the DevOps Examples use insecure communication over HTTP. The section now states that they use secure communication over HTTPS.

Changed the term Google Filestore to use Google's new branding, Cloud Filestore.

Removed all text that stated that backups are scheduled as part of CDM deployment. CDM benchmarks were run on deployments in which DS backups were not scheduled.

In "frconfig.yaml" in the DevOps Developer's Guide, changed the default value in the frconfig.yaml file example from release/6.5.0 to my-branch. In version 6.5, the forgeops-init repository maintains ForgeRock Identity Platform configurations in directories rather than branches. For more information, see the forgeops-init repository README file.

2018-11-30

Released version 6.5 of the DevOps Examples and the CDM.

Appendix A. Getting Support

This appendix contains information about support options for the ForgeRock DevOps Examples and the ForgeRock Identity Platform.

A.1. Statement of Support

The ForgeRock DevOps Examples, the CDM, and the accompanying Git repository demonstrate deployment in a containerized environment using DevOps techniques. You are responsible for adapting the examples to suit your production requirements. These resources are provided for demonstration purposes only. Commercial support for the DevOps Examples and the CDM is not available from ForgeRock.

ForgeRock does not support production deployments that use the evaluation-only Docker images described in "Using the Evaluation-Only Docker Images" in the DevOps Developer's Guide. When deploying the ForgeRock Identity Platform by using Docker images, you must build and use your own images for production deployments. For information about how to build Docker images for the ForgeRock Identity Platform, see "Using the Evaluation-Only Docker Images" in the DevOps Developer's Guide.

ForgeRock provides commercial support for the ForgeRock Identity Platform only. For supported components, containers, and Java versions, see the following:

ForgeRock does not provide support for software that is not part of the ForgeRock Identity Platform, such as Docker, Kubernetes, Java, Apache Tomcat, NGINX, Apache HTTP Server, and so forth.

A.2. Accessing Documentation Online

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 product documentation, such as this document, aims to be technically accurate and complete with respect to the software documented. It is visible to everyone and covers all product features and examples of how to use them.

A.3. How to Report Problems or Provide Feedback

If you have questions regarding the DevOps Examples or the CDM that are not answered by the documentation, you can ask questions on the DevOps forum at https://forum.forgerock.com/forum/devops.

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.

  • Description of the environment, including the following information:

    • Environment type (Minikube, GKE, or EKS).

    • Software versions of supporting components:

      • Oracle VirtualBox (Minikube environments only).

      • Docker client (all environments).

      • Minikube (all environments).

      • kubectl command (all environments).

      • Kubernetes Helm (all environments).

      • Google Cloud SDK (GKE environments only).

      • Amazon AWS Command Line Interface (EKS environments only).

    • forgeops repository branch.

    • Any patches or other software that might be affecting the problem.

  • Steps to reproduce the problem.

  • HTML output from the debug-logs.sh script. For more information, see "Running the debug-logs.sh Script" in the DevOps Developer's Guide.

A.4. Getting Support and Contacting ForgeRock

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, visit https://www.forgerock.com, or send an email to ForgeRock at info@forgerock.com.

Read a different version of :