Automate Guide
AppService status

Installation

Suggest Edits

Document version: 245. Automatically generated.

Below you'll find steps that needs to be done to set up SentiOne Automate and SentiOne React in Kubernetes cluster.

Prerequisites

Conventions

  • CAPITAL_LETTERS_VARIABLE_NAME - fragment which should be replaced with actual values matching particular environment
  • AUTOMATE_CONFIG_REPO_PATH - Path to automate configuration repository (eg. /home/user/automate-config)
  • ENVIRONMENT_NAME - Environment name (eg. production)

Example

$ cd AUTOMATE_CONFIG_REPO_PATH/ENVIRONMENT_NAME/external-services

Should be substituted with:

$ cd /home/user/automate-config/production/external-services

Steps

1. Check if you have access to the Kubernetes cluster

The Administrator need to prepare access to the operational Kubernetes cluster with use of kubectl tool.
We shall receive similar information as below when invoking kubectl cluster-info.

$ kubectl cluster-info
Kubernetes control plane is running at https://1.2.3.4:6443
KubeDNS is running at https://1.2.3.4:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
Metrics-server is running at https://1.2.3.4:6443/api/v1/namespaces/kube-system/services/https:metrics-server:/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

$ kubectl get nodes   
NAME            STATUS   ROLES                AGE    VERSION
master          Ready    master               1d     v1.21.1
worker          Ready                         1d     v1.21.1

2. Kubernetes cluster preparation

2.1 Create a dedicated namespace

It is recommended to run SentiOne Automate platform in it's dedicated logical Kubernetes space called namespace. To create namespace please use kubectl command, ie:

# creating namespace named 'sentione'
$ kubectl create namespace sentione

# verifying if namespace has been created
$ kubectl get namespaces

2.2 Add docker container registry credentials

Kubernetes cluster pulls docker images from harbor-vm-proxy.sentione.com repository. By default, the registry is locked and needs authentication. The object type secret docker-registry is created to previously created Kubernetes namespace to authenticate.

# creating secret type object named 'sec-harbor-vm-proxy.sentione.com' - enabling access to SentiOne docker registry
$ kubectl create secret \
docker-registry sec-harbor-vm-proxy.sentione.com \
--docker-server=harbor-vm-proxy.sentione.com \
--docker-username=USERNAME \
--docker-password=PASSWORD \
[email protected] \
--namespace sentione

# veryfying if secret type object has been created in sentione namespace
$ kubectl get secrets -n sentione sec-harbor-vm-proxy.sentione.com

NAME                               TYPE                             DATA   AGE
sec-harbor-vm-proxy.sentione.com   kubernetes.io/dockerconfigjson   1      2d17h

3. Create persistent volumes

NLU applications store their training data on the filesystem.
Our system requires these data to be persistent and shared with all instances.

For that purpose, you have to create so-called persistent volume in Kubernetes cluster that will be backed by NFS share configured in NFS Installation.

3.1 Navigate to Automate configuration repository

$ cd AUTOMATE_CONFIG_REPO_PATH/ENVIRONMENT_NAME/kubernetes/nfs

3.2 Configure NFS details

Modify pv.yaml file accordingly by providing NFS server IP address and correct share path.

3.3 Create persistent volume

Apply modified manifest using kubectl command

$ kubectl apply -f ./pv.yaml

3.4 Create persistent volume claim

Apply persistent volume claim manifest using kubectl command

$ kubectl apply -f ./pvc.yaml

3.5 Commit changes to config repository

$ git add pv.yaml pvc.yaml
$ git commit -m 'updates persistent volume configuration'
$ git push

4. Install Helm

To ease the installation process the tool named helm will be used. At Administrator's / Operator's computer please install tool in version 3.5.4 by following the instructions from:

Installation instructions

Version 3.5.4: https://github.com/helm/helm/releases/tag/v3.5.4

4.1 Verify installation

Properly installed tool can be verified with command helm version

