ForgeOps

Azure

forgeops and forgeops-extras repositories

Get the forgeops and forgeops-extras repositories:

  1. Clone the repositories. For example:

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

    Both repositories are public; you do not need credentials to clone them.

  2. Check out the forgeops repository’s release/7.5-20240402 branch:

    $ cd /path/to/forgeops
$ git checkout release/7.5-20240402

    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.5-20240402 branch. For more information, refer to Repository Updates.

  3. Check out the forgeops-extras repository’s master branch:

    $ cd /path/to/forgeops-extras
$ git checkout master

Third-party software

Before performing a ForgeOps deployment, 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[1] .

The versions listed in the following table have been validated for ForgeOps deployments on Microsoft Azure. 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.11.8

python@3.11

Docker client

25.0.3

docker

Kubernetes client (kubectl)

1.29.3

kubernetes-cli

Kubernetes context switcher (kubectx)

0.9.5

kubectx

Kustomize

5.3.0

kustomize

Helm

3.14.3

helm

JSON processor jq

1.7.1

jq

Terraform

1.5.7

terraform

Six (Python compatibility library)

1.16.0

six

Setup tools (Python)

69.2.0

python-setuptools

Azure Command Line Interface

2.58.0

azure-cli

Docker engine

In addition to the software listed in the preceding table, you’ll need to start a virtual machine that runs Docker engine.

For more information about using Colima when performing ForgeOps deployments, refer to this article.

The default configuration for a Docker virtual machine provides adequate resources for a ForgeOps deployment.

For users running Microsoft Windows

ForgeRock supports ForgeOps deployments on macOS and Linux. If you have a Windows computer, you’ll need to create a Linux VM. We tested the following configurations:

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

  • Guest OS: Current Ubuntu LTS release 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 attempt to perform ForgeOps deployments on WSL2 until this issue is resolved.

Azure subscription setup

Perform these steps to set up an Azure subscription that meets the requirements for ForgeOps deployments:

  1. Assign the following roles to users who will perform ForgeOps deployments:

    • Azure Kubernetes Service Cluster Admin Role

    • Azure Kubernetes Service Cluster User Role

    • Contributor

    • User Access Administrator

    Remember, a ForgeOps deployment is a reference implementation, and is not for production use. The roles you assign in this step are suitable for ForgeOps deployments. 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 perform the ForgeOps deployment:

    $ az account set --subscription my-subscription-id

Kubernetes cluster creation

ForgeRock provides Terraform artifacts for AKS cluster creation. Use them to create a cluster that supports ForgeOps deployments. After performing a ForgeOps deployment, you can use your cluster as a sandbox to explore ForgeRock Identity Platform customization.

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

Here are the steps the ForgeOps team follows to create a Kubernetes cluster on AKS:

  1. Copy the file that contains default Terraform variables to a new file:

    1. Change to the /path/to/forgeops-extras/terraform directory.

    2. Copy the terraform.tfvars file to override.auto.tfvars [2].

    Copying the terraform.tfvars file to a new file preserves the original content in the file.

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

  3. Define your cluster’s configuration:

    1. Open the override.auto.tfvars file.

    2. Determine the location of your cluster’s configuration in the override.auto.tfvars file:

      Cluster size Section containing the cluster configuration

      Small

      cluster.tf_cluster_aks_small

      Medium

      cluster.tf_cluster_aks_medium

      Large

      cluster.tf_cluster_aks_large

    3. Modify your cluster’s configuration by setting values in the section listed in the table:

      1. Set the value of the enabled variable to true.

      2. Set the value of the meta.cluster_name variable to the name of the AKS cluster you’ll create.

      3. Set the values of the location.region and location.zones variables to the region and zones where you’ll perform the ForgeOps deployment.

        Before continuing, go to Microsoft’s Products available by region page and verify that Azure Kubernetes Service is available in the region you specified.

    4. Save and close the override.auto.tfvars file.

  4. Ensure your region has an adequate CPU quota for a ForgeOps deployment.

    Locate these two variables in your cluster’s configuration in the override.auto.tfvars file:

    • node_pool.type: the machine type to be used in your cluster

    • node_pool.max_count: the maximum number of machines to be used in your cluster

    Your quotas must be large enough to let you allocate the maximum number of machines in your region. If your quotas are too low, request and wait for a quota increase from Microsoft Azure before attempting to create your cluster.

  5. Create a cluster using Terraform artifacts in the forgeops-extras repository:

    1. Change to the directory that contains Terraform artifacts:

      $ cd /path/to/forgeops-extras/terraform

    2. Run the tf-apply script to create your cluster:

      $ ./tf-apply

      Respond yes to the Do you want to perform these actions? prompt.

      When the tf-apply script finishes, it issues a message that provides the path to a kubeconfig file for the cluster.

      The script creates:

      • The AKS cluster

      • The fast storage class

      • The ds-snapshot-class volume snapshot class

      The script deploys:

      • An ingress controller

      • Certificate manager

  6. Set your Kubernetes context to reference the new cluster by setting the KUBECONFIG environment variable as shown in the message from the tf-apply command’s output.

  7. To verify that the tf-apply script created the cluster, log in to the Azure portal. Search for Kubernetes services and access the Kubernetes services page. The new cluster should appear in the list of Kubernetes clusters.

Hostname resolution

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

  1. Get the ingress controller’s external IP address:

    $ kubectl get services --namespace ingress-nginx
NAME                                 TYPE           CLUSTER-IP     EXTERNAL-IP     PORT(S)                      AGE
ingress-nginx-controller             LoadBalancer   10.0.166.247   20.168.193.68   80:31377/TCP,443:31099/TCP   74m
ingress-nginx-controller-admission   ClusterIP      10.0.40.40     <none>          443/TCP                      74m

    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.

  2. Configure hostname resolution for the ingress controller:

    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 forgeops.example.com as the deployment FQDN. You are not required to use forgeops.example.com; you can specify any FQDN you like.

    2. If DNS does not resolve your deployment FQDN, add an entry to the /etc/hosts file that maps the ingress controller’s external IP address to the deployment FQDN. For example:

      20.168.193.68 forgeops.example.com
1. 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.
2. The Terraform configuration contains a set of variables under forgerock that adds labels required for clusters created by ForgeRock employees. If you’re a ForgeRock employee creating a cluster, set values for these variables.
Copyright © 2010-2024 ForgeRock, all rights reserved.