Deploying to your own Kubernetes Service

Note: The commands referenced in this document will be kubernetes cli specific but the same can be used by changing the kubectl command to oc using the openshift cli

This document is split into 2 sections:

New deployment will take you through the steps to deploy K for the first time.
Upgrades will take you through the steps to update your K installation.

Before you start

You should have

Received a configuration package from KADA.
Be familiar or be knowledgable about the network and load balancer settings for exposing services on your Kubernetes instance.
Request from your network team a DNS alias and certificate for the KADA Platform.
Access to an environment a Kubernetes cluster
In your local environment
1. Install kubectl
2. Install your cloud provider cli: eg azure cli, aws cli
3. For windows environments install gitbash.

1. New Deployments

A new deployment will take approximately 1 hour in duration to complete.

The commands in the steps below assume you are running in a unix bash env.

We strongly recommend using a Linux based environment over windows for compatibility of the deployment scripts. However windows use may run gitbash if you are deploying from a windows environment.

Step 1) Create a new Kubernetes cluster.

Kubernetes Service Providers supported: Amazon's Elastic Kubernetes Service (EKS) & Microsoft Azure's Kubernetes Service (AKS). Our customers have deployed onto Openshift Kubernetes Service. Reach out for assistance with other Kubernetes options that are not listed.

For cluster requirements see the How to deploy on your cloud page.

Step 2) Setting up access to KADA Image repository

KADA will provide a KADA_CLIENT_ID and KADA_CLIENT_SECRET to access the KADA Image repository. The following setups your Kubernetes service to access the repository

Create a secret

kubectl create secret docker-registry kada-image-credentials \
    --docker-server=kadaexternal.azurecr.io \
    --docker-username=$KADA_CLIENT_ID \
    --docker-password=$KADA_CLIENT_SECRET

Patch the service account with the above secret

kubectl patch serviceaccount <the service_account or "default"> \
  -p "{\"imagePullSecrets\": [{\"name\": \"kada-image-credentials\"}]}"

If your Kubernetes cluster does not have internet access to pull images then contact KADA Support for assistance to download images into your internal image repository.

Step 3) Creating a certificate

Create a certificate and key

Raise a certificate request for the domain hosting the K Platform.

Generate a full chain certificate. The cert file should contain the root CA and all intermediary certificates.

The certificate should be in the format of a *.crt and *.key file.

The cert should be signed via a trust authority that is trusted by your organisations browser. This is so there are no cert issues when user accesses K from a browser.

Load the cert / key into Kubernetes

kubectl create secret tls kada-ssl-cert --cert /path/to/fullchain.cer --key /path/to/certificate.key

Step 4) Kubernetes ingress

Your organisation will most likely have a standard pattern for routing network traffic to a Kubernetes cluster via a Load Balancer / HA Proxy / Ingress routes.

Using your organisations Load Balancer and ingress service

KADA Deployment can make use of your organisations pattern with a few additional configuration steps.

Note the domain of the Load Balancer URL. We will refer to this as DOMAIN_URL from here on.

Add the following mappings to the config of your organisation's ingress

List on *:8080

/keycloak -> keycloak-cluster-ip-service.<REPLACE WITH PROJECT NAMESPACE>.svc.cluster.local:8080 
/api -> cerebrum-cluster-ip-service.<REPLACE WITH PROJECT NAMESPACE>.svc.cluster.local:5002
/solr -> solr-gatekeeper-cluster-ip-service.<REPLACE WITH PROJECT NAMESPACE>.svc.cluster.local:8888
/ -> cortex-cluster-ip-service.<REPLACE WITH PROJECT NAMESPACE>.svc.cluster.local:9002

Deploy KADA's generic Load Balancer and ingress service

If you are not using your own load balancer / ingress service you can use the one packaged with the K Platform.

KADA provided a nginx-ingress controller but you may choose to deploy your own.

kubectl apply -f ingress/mandatory.yaml
kubectl apply -f ingress/cloud-generic.yaml

Deploy ingress. Depending on your setup you may need to modify the ingress definition. Out of the box KADA provide examples for:
1. TLS ingress: kubectl apply -f ingress/tls-ingress-service.yaml
2. non-TLS ingress: kubectl apply -f ingress/ingress-service.yaml
3. azure-private link service: kubectl apply -f ingress/azure-private.yaml

Step 5) Deploying KADA Services into Kubernetes

Download the distribution package and unzip it: unzip kada_x.x.x.zip
Navigate to the kube_setup directory: cd d_pkg/kube_setup
Populate the k8s_env.sh with the correct values:
```
export HOST=
export KADA_ADMIN_PASSWORD=
export POSTGRES_PASSWORD=
export KEYCLOAK_PASSWORD=
export KEYCLOAK_POSTGRES_PASSWORD=
export CEREBRUM_SECRET=
export SOLR_SECRET=
export FERNET_KEYS=
```
NOTES
1. HOST is in the format of the alias name or canonical host name. It must be lowercase e.g. if I intend to access K via https://prod.kada.ai, then the host value is prod.kada.ai
2. FERNET_KEYS should be generated using one of these methods:
  - Python: from cryptography.fernet import Fernet; Fernet.generate_key()
  - Unix shell: echo $(dd if=/dev/urandom bs=32 count=1 2>/dev/null | openssl base64)
3. SSL_SECRET_NAME is the Kubernetes secret name you installed the SSL Certificate as
4. Avoid special characters in the values above if possible.
5. Save k8s_env.sh in a secure location so that it can be used when upgrading to the K Platform.
Run to create a generated-k8s-common folder: ./kada_gen.sh
Make sure kubectl is configured and pointing to a Kubernetes cluster.
Deploy the generated config: kubectl apply -f generated-k8s-common
Deploy the K platform: kubectl apply -f master.yaml
Modify PV Policy - Modify all Persistent Volumes to ensure that the Reclaim Policy is set to Retain.

kubectl get pv
kubectl patch pv <REPLACE WITH pv name eg pvc-xxxxxxxxxxxx> -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'
kubectl get pv

Step 6) Post deployment verification

Check all Kubernetes services are running and not in error

kubectl get pods

Check the status API. It should return 200 if successful

https://<YOUR DOMAIN>/api/status

Step 7) Setup Users

KADA uses Keycloak to manage users in platform.

The Keycloak portal is accessible at:

http://<YOUR DOMAIN>/keycloak/auth/admin/master/console/#/realms/kada

Users can be setup locally or configured for SSO.

Step 8) Setup Landing Storage

KADA uses object store as a landing zone to process metadata and log files.

We currently support AWS s3, Azure Blob or local attached Kubernetes PVs.

AWS s3 setup

storage_type = s3
storage_root_folder = <s3 bucket name>
storage_aws_region = <Your AWS region>
storage_aws_access_key_id = <Your AWS IAM user access key>
storage_aws_secret_access_key = <Your AWS IAM user secret>

Azure Blob setup

storage_type = azure
storage_root_folder = <Azure container name>
storage_azure_storage_account = <Your azure storage account>
storage_azure_access_key = <Your azure storage account access key>

Performing an upgrade to your K installation

Step 1) Pre checks

Check that no jobs are currently running. Admin > Monitor.

Step 2) Deploying KADA updates

Download the distribution package and unzip it: unzip kada_x.x.x.zip
Navigate to the kube_setup directory: cd d_pkg/kube_setup
Populate the k8s_env.sh or overwrite with the k8s_env.sh from a prior deployment
Deploy the K platform: kubectl apply -f master.yaml

Step 3) Post deployment verification

Follow the same verification as per New Deployments (Step 6 in New Deployments)