Repositories
The ForgeOps project provides two public GitHub repositories; the forgeops and
forgeops-extras repositories.
This page provides a high-level overview of the two repositories.
forgeops repository
The forgeops 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
-
-
Helm charts
-
Kustomize bases and overlays
In addition, the repository contains numerous utility scripts and sample files. The scripts and samples are useful for:
-
Performing ForgeOps deployments quickly and easily
-
Exploring monitoring, alerts, and security customization
Refer to forgeops repository reference for information about the files in the repository,
recommendations about how to work with them, and the support status for the
files.
forgeops repository updates
New forgeops repository features become available in the release/7.5-20240402
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. Refer to
Git clone or Git fork? for more information.
Then, check out the release/7.5-20240402 branch and create a working branch. For
example:
$ git checkout release/7.5-20240402 $ git checkout -b my-working-branch
ForgeRock recommends that you regularly incorporate updates to the
release/7.5-20240402 into your working branch:
-
Get emails or subscribe to the ForgeOps RSS feed to be notified when there have been updates to ForgeOps 7.5.
-
Pull new commits in the
release/7.5-20240402branch into your clone’srelease/7.5-20240402branch. -
Rebase the commits from the new branch into your working branch in your
forgeopsrepository clone.
It’s important to understand the impact of rebasing changes from the forgeops
repository into your branches. forgeops 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
forgeops 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.5-20240402 branch.
forgeops repository reference
For more information about support for the forgeops repository, see
Support from ForgeRock.
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.
charts
Helm charts.
Recommendation: Don’t modify the files in this directory. If you want to update a values.yaml file, copy the file to a new file, and make changes there.
Support Status: Supported is available from ForgeRock.
cluster
Example script that automates Minikube cluster creation.
Recommendation: Don’t modify the files in this directory.
Support Status: Sample file. Not supported by ForgeRock.
docker
Contains three types of files needed to build Docker images for the ForgeRock Identity Platform: Dockerfiles, support files that go into Docker images, and configuration profiles.
Dockerfiles
Common deployment customizations require modifications to Dockerfiles in the docker directory.
Recommendation: Expect to encounter merge conflicts when you rebase changes from ForgeRock into your branches. Be sure to track changes you’ve made to Dockerfiles, so that you’re prepared to resolve merge conflicts after a rebase.
Support Status: Dockerfiles. Support is available from ForgeRock.
Support Files Referenced by Dockerfiles
When customizing ForgeRock’s default deployments, you might need to add files to the docker directory. For example, to customize the AM WAR file, you might need to add plugin JAR files, user interface customization files, or image files.
Recommendation: If you only add new files to the docker directory, you should not encounter merge conflicts when you rebase changes from ForgeRock 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:
Scripts and other files from ForgeRock that are incorporated into Docker images for the ForgeRock Identity Platform: Support is available from ForgeRock.
User customizations that are incorporated into custom Docker images for the ForgeRock Identity Platform: Support is not available from ForgeRock.
Configuration Profiles
Add your own configuration profiles to the docker directory using the
export command. Do not modify ForgeRock’s internal-use only
idm-only and ig-only configuration profiles.
Recommendation: You should not encounter merge conflicts when you rebase changes from ForgeRock into your branches.
Support Status: Configuration profiles. Support is available from ForgeRock.
etc
Files used to support ForgeOps deployments.
Recommendation: Don’t modify the files in this directory (or its subdirectories).
Support Status: Sample files. Not supported by ForgeRock.
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 directory. You’ll probably change, at minimum, the kustomize/overlay/all/kustomization.yaml file.
Expect to encounter merge conflicts when you rebase changes 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 performing ForgeOps deployments using older versions. 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.
forgeops-extras repository
Use ForgeRock’s forgeops-extras repository to create sample Kubernetes clusters in which you can deploy the ForgeRock Identity Platform.
forgeops-extras repository reference
For more information about support for the forgeops-extras repository, see
Support from ForgeRock.
Directories
terraform
Example Terraform artifacts that automate cluster creation and deletion.
Recommendation: Don’t modify the files in this directory. If you want to add
your own cluster creation support files to the forgeops repository, copy the
terraform.tfvars file to a new file and make changes there.
Support Status: Sample files. Not supported by ForgeRock.
Git clone or Git fork?
For the simplest use cases—a single user in an organization performing a ForgeOps deployment for a proof of concept, or exploration of the platform—cloning ForgeRock’s public repositories from GitHub provides a quick and adequate way to access the repositories.
If, however, your use case is more complex, you might want to fork the repositories, and use the forks as your common upstream repositories. 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
forgeopsandforgeops-extrasrepository changes from ForgeRock. -
Your organization wants to use pull requests when making repository updates.
If you’ve forked the forgeops and forgeops-extras repositories:
-
You’ll need to synchronize your forks with ForgeRock’s public repositories on GitHub when ForgeRock releases new branches.
-
Your users will need to clone your forks before they start working instead of cloning the public repositories from GitHub. Because procedures in the documentation tell users to clone the public repositories, 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 clones will differ from the steps provided in the documentation. You’ll need to let users know how to work with the forks as the upstream repositories instead of following the steps in the documentation.