Deploy with Kubernetes

The following documentation is a guide for installing OmniSpatial in a general Kubernetes environment. The guide will walk you through each step of deploying the OmniSpatial dependency components and then the OmniSpatial containers themselves.

note

Configuration may vary depending on your specific Kubernetes platform and environment.

Deployment Prerequisites

Platform Requirements

The following platform/components must be available and accessible.

• A basic understanding of Kubernetes
• A Kubernetes cluster exists and you have access to it
• An Ingress Class is configured and available in your cluster
• A domain name is available and pointed to your cluster (via Ingress Load Balancer)
  • ex: your cluster can be reached via a domain (ex: https://my-domain.com → your cluster)
• Your Kubernetes CLI (kubectl) context is set as your active Kubernetes cluster

Local Environment Tools

The following tools are required to be installed and available to the person performing the deployment steps.

• Kubernetes CLI (kubectl)
  • Used to interact with the Kubernetes API.
• Kubernetes Package Manager CLI (HELM)
  • Used to deploy the OmniSpatial HELM charts.
• A registry YAML file provided by Rizing
  • This file will provide access to Rizing's container registry (will be used later in the deployment steps).

Deployment Overview

Following this guide will produce a complete OmniSpatial technology stack deployed within Kubernetes. The deployment will result in the following general High-Availability (HA) components:

• keycloak namespace
  • Keycloak Cluster - used as an identity broker to provide Single-Sign on (SSO)
  • Postgres Database Cluster - used to store Keycloak application data
• omni namespace
  • Postgres Database Cluster - used to store OmniSpatial application data
  • OmniSpatial frontend (application) deployment
  • OmniSpatial backend (REST API services) deployment
  • OmniSpatial documentation (User Guide) deployment

Install Postgres Database Operator

Install the CloudNative PG Operator.

1. Add the HELM repository

helm repo add cnpg https://cloudnative-pg.github.io/charts

2. Install the operator

helm upgrade --install cnpg --namespace cnpg-system --create-namespace cnpg/cloudnative-pg --wait

Install Keycloak

Keycloak is an open source identity and access management solution which is used in Omni to provide Single-Sign on capabilities. Reference docs can be found here.

Install Keycloak Operator

1. Create keycloak namespace

kubectl create namespace keycloak

2. Deploy the Keycloak Custom Resource Definitions (CRDs):

kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/22.0.1/kubernetes/keycloaks.k8s.keycloak.org-v1.yml
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/22.0.1/kubernetes/keycloakrealmimports.k8s.keycloak.org-v1.yml

3. Deploy the Keycloak Operator deployment:

kubectl apply -n keycloak -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/22.0.1/kubernetes/kubernetes.yml

Deploy Postgres Database for Keycloak

Keycloak requires a database to store its information. The following steps will guide you through installing a Postgres Cluster for Keycloak.

1. Create keycloak-postgres-cluster.yaml file

Update the YOUR_INGRESS value with the name of the ignress class for your cluster (ex: nginx).

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: postgres
  namespace: keycloak
spec:
  instances: 3
  storage:
    size: 25Gi
  bootstrap:
    initdb:
      database: keycloak
      owner: keycloak
  monitoring:
    enablePodMonitor: true

2. Apply file

kubectl apply -f ./keycloak-postgres-cluster.yaml

3. Wait for cluster to finish creating.

There should be "n" number of Postgres pods that get created, where "n" is the number of instances defined in the YAML file. For Example, if 3 instances were specified, you will need to wait for 3 postgres-n pods to have a "Running" status:

Create Keycloak Cluster

1. Create keycloak-cluster.yaml file

Update the YOUR_DOMAIN.com with the domain of your cluster (ex: identity.my-org.com).

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: keycloak
  namespace: keycloak
spec:
  instances: 3
  ingress:
    enabled: true
    className: YOUR_INGRESS # <--- UPDATE
  db:
    vendor: postgres
    usernameSecret:
      name: postgres-app
      key: username
    passwordSecret:
      name: postgres-app
      key: password
    host: postgres-rw.keycloak.svc
    database: keycloak
  hostname:
    hostname: identity.YOUR_DOMAIN.com # <--- UPDATE
  additionalOptions:
    - name: proxy
      value: edge

2. Apply file

kubectl apply -f ./keycloak-cluster.yaml

3. Wait for each pod for every instance of the cluster to become available:

There should be "n" number of Keycloak pods that get created, where "n" is the number of instances defined in the YAML file. For Example, if 3 instances were specified, you will need to wait for 3 keycloak-n pods to have a "Running" status:

Install Omni

The OmniSpatial application is made up of 3 containerized apps.

• omni - the frontend application
• omni-api - the backend REST services
• omni-docs - the User Guide and documentation for the application

1. Create omni namespace

kubectl create namespace omni

Deploy Postgres Database for Omni

Omni requires a database to store application data. The following steps will guide you through installing a Postgres Cluster for Omni.

1. Create omni-postgres-cluster.yaml file

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: postgres
  namespace: omni
spec:
  instances: 3
  storage:
    size: 25Gi
  bootstrap:
    initdb:
      database: omni
      owner: omni
  monitoring:
    enablePodMonitor: true

2. Apply file

kubectl apply -f ./omni-postgres-cluster.yaml

3. Wait for cluster to finish creating.

There should be "n" number of Postgres pods that get created, where "n" is the number of instances defined in the YAML file. For Example, if 3 instances were specified, you will need to wait for 3 postgres-n pods to have a "Running" status:

Deploy Omni Workloads

1. Add Rizing container registry secret

NOTE: You should receive this file from Rizing.

kubectl apply -f rizing-registry.yaml -n omni

2. Get keycloak admin password

Retrieve and copy the decoded password value from the the keycloak-initial-admin secret.

Optionally, you could retrieve it with the following command:

kubectl get secrets/keycloak-initial-admin -n keycloak --template='{{.data.password | base64decode}}'

note

The terminal may display a trailing % symbol. When you copy the result make sure you don't include the erroneous % symbol. (omit the % symbol at the end, if your terminal includes it)

3. Create omni-helm-values.yaml file and update desired configuration

NOTE: Paste the Keycloak Password into the api > keycloak > password section in the YAML file.

timezone: UTC
image:
  tag: 'release' # <--- RECOMMENDED: UPDATE TO SPECIFIC TAG
host: YOUR_ROOT_DOMAIN.com # <--- UPDATE (ex: my-domain.com)
app:
  replicaCount: 3
api:
  replicaCount: 3
  db:
    type: postgres
    host: postgres-rw.omni.svc
    database: omni
    username: omni
    usernameSecretName: postgres-app
    passwordSecretName: postgres-app
  keycloak:
    username: admin
    password: KEYCLOAK_PASSWORD # <--- REPLACE WITH COPIED KEYCLOAK PASSWORD
docs:
  replicaCount: 2

4. Deploy via HELM install command

helm install omni oci://registry.rizing.cloud/library/omni -n omni --version 1.0.0 -f omni-helm-values.yaml

Congratulations! Omni is now deployed to Kubernetes. You can now run the application from the omni subdomain of your cluster's domain (as set in the omni-helm-values.yaml file).

Example: https://omni.your-org.com

Upgrades

1. Use the same omni-helm-values.yaml used for the initial deployment
2. Upgrade the omni-helm-values.yaml file with any desired additional configuration changes
3. Perform a HELM upgrade

helm upgrade --install omni oci://registry.rizing.cloud/library/omni -n omni --version 1.0.0 -f omni-helm-values.yaml

Uninstall

To uninstall all Omni workloads (including dependencies), delete the keycloak and omni namespaces.

NOTE: This will permanently delete all application data. Make sure you know what you are doing.

kubectl delete namespace keycloak
kubectl delete namespace omni

Troubleshooting

Symptom

omni-api-* pods have a "FAILED" status or restart count is greater than 0.

Diagnostics

This is typically caused by a misconfiguration of the Keycloak admin account details within omni-helm-values.yaml. The Omni API pods need to have the proper Keycloak admin account configured because these pods will communicate with the Keycloak API on startup in order to setup the necessary artifacts within Keycloak to support Omni.

The omni-api logs can be viewed to confirm that the Keycloak communication is broken with the following command:

kubectl logs -f deployment/omni-api -n omni

note

Adding a -f argument will follow the logs (docs).

Resolution

1. Delete the omni namespace (kubectl delete namespace omni)
2. Ensure the Keycloak admin account (username & password) are correct and properly added to omni-helm-values.yaml
   • Try logging into the Keycloak admin dashboard with the configured admin account credentials to verify them
   • Example: https://identity.your-org.com
3. Recreate the Omni namespace and artifacts by following the Install Omni steps again

---

Resources

• https://kubernetes.io/docs/tutorials/kubernetes-basics/