$ helm version
version.BuildInfo{Version:"v3.5.4", GitCommit:"1b5edb69df3d3a08df77c9902dc17af864ff05d1", GitTreeState:"dirty", GoVersion:"go1.16.3"}

4.2 Add SentiOne's chart repository

📘

HELM charts repository is used to store deployment manifests that can be easily installed in Kubernetes cluster.

SentiOne hosts private chart repository which holds recipies for deployment of entire Automate platform.

In configuration that is below there has been used variables named USERNAME and PASSWORD - the actual values shall be delivered by SentiOne through safe communication channel that shall be agreed upfront with customer and accepted with SentiOne (ie SMS). If those values are missing then please contact SentiOne Administrator (please check chapter Contact at the end of this document).
Access to the repository is limited to whitelisted IP addresses that's why it's mandatory to send list of public source IP(s) which will be in use for setup or update process

4.2.1 Add SentiOne's chart repo to HELM

SentiOne shares with the customers helm charts repository which can be added with command: 

$ helm repo add sentione-hub https://charts.sentione.com/repository/helm --username USERNAME --password PASSWORD

4.2.2 Fetch repository data

Next data from repository is downloaded/updated:

$ helm repo update

5. Applications configuration

5.1 Navigate to automate config folder

$ cd AUTOMATE_CONFIG_REPO_PATH/ENVIRONMENT_NAME/kubernetes/helm/automate

5.2 Chatbots configuration

5.2.1 Replace placeholders in values.yaml

Please substitute following placeholders with actual values in file named values.yaml inside chatbots section

DB_USERNAME
DB_PASSWORD
DB_HOST
DB_PORT
RABBITMQ_HOST1
RABBITMQ_HOST2
RABBITMQ_HOST3
RABBITMQ_USERNAME
RABBITMQ_PASSWORD

Where placeholder prefixed with

5.2.3 Commit changes

$ git add values.yaml
$ git commit -m 'updates configuration of chatbots for environment ENVIRONMENT_NAME'
$ git push

5.3 NLU configuration

5.3.1 Replace placeholders in values.yaml

Please substitute following placeholders with actual values in file named values.yaml inside nlu section

REDIS_AI_NAMESPACE
CLUSTER_DOMAIN

Where placeholder prefixed with

5.3.2 Commit changes

$ git add values.yaml
$ git commit -m 'updates configuration of chatbots for environment ENVIRONMENT_NAME'
$ git push

5.4 SentiOne React configuration

5.4.1 Replace placeholders in values.yaml

Please substitute following placeholders with actual values in file named values.yaml inside sentione section

DB_HOST
DB_PORT
DB_USERNAME
DB_PASSWORD
ES_HOST1
ES_HOST2
ES_CLUSTERNAME
ES_USERNAME
ES_PASSWORD
ES_HTTPPORT
ES_TRANSPORTPORT
RABBITMQ_HOST1
RABBITMQ_HOST2
RABBITMQ_HOST3
RABBITMQ_PORT
RABBITMQ_USERNAME
RABBITMQ_PASSWORD

Where placeholders prefixed with

5.4.2 Commit changes

$ git add values.yaml
$ git commit -m 'updates configuration of sentione react for environment ENVIRONMENT_NAME'
$ git push

5.5 Elasticsearch certificate installation

Due to security reasons communication between SentiOne React components and Elasticsearch cluster is encrypted and secured with username/password (needed data shall be created within configuration of Elasticsearchj service).

Therefore the CA certificate of Elasticsearch needs to be securely attached to the SentiOne React applications with help of Kubernetes secret object.

🚧

Certificate file should be generated during installation of master ES node

5.5.1 Navigate to elasticsearch config folder

$ cd AUTOMATE_CONFIG_REPO_PATH/ENVIRONMENT_NAME/external-services/elasticsearch

5.5.2 Create kubernetes secret inside cluster

# creating secret type object containing Elasticsearch CA certificate
$ kubectl create secret generic elastic-stack-ca -n sentione  --from-file=elastic-stack-ca.pem=./elastic-stack-ca.pem

5.5.3 Verify secret was installed successfully

