The steps below will guide you when deploying OpenIAM to the manually preinstalled AKS. Here, all infrastructure services are internal.

Setting up Docker environment variables

1. Create an account on Dockerhub.

2. Export the following environment variables.

export DOCKER_REGISTRY=registry.openiam.com
export DOCKERHUB_USERNAME=******
export DOCKERHUB_PASSWORD=******

Replacing the ***** with corresponding values.

Installing Helm

1. Helm version to be installed is v3.3.4

https://github.com/helm/helm/releases/tag/v3.3.4

2. For Linux systems, follow the instructions below.

3. Download Helm with the following command.

https://get.helm.sh/helm-v3.3.4-linux-amd64.tar.gz

2. Unpack the file downloaded as follows.

tar -zxvf helm-v3.3.4-linux-amd64.tar.gz

3. Find the Helm binary in the unpacked directory and move it to its desired destination by running the following command.

mv linux-amd64/helm /usr/local/bin/helm

Installing Terraform

The version of Terraform should be 1.13.4. There are various ways to do this, we recommend using tfenv.

System requirements

The table below specifies the minimum system requirements for deploying a non-production OpenIAM v4.2.x instance using Kubernetes.

MINIMUM Hardware requirements

Kubernetes Version

We have tested our terraform and helm scripts with Kubernetes 1.32. Please use this version. No other versions are supported currently.

Prerequisites

Vault

We use Vault in order to securely store secrets. Our applications use certificate based authentication in order to securely talk to Vault. Our images will generate a self-signed certificate to be used for vault. However, if you would like to use your own certificate, you can do the following:

1) Get a public/private keypair from a valid CA Authority, and put the files in:

• * .vault/vault.key for the private key.
• * .vault/vault.crt for the public key.

2) Run the following command:

. env.sh
openssl pkcs12 -export -in .vault/vault.crt -inkey .vault/vault.key -out .vault/vault.jks -password pass:${VAULT_KEYPASS}

If you are using Terraform, make sure that ${VAULT_KEYPASS} above matches vault.vaultKeyPassword in terraform.tfvars. Also, put all of the resulting files in openiam-configmap/.vault/, i.e.:

cp .vault/vault.key openiam-configmap/.vault/
cp .vault/vault.crt openiam-configmap/.vault/
cp .vault/vault.jks openiam-configmap/.vault/

SMTP Server

You will need to setup an SMTP server. If running in AWS, you use SES, which is very simple to setup. If you do not have a corporate SMTP server, there are numerous SMTP Cloud Servers which you can use. Setting up SMTP is outside the scope of this document.

RabbitMQ TLS

You can optionally run RabbitMQ with TLS enabled.

Adding your own TLS Certificates to RabbitMQ

If you would like to use your own Certificates with RabbitMQ, you will need to get a public/private keypair from a valid CA authority, and generate a JKS file. Please follow the instructions in the RabbitMQ TLS document.

Generating a self-signed certificate

You can also generate a self-signed certificate by running

./generate.rabbitmq.certs.sh

HTTPS certificates

When running in Kubernetes, we expose port 80, and 443 if https is enabled. Our Apache httpd server listens to these ports. To setup https, see our SSL document for a list of required files.

Set required values in env.sh

1. Set the APP_NAME variable in env.sh to a unique string. This is a unique identifier, and will not be seen by end users.
2. If you're running in AWS, set the OSS variable in env.sh to -oss.
3. Configure Extra VHost and Apache Configs.

You can optionally add 'extra' VHost and Apache configs. To do that, simply modify the following files as needed

• .apache/extraVHost.conf
• .apache/extraApache.conf

These files will be put in /usr/local/apache2/conf/add, in the rProxy pod.

Device manager (optional)

1. Set the replica_count_map.devicemanager (not zero) in the terraform.tfvars.
2. Ask the OpenIAM team to provide you with firebase-admin.json file.
3. Copy the file to the openiam-configmap/.device/ folder.

vm.max_map_count

OpenSearch requires the vm.max_map_count=262144. Make sure the k8's worker nodes have this value. Read your cloud provider documentation how to set this value on the worker nodes.

Initialize and setup

Run the setup script

./setup.sh

RabbitMQ

Exposing externally. To expose the RabbitMQ Service externally, uncomment the following lines in rabbitmq.values.yaml:

# Uncomment to expose externally
# service:
#   type: LoadBalancer
#   clusterIP: None

Deploying with Terraform

The recommended approach is deploying to Kubernetes using Terraform. The detailed step-by-step guide to doing that can be found in this document.

Deploying without Terraform

You can also deploy without using Terraform, however this method is much more complex, requires much more configuration, and is generally not recommended. In the event this approach is still required, the step-by-step guide for it can be found here.

Confirming successful deployment

Confirm that all pods are up and running with the following command.

kubectl get pods

Ensure that the READY column does not have any failed pods.

The running pod looks as follows

test100-esb-0                         1/1     Running   0          2m3s

The failed pod looks as shown below.

test100-esb-0                         0/1     CrashLoopBackOff   4          2m3s

Debugging failed pods

If a certain pod fails, gather it's logs for analysis.

kubectl logs pods/<name_of_failed_pod>

Accessing your deployed instance

To access your deployed instance of OpenIAM, run the following command.

. env.sh
kubectl get "service/${APP_NAME}-rproxy"

The output of the above command will contain an EXTERNAL IP column, for example:

NAME                     TYPE           CLUSTER-IP     EXTERNAL-IP                                                              PORT(S)        AGE
test100-rproxy   LoadBalancer   172.20.27.78   a0375c89dd2ec11e98bca0648c64953f-439827441.us-west-2.elb.amazonaws.com   80:32468/TCP   3m57s

Curl the above URL.

curl -L "http://${EXTERNAL_IP_FROM_ABOVE}/webconsole"

You may want to add a CNAME alias for the above URL, to make it more human-readable.

Switching between environments/clients.

We provide a convenience shell script, which saves off Terraform files to a specific location, or copies Terraform files from that location to this project.

For example, the below will save the terraform files from this project into /tmp/client_name/prod.

./terraform.client.sh save /tmp client_name prod

In its turn this will use the terraform files from /tmp/client_name/prod.

./terraform.client.sh use /tmp client_name prod