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:
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]
-
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. -
Check out the
2020.08.07-ZucchiniRicotta.1
release tag, creating a branch namedmy-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 |
|
Kubernetes client ( |
1.18.6 |
|
Skaffold |
1.12.1 |
|
Kustomize |
3.8.1 |
|
Kubernetes context switcher ( |
0.9.1 |
|
VirtualBox |
6.1.10 |
|
Minikube |
1.12.0 |
|
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:
-
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"
-
Run the following command to enable the ingress controller plugin built into Minikube:
$ minikube addons enable ingress 🌟 The 'ingress' addon is enabled
-
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 in your Kubernetes cluster:
$ kubectl create namespace my-namespace namespace/my-namespace created
-
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.
-
Run the
minikube ip
command to get the Minikube ingress controller’s IP address:$ minikube ip 111.222.33.44
-
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:
-
Run the
docker-env
command in your shell:$ eval $(minikube docker-env)
-
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.
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.
minikube
, replace minikube
with the actual context name in the skaffold config set
command.