# veryfying if secret type object has been created in sentione namespace
$ kubectl get secrets -n sentione elastic-stack-ca

NAME               TYPE     DATA   AGE
elastic-stack-ca   Opaque   1      5s

6. Automate Installation

SentiOne Automate and React installation is run automatically with help of helm tool and use of SentiOne charts repository sentione-hub:

🚧

Installation process with helm tool can take quite long time (even up to 30 minutes).

This is related to download of docker images to Kubernetes cluster from SentiOne repository harbor-vm-proxy.sentione.com and depends on internet connection (speed) available to Kubernetes cluster.

6.1 Issue helm upgrade command

To install automate in Kubernetes cluster please issue following command:

Command template

$ helm upgrade --install --wait --debug '--timeout=300m' \
--namespace sentione \
-f AUTOMATE_CONFIG_REPO_PATH/ENVIRONMENT_NAME/kubernetes/helm/automate/values.yaml \
--version PUT_AUTOMATE_VERSION_HERE \
automate \
sentione-hub/automate

Example (Installation of Automate 208.0.10 on production environment)

$ helm upgrade --install --wait --debug '--timeout=300m' \
--namespace sentione \
-f /home/automate-config/production/kubernetes/helm/automate/values.yaml \
--version 208.0.10 \
automate \
sentione-hub/automate

7. Expose Automate apps on public URLs

With help of an Kubernetes Ingress Controller we can configure domains for exposed Kubernetes services so that they can be accessed by end-users. In our case there are three services that need to be exposed outside the cluster: admin, gateway, web-chat. See Architecture – Components to learn more about these apps.

📘

Configuring TLS (HTTPS)

TLS is required to enable features such as clipboard in Chatbots. Refer to Security - TLS certificates to learn about configuring the ingresses above with a TLS certificate. If you're setting up a testing environment, follow the instructions below instead.

7.1 Install the Ingress Controller

$ helm upgrade --install ingress-nginx ingress-nginx \
  --repo https://kubernetes.github.io/ingress-nginx \
  --namespace sentione

7.2 Add DNS records that point to the IP address of the LoadBalancer resource

$ kubectl -n sentione get svc
NAME                                 TYPE           CLUSTER-IP      EXTERNAL-IP      PORT(S)                      AGE
ingress-nginx                        LoadBalancer   X.X.X.X         Y.Y.Y.Y          80:31841/TCP,443:32712/TCP   1m

The Y.Y.Y.Y is the External IP address that's exposed outside the cluster. Point your DNS records (e.g. admin-envname.automate.example.com) to this address.

7.3 Configure automate ingress object

7.3.1 Navigate to ingress folder in configuration repository

$ cd AUTOMATE_CONFIG_REPO_PATH/ENVIRONMENT_NAME/kubernetes/ingress/

7.3.2 Update automate_ingress.yaml file

Change the host values to target domains where these applications will be reachable in the following files:

$ grep host automate_ingress.yaml
  - host: admin-envname.automate.example.com
  - host: web-chat-envname.automate.example.com
  - host: gateway-envname.automate.example.com
  - host: channels-connector-envname.automate.example.com

7.3.3 Apply ingress manifests on Kubernetes

$ kubectl -n sentione apply -f ./automate_ingress.yaml

The nginx Ingress Controller will automatically reload the configuration once the Ingresses are applied to the cluster. You can verify it's correctly attached as below:

$ kubectl -n sentione get ingress
NAME                       CLASS   HOSTS                                                                      ADDRESS          PORTS     AGE
automate-ingress   nginx   admin-envname.automate.example.com,web-chat-envname.automate.example.com,...   X.X.X.X          80, 443   1m
gateway-ingress    nginx   gateway-envname.example.com                                                    X.X.X.X          80, 443   1m
7.3.4 Commit changes to automate_ingress.yaml
$ git add automate_ingress.yaml
$ git commit -m 'updates ingress domains for environment ENVIRONMENT'

Contact

In case of questions please send mesasge with related details to the email:
admin (at) senti1.com.

Updated 22 days ago