Environment Setup: Minikube

This section describes how to set up your local computer for developing custom Docker images for the ForgeRock Identity Platform on 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.

Tasks to set up your local computer:

  1. forgeops Repository

  2. Third-Party Software

  3. Minikube Virtual Machine

  4. Namespace

  5. Hostname Resolution

  6. Minikube’s Docker Engine

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

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:

    $ 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 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 install a set of third-party software on your local computer.

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

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

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

VirtualBox

6.1.10

virtualbox (cask)[3]

Minikube

1.12.0

minikube

Minikube Virtual Machine

Now that you’ve installed third-party software on your local computer, you’re ready to create a Minikube VM. When you create a Minikube VM, a Kubernetes cluster is created in the VM.

The following configuration has been validated for building custom Docker images for the ForgeRock Identity Platform:

  • Kubernetes version: 1.17.4

  • Memory: 12 GB or more

  • Disk space: 40 GB or more

Perform the following procedure to set up Minikube:

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 \
 --vm-driver=virtualbox --bootstrapper kubeadm --kubernetes-version=1.17.4
😄  minikube v1.12.1 on Darwin 10.15.6
✨  Using the virtualbox driver based on user configuration
🔥  Creating virtualbox VM (CPUs=3, Memory=12288MB, Disk=40960MB) …​
🐳  Preparing Kubernetes v1.17.4 on Docker 19.03.12 …​
🔎  Verifying Kubernetes components…​
🌟  Enabling addons: default-storageclass, storage-provisioner
🏄  Done! kubectl is now configured to use "minikube"

  2. Run the following command to enable the ingress controller plugin built into Minikube:

    $ minikube addons enable ingress
🌟  The 'ingress' addon is enabled

  3. Before attempting to work with the ForgeRock Identity Platform on Minikube, you must implement the workaround for Minikube issue 1568. The workaround lets pods deployed on Minikube reach themselves on the network.

    Run the following command to work around the issue:

    $ minikube ssh sudo ip link set docker0 promisc on

    Note that you must run this command every time you restart the Minikube VM.

Namespace

After you’ve created the Minikube VM and Kubernetes cluster, 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.

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

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

    $ minikube ip
111.222.33.44

  2. Add an entry similar to the following to the /etc/hosts file:

    minikube-ip-address my-namespace.iam.example.com

Minikube’s Docker Engine

Now you’ve prepared your cluster by creating a namespace and setting up hostname resolution. Your last step before you can deploy the ForgeRock Identity Platform is to set up your local computer 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.

Set up your local computer to use Minikube’s Docker engine as follows:

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 [4]:

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

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. If your cluster’s context is not minikube, replace minikube with the actual context name in the skaffold config set command.