Environment Setup: Shared Cloud Cluster

This section describes how to set up your local computer before you start developing custom Docker images for the ForgeRock Identity Platform.

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.

Jump to the section that contains the setup activities for the type of cluster you’ll be working on:

When you’ve completed the setup tasks, you’ll have an environment like the one shown in this diagram.

GKE Cluster

This section is for users developing custom Docker images for the ForgeRock Identity Platform on a shared GKE cluster.

Tasks to set up your local computer:

forgeops Repository

Before you can deploy the CDK or the CDM, you must first get the forgeops repository:[1]

Obtain the forgeops Repository
  1. Clone the forgeops repository:

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

  2. Check out the 2020.08.07-ZucchiniRicotta.1 release tag, creating a branch named my-branch:

    $ cd forgeops
    $ git checkout tags/2020.08.07-ZucchiniRicotta.1 -b my-branch
    Switched to a new branch 'my-branch'

Third-Party Software

After you’ve obtained the forgeops repository, you’ll need to get non-ForgeRock software and install it on your local computer.

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

The versions listed in the tables 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 tables, it is your responsibility to validate them.

Install the following third-party software:

Software Version Homebrew package

Docker Desktop[2]

2.3.0.3

docker (cask)[3]

Kubernetes client (kubectl)

1.18.6

kubernetes-cli

Skaffold

1.12.1

skaffold

Kustomize

3.8.1

kustomize

Kubernetes context switcher (kubectx)

0.9.1

kubectx

Google Cloud SDK

303.0.0

google-cloud-sdk (cask)[3]

Getting Cluster Details

Next, 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.

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.

Context for the Shared Cluster

You’ve now installed third-party software on your local computer and obtained some details about the cluster. You’re ready to create a context on your local computer to enable access to 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.

Perform the following procedure to create a context for the shared cluster:

Create a Context for a GKE 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 in this procedure.

  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.

Namespace

After you’ve created a context for the shared cluster, create a namespace in the 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.

Perform the following procedure to create a namespace:

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

Hostname Resolution

After you’ve created a namespace, 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.

    The hosts file is located at /etc/hosts

docker push Setup

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.

Perform the following procedure:

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 the previous step:

    $ skaffold config set default-repo my-docker-registry -k my-kubernetes-context

You’re now ready to deploy the ForgeRock Identity Platform in your namespace. Proceed to CDK Deployment.

EKS Cluster

This section is for users developing custom Docker images for the ForgeRock Identity Platform on a shared EKS cluster.

Tasks to set up your local computer:

forgeops Repository

Before you can deploy the CDK or the CDM, you must first get the forgeops repository:[1]

Obtain the forgeops Repository
  1. Clone the forgeops repository:

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

  2. Check out the 2020.08.07-ZucchiniRicotta.1 release tag, creating a branch named my-branch:

    $ cd forgeops
    $ git checkout tags/2020.08.07-ZucchiniRicotta.1 -b my-branch
    Switched to a new branch 'my-branch'

Third-Party Software

After you’ve obtained the forgeops repository, you’ll need to get non-ForgeRock software and install it on your local computer.

ForgeRock recommends that you install third-party software using Homebrew on macOS and Linux. For a list of the Homebrew packages to install, see Homebrew Package Names.

The versions listed in the tables 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 tables, it is your responsibility to validate them.

Install the following third-party software:

Software Version Homebrew package

Docker Desktop[4]

2.3.0.3

docker (cask)[5]

Kubernetes client (kubectl)

1.18.6

kubernetes-cli

Skaffold

1.12.1

skaffold

Kustomize

3.8.1

kustomize

Kubernetes context switcher (kubectx)

0.9.1

kubectx

Amazon AWS Command Line Interface

2.0.40

awscli

AWS IAM Authenticator for Kubernetes

0.5.1

aws-iam-authenticator

Getting Cluster Details

Next, 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.

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.

Context for the Shared Cluster

You’ve now installed third-party software on your local computer and obtained some details about the cluster. You’re ready to create a context on your local computer to enable access to 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.

Perform the following procedure to create a context for the shared cluster:

Create a Context for an EKS 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 in this procedure.

  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.

Namespace

After you’ve created a context for the shared cluster, create a namespace in the 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.

Perform the following procedure to create a namespace:

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

Hostname Resolution

After you’ve created a namespace, 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.

docker push Setup

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.

Perform the following procedure:

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.[6]

  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

You’re now ready to deploy the ForgeRock Identity Platform in your namespace. Proceed to CDK Deployment.

AKS Cluster

This section is for users developing custom Docker images for the ForgeRock Identity Platform on a shared AKS cluster.

Tasks to set up your local computer:

forgeops Repository

Before you can deploy the CDK or the CDM, you must first get the forgeops repository:[1]

Obtain the forgeops Repository
  1. Clone the forgeops repository:

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

  2. Check out the 2020.08.07-ZucchiniRicotta.1 release tag, creating a branch named my-branch:

    $ cd forgeops
    $ git checkout tags/2020.08.07-ZucchiniRicotta.1 -b my-branch
    Switched to a new branch 'my-branch'

Third-Party Software

After you’ve obtained the forgeops repository, you’ll need to get non-ForgeRock software and install it on your local computer.

ForgeRock recommends that you install third-party software using Homebrew on macOS and Linux. For a list of the Homebrew packages to install, see Homebrew Package Names.

The versions listed in the tables 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 tables, it is your responsibility to validate them.

Install the following third-party software:

Software Version Homebrew package

Docker Desktop[7]

2.3.0.3

docker (cask)[8]

Kubernetes client (kubectl)

1.18.6

kubernetes-cli

Skaffold

1.12.1

skaffold

Kustomize

3.8.1

kustomize

Kubernetes context switcher (kubectx)

0.9.1

kubectx

Azure Command Line Interface

2.10.1

azure-cli

Getting Cluster Details

Next, 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.

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.

Context for the Shared Cluster

You’ve now installed third-party software on your local computer and obtained some details about the cluster. You’re ready to create a context on your local computer to enable access to 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.

Perform the following procedure to create a context for the shared cluster:

Create a Context for an AKS 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 in this procedure.

  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.

Namespace

After you’ve created a context for the shared cluster, create a namespace in the 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.

Perform the following procedure to create a namespace:

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

Hostname Resolution

After you’ve created a namespace, 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.

docker push Setup

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.

Perform the following procedure:

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 the previous step:

    $ skaffold config set default-repo my-docker-registry -k my-kubernetes-context

You’re now ready to deploy the ForgeRock Identity Platform in your namespace. Proceed to CDK Deployment.


1. For the short term, follow the steps in the procedure to clone the forgeops repository and check out the 2020.08.07-ZucchiniRicotta.1 tag. For the long term, you’ll need to implement a strategy for managing updates, especially if a team of people in your organization works with the repository. For example, you might want to adopt a workflow that uses a fork as your organization’s common upstream repository. For more information, see About the forgeops Repository.
2. Install Docker Desktop on macOS. On Linux computers, install Docker CE instead. For more information, see the Docker documentation.
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 for this package. Instead, refer to the package’s documentation for installation instructions.
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 for this package. Instead, refer to the package’s documentation for installation instructions.
6. You can automate logging into ECR every 12 hours by using the cron utility.
7. Install Docker Desktop on macOS. On Linux computers, install Docker CE instead. For more information, see the Docker documentation.
8. 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 for this package. Instead, refer to the package’s documentation for installation instructions.