Deploying OpenIAM on Kubernetes using Helm

This guide describes how to deploy OpenIAM to a private (not AWS, GKE) Kubernetes cluster via Helm, but without Terraform. This type of deployment is not recommended due to the number of Helm variables.

Prerequisites

Before starting the installation process, please make sure that the following prerequisites are in place.

• Access to Kubernetes cluster (kubectl configured on installer VM) is active.
• Helm 3 is installed and configured.
• Docker (if building/pulling images locally) is installed or the access to container registry is live.
• Network connectivity to remote DB (if using remote database) is active.
• Appropriate credentials for Harbor/container registry and DB users are in place.
• There is an admin (root) access to the private Kubernetes cluster with the required permissions to create cluster-level resources.

Installer VM preparation

Recommended OS: Ubuntu 20.04/22.04 (commands below follow Ubuntu syntax). Ensure that SSH key access and root privileges are available.

Installing required utilities

Before installing OpenIAM there are several utilities that must be installed, such as Docker, Helm, and kubectl. Use the exact commands below or adapt them to your environment.

Installing Docker

Use the commands below to install Docker.

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update -y
sudo chmod a+r /etc/apt/keyrings/docker.gpg
sudo apt-get install docker-ce docker-ce-cli -y

Installing Helm

Use the following commands to install Docker.

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh

Installing kubectl

Use the following commands to install kubectl.

curl -LO https://dl.k8s.io/release/v1.25.6/bin/linux/amd64/kubectl
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
kubectl --version

Preparing OpenIAM deployment directory

Star with creating a base directory, then log in to registry, clone repo and check out required release tag.

sudo mkdir -p /usr/local/openiam
cd /usr/local/openiam
git clone https://bitbucket.org/openiam/kubernetes-docker-configuration.git
cd kubernetes-docker-configuration/
git checkout RELEASE-4.2.1.15
./setup.sh
docker login confidant-bhaskara.container-registry.com

Deployment options

OpenIAM can be installed using local MariaDB (Helm chart packaged) or using remote MySQL/PostgreSQL. Use the appropriate configuration in setup-no-tf.sh. Key variables to set in setup-no-tf.sh are given in the table below.

Pre-deployment checklist

✅ kubectl configured on installer VM.
✅ Helm installed and repository updated.
✅ Registry credentials are available.
✅ Database reachable and user created.
✅ Required database ports open between cluster and DB.
✅ Values.yaml reviewed and customized if needed.
✅ Existing DB (if migrating) is backed up.

Installing OpenIAM using local MariaDB

Edit setup-no-tf.sh and set the variables described above. For local DB, ensure MariaDB chart version is set and not commented. Use the commands below to edit the file:

vi setup-no-tf.sh

... to set the variables:

BUILD_ENVIRONMENT="dev"
OPENIAM_VERSION_NUMBER="4.2.1.13"
APP_NAME="test2021"

... to run Installation setup, it will prompt for registry credentials:

./setup-no-tf.sh

... to monitor.

kubectl get pods -n <namespace>

Installing OpenIAM using remote MySQL database

To install OpenIAM using remote MySQL database, you will need to update DB host, port, database type and Hibernate dialect. Comment out local MariaDB Helm install block to avoid deploying local DB as follows.

openiam.database.jdbc.openiam.host=<DB_HOST>
openiam.database.jdbc.openiam.port=3306
openiam.database.jdbc.activiti.host=<DB_HOST>
openiam.database.jdbc.activiti.port=3306
openiam.database.type=MariaDB
openiam.database.jdbc.hibernate.dialect="org.hibernate.dialect.MySQLDialect"

Next, comment local MariaDB block in setup-no-tf.sh with the following commands.

#MARIADB_CHART_VERSION=
#helm upgrade --install "${APP_NAME}-database" openiam/mariadb  -f .deploy/mariadb.values.yaml --version "${MARIADB_CHART_VERSION}" --set auth.rootPassword="${ROOT_PASSWORD}" --set initdbScriptsConfigMap="mariadb-initdbscripts" --set openiam.bash.log.level="warn"

Afterwards, run installation setup, it will prompt for registry credentials.

./setup-no-tf.sh

Installing OpenIAM using remote PostgreSQL

To install OpenIAM using remote PostgreSQL database, set database type to Postgres and use PostgreSQL dialect with the following command. Ensure network access and DB user with required privileges.

openiam.database.jdbc.openiam.host=<DB_HOST>
openiam.database.jdbc.openiam.port=5432
openiam.database.jdbc.activiti.host=<DB_HOST>
openiam.database.jdbc.activiti.port=5432
openiam.database.type=Postgres
openiam.database.jdbc.hibernate.dialect="org.hibernate.dialect.PostgreSQLDialect"

Then comment local MariaDB block in setup-no-tf.sh as follows.

#MARIADB_CHART_VERSION=
#helm upgrade --install "${APP_NAME}-database" openiam/mariadb  -f .deploy/mariadb.values.yaml --version "${MARIADB_CHART_VERSION}" --set auth.rootPassword="${ROOT_PASSWORD}" --set initdbScriptsConfigMap="mariadb-initdbscripts" --set openiam.bash.log.level="warn"

Finally, run Installation setup, it will prompt for registry credentials

./setup-no-tf.sh

Post-install verification

After a successful deployment, make sure to verify pods, services, ingress/rProxy and logs. with the following useful commands.

kubectl get pods -A
kubectl get svc -A
kubectl logs <pod> -n <namespace>
kubectl describe pod <pod> -n <namespace>
To find rproxy service and expose to external network:
kubectl get svc | grep prox

Troubleshooting

If ElasticSearch-curator or bootstrap jobs fail, use the following commands to cleanup and retry.

kubectl delete jobs --all
helm ls | grep rabbit
helm delete <app>-rabbitmq
kubectl get pvc | grep rabbit
kubectl delete pvc data-<app>-rabbitmq-0
helm delete <app>-configmap
kubectl delete job <app>-vault-bootstrap-job

After, re-run the setup.

./setup-no-tf.sh