Deploy Autonomous Identity on MacOS

This section shows you how to install and deploy Autonomous Identity using Minikube, Kubernetes, and Docker on a MacOS laptop or computer. This example shows you how easy it is to deploy Autonomous Identity locally on your computer.

This example setup is only for evaluation purposes and should not be used for production deployments.

This example uses a combination of components like Docker, Kubernetes, Minikube, and Hyperkit to deploy Autonomous Identity on your computer or laptop.

  • Docker is a popular tool that packages software and their dependencies into their own containers.

  • Kubernetes is an open-source orchestration platform that provides deployment, scaling, and load management across multiple containers, allowing you to run a microservices architecture.

  • Minikube is an open-source tool that lets you run a single-node Kubernetes cluster virtually on your local machine.

  • Hyperkit is a MacOS-based hypervisor that runs and manages virtual machines like Minikube.

See a simple image of this deployment

* Deployment Procedures*

Let’s set up Autonomous Identity on MacOS.

Prerequisites
  • Hardware: MacBook Pro, 16 cores, 32GB RAM

  • Software: Homebrew for downloading third-party components

    Minimum OS: MacOS Catalina, version 10.15.4

Install Minikube
  1. Download and install Minikube. If you already have minikube, make sure to upgrade to v1.9.2, which fixes NFS share mounting issues with the Hyperkit driver.

    $ brew install minikube
  2. Create a bin directory.

    $ mkdir ~/bin
  3. Create a minikube directory.

    $ sudo mkdir /Users/minikube
  4. Change the privileges.

    $ sudo chown $USER /Users/minikube
  5. Create a startup script.

    $ echo "minikube start --vm-driver=hyperkit --cpus 12 --memory 14336 --disk-size=50GB --nfs-share /Users/minikube --addons metrics-server" > ~/bin/start-minikube.sh
  6. Make the script executable.

    $ chmod +x ~/bin/start-minikube.sh
  7. Export to $PATH.

    $ echo -e "\nexport PATH=~/bin:$PATH" >> ~/.bash_profile
  8. Start Minikube.

    $ minikube.sh
    
    minikube v1.9.2 on Darwin 10.15.4
    Using the hyperkit driver based on user configuration
    Starting control plane node m01 in cluster minikube
    Creating hyperkit VM (CPUs=10, Memory=14336MB, Disk=51200MB) …​
    Password:
    Preparing Kubernetes v1.18.0 on Docker 19.03.8 …​
    Enabling addons: default-storageclass, metrics-server, storage-provisioner
    Done! kubectl is now configured to use "minikube"
  9. Check that Minikube is running.

    $ minikube status
    
    m01
    host: Running
    kubelet: Running
    apiserver: Running
    kubeconfig: Configured
Deploy the Components in Minikube
  1. Create a directory for the Autonomous Identity repository.

    $ mkdir -p ~/repo/autoid
  2. Change to the directory.

    $ cd ~/repo/autoid
  3. Clone a kubernetes folder that holds the configuration files from the ForgeRock repo.

    $ git clone ssh://git@stash.forgerock.org:7999/opt/autoid/kubernetes.git
  4. Change to the kubernetes directory.

    $ cd kubernetes
  5. Check out the branch.

    $ git checkout -b zoran-kubernetes origin/zoran-kubernetes-poc
  6. Make an analytics folder. This folder holds the example input files for ingestion.

    $ mkdir -p /Users/minikube/autoid-data/analytics
  7. Process the kustomize directory to create the microservices.

    $ kubectl create -k .
  8. List all pods in ps output format, and then wait for all pods to be in a "running" state. Note that you may see some errors for the pods: Error, CrashLoopBackOff, ErrImagePull, or ImagePullBackoff. These errors indicate that the pods are waiting for their dependencies to start. Continue waiting until all pods go into a "running" state.

    $ kubectl get pods -w
    
    NAME                            READY   STATUS              RESTARTS   AGE
    cassandra-db                    1/1     Running             0          28m
    cli                             1/1     Running             0          28m
    configuration-service           1/1     Running             0          28m
    consul-client                   1/1     Running             7          28m
    consul-server                   1/1     Running             0          28m
    nginx                           1/1     Running             0          28m
    openldap                        1/1     Running             0          28m
    phpldapadmin                    1/1     Running             0          28m
    selfservice                     1/1     Running             0          28m
    spark-56f58889fd-kbxdv          1/1     Running             0          28m
    spark-slaves-7f7674d5fc-7xjk8   1/1     Running             0          28m
    spark-slaves-7f7674d5fc-9dprx   1/1     Running             0          28m
    spark-slaves-7f7674d5fc-pfg5n   1/1     Running             0          28m
    spark-slaves-7f7674d5fc-wlvpp   1/1     Running             0          28m
    zoran-api                       1/1     Running             0          28m
    zoran-ui                        1/1     Running             0          28m
Run the Analytics Engine on MacOS
  1. Copy the Demo Data into the Analytics folder.

    $ cp demo-data/* /Users/minikube/autoid-data/analytics
  2. Run the Analytics Pipeline.

    $ kubectl exec cli — run-pipeline
Access the Autonomous Identity UI
  1. Find out what your IP address is on Minikube.

    $ minikube ip
  2. Update your /etc/hosts file to map your minikube IP to the UI. Open an editor and add your Minikube IP address to the /etc/hosts . For example, assume your Minikube IP address is 192.168.64.29, then update your /etc/hosts file as follows:

    192.168.64.29  zoran-ui.nip.io
  3. Open a browser and navigate to http://zoran-ui.nip.io:30080/.

  4. To log in to Autonomous Identity, enter a test admin user: bob.rodgers; password: Welcom123.

  5. Access a self-service UI if you want to change your Autonomous Identity password: http://zoran-ui.nip.io:30070/

  6. If you want to access the Apache Spark console: http://zoran-ui.nip.io:30088/

Stop the Autonomous Identity
  • Stop Autonomous Identity

    $ docker stop $(docker ps -a -q)
Troubleshooting Tips

This section presents some troubleshooting tips when running the evaluation version of Autonomous Identity:

  • If you run low on memory, you can safely shutdown Minikube without losing data. All data in Cassandra, Consul, OpenLDAP are stored in Minikube using persistent volumes. You can access the data by running minikube ssh and going to the /data folder.

  • Analytics jobs are quite compute intensive. You can speed up the analytics job if you can dedicate more resources for Minikube.

    • Alter the Minikube parameters to increase the CPU cound and memory.

    • Increase the number of Spark slaves by changing the variables replicas in spark-slaves.yaml .

    • While running the analytics scripts, set --num-executors to the number of spark slaves.

    • Make sure the --executor-memory multiplied by the number of spark slaves is well within the memory allocated to Minikube.

    • If you change the Minikube resource allocation, delete the existing cluster and re-create.

    • To troubleshoot performance issues or pod crashes, run the Kubernetes dashboard. First, check if the metrics-server is running kubectl top node. It should show an output like this:

      NAME CPU(cores)  CPU% MEMORY(bytes)  MEMORY%
      minikube  189m 2% 1165Mi 8%

      If you see the output, start the Kubernetes dashboard by running minikube dashboard.