Deploy in a Cluster Environment

This page contains detailed instructions for deploying Rasa X in a scalable cluster environment using OpenShift or Kubernetes (K8S).

If you get stuck, email support@rasa.com with subject “deployment help” and we’ll jump on a call with you! We’re working to make deployment easier and would love your feedback.

Rasa X is available as a Helm Chart for a quick and easy cluster setup. If you are not using Helm in your cluster, you can still use the following instructions to generate the Kubernetes/OpenShift object configurations via the Helm command-line interface, and deploy those configurations manually.

Requirements

  1. Check that Helm is installed on your machine. If this is not the case, see this guide for instructions on how to install Helm.

  2. Add the Rasa X Helm chart repository to Helm so you can get the chart from there.

    helm repo add rasa-x https://rasahq.github.io/rasa-x-helm
    
  3. Make sure kubectl or oc are connected with your cluster and are using the desired namespace.

Configuring the Helm Chart

The Rasa X Helm Chart comes with a default configuration. However, in order to choose safe credentials and to adapt the chart to your environment, you need to adapt some of these default settings. You can see which values are configurable in the Rasa X chart by running this on your command line:

$ helm inspect values rasa-x/rasa-x

There are different ways to change the default parameters:

  • --values (or -f): Specify a YAML file with overrides for the values.
  • --set (and its variants --set-string and --set-file): Specify overrides in the command line.

Our recommended option is to specify your configurations in a separate YAML file. Please see the following sections for examples.

OpenShift / Kubernetes Specific Configuration

The Helm chart is compatible with both Kubernetes and OpenShift. However, depending on your cluster configuration, it might be necessary to adjust the security permissions for the deployments:

securityContext:
  # fsGroup to use (e.g. when deploying on Kubernetes)
  fsGroup: 0

Configuring the Subcharts

Rasa X builds on existing charts for postgresql, rabbitmq, and redis. To see all configuration values please check the READMEs of the subcharts. The Rasa X chart contains a link to the used chart versions and their READMEs in its values.yml file.

If you don’t want to use the subcharts and decide to provide your own deployments, you can disable the subchart usage through the Rasa X values file. E.g. to skip installing the postgresql subchart specify this in your override file:

postgresql:
  install: false

Additionally you have to provide the connection details of your external instances and the required credentials. For postgresql this would e.g. be:

postgresql:
  install: false
  existingHost: "<host of your postgress instance>"
  existingSecretKey: "<key to get the password from the secret>"

global:
  postgresql:
    existingSecret: "<name of the secret which contains the database password>"
    servicePort: <port which should be used to connect>
    postgresqlDatabase: "<name of the database which should be used>"
    postgresqlUsername: "<username which should be used to connect>"

Using Rasa X EE

By default, the Helm chart is configured to use the Rasa X CE image. To use the Rasa X EE image add this to your override file:

rasax:
  name: "gcr.io/rasa-platform/rasa-x-ee"

The next step is to configure the pull secret, which Kubernetes / OpenShift will use to pull the image from the private registry:

  1. Copy everything between the outer " of the docker_registry_license key in your Rasa X EE license to a file gcr-auth.json. The contents of gcr-auth.json should look like this:

    {
      "type": "service_account",
      "project_id": "rasa-platform",
      "private_key_id": "sdferw234qadst423qafdgxhw",
      "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvfwrt423qwadsfghtzw0BAQEFAASCBKgwggSkAgEAAoIBAQCgt338FkWbW13dghtzew4easdf5wAi15jrA9t4uOk8dghrtze4weasfgdhtAFZNfrLgvr2\nPBTu1lAJDLo136ZGTdMKi+/TuRqrIMg/sr8q0Ungish8v6t5Jb4gsjBi9StytCT4\nhWXDL3qeadfsgeDOudl6c3iMzylBws+VffrFfaZWjDpGtxmlYwIUa2e\noNSe7BYLnY9tDrX3zrP/wu/6FPbbGkBjguDG1l3Kx7l1wmiPtK5lIhjt+k7Oyx/u\nd6+gvfs+7RX9wUxnZT/tLggybYdsr8BA1Pqr0hDmhdDl7tjXVTmGLG+1/+lXVGFc\nqKEg+uLXAgMBAAECggEAESzwRK0Cp62LgBjInk+jvTmMI4lYP/XTnfk0TNwyiLxd\nT7mkw/TzkSVRifZ37lBQ6BS6BiqBJherh1N4xI+DF9HUN/wHR93QTyu7p8umlcxC\nlPV0KE4b5ZMfWvRG4y236cRGly9urcBNGoFzFHl8pd2iS5DMqZOYpSXY+qvkXTKE\nUOm5mVSs4S4Qa9cHL+jWXCvY0789fG1GrT+L3Fn+StKacgQuBnN1krYFYBSjCAh8\nsnSdjkvGguw/6OApPHd8HqkHtjU0PD67uU5QIm5N1bmz9KT4s9Pm+WbCinEstIiN\nIfln5ikmHcMAiIS0gzSnZavsY21PsDHBkD8SUO7CTQKBgQDgMPhx0TsB/oVH/SnU\nt3oTME+tfAKI69tozX02jHj6DY/vDpI1hXNmb4oMOos5+3ulborHqnso9za1RgV7\nm2N04QQVfzYEuZzJzXL11SHvBYVjHkXYy6HR5GhnPmwA+CzrDNy2/oYxlaqH7TBA\nR+f7IHToIPKGCVrhCJztlAgzIwKBgQC3hQNclIQ5Iw0gm9Rr8zAP/YoRJdiUSYtv\nNBmav+dTTSkPh51Bomj/J4Rrg8OLvHG5U79pmzbQdIFGYGKlR0l4/QepKpbaGm7x\nM/gRp/GXu9sN8LgI+h+FskCYi4cuqDjQ9L2S0gwMre4witmeVSIiBxLWxS7mvkZX\nWRW58ml2vQKBgBozPuW2SQobn6HhIUFdy+NwMu+YXYd44ORnl2mHkx/N8/NBJa8h\nkHH5OQ3izaCSFkooGAnrj4cjFP6sVzmx2DaxkVOd0UdOFdezreqy5MtVPthtkkYa\nzieEZPsj3WVjm4RAtY6hQjeLQSmve4MXpDHCAkeaih1F/Jvt8MEHGso3AoGBAJez\nTioTYpFQliNkbN2nMw2kyaKPJE6/1JDiAmBXTcMgP1blBWsh86UnZ2DwlI5IAcHu\npoWHlnIOPGaOejyhhuyKTPDbkcNMonSkPuVpbF2/Hb6SQ664A6KizJ7Mh7xbtkuU\nY7igBPHePMzHmkg1m3eBXWNHsBNxKfg+XaVN6zwJAoGBAN6VhGMmyDcn0GqkkP6d\nrSsQ0Ig7L4PnU633oYWoGWa8q/XYiFbcACMFynMbrmHG+/0c3Iwt32bi3th60Cwb\nT66yqmv4MaT72+EfQHxiLxnUxhqSpBXM0eoXbyvDg97Zp/slsYvGGLjONmmretlE\nsjAsuAH4Iz1XdfdenzGnyBZH\n-----END PRIVATE KEY-----\n",
      "client_email": "company@rasa-platform.iam.gserviceaccount.com",
      "client_id": "114123456713428149",
      "auth_uri": "https://accounts.google.com/o/oauth2/auth",
      "token_uri": "https://accounts.google.com/o/oauth2/token",
      "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
      "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/company%40rasa-platform.iam.gserviceaccount.com"
    }
    
  2. Log in to the docker registry:

    $ sudo docker login  -u _json_key -p "$(cat gcr-auth.json)" https://gcr.io
    
  3. Create an image pull secret from the docker config.json following the Kubernetes guide or the OpenShift guide.

  4. Add the secret name in your override file:

    images:
      imagePullSecrets:
      - name: <name of the created secret>
    

Using Your Own Custom Action Server Image

To use your own custom action server image, put the following in the override file:

app:
  name: "name of your image"
  tag: "tag you want to use"

Specifying Volume Sizes

Rasa X requires two volume claims: one for Rasa X, and one for the database. You can define the claim sizes by setting the size of these services in your override file:

rasax:
  persistence:
    size: "10Gi"
postgresql:
  persistence:
    size: "100Gi"

Providing Access Credentials / Using an External Secret

By default, the Helm chart has hardcoded credentials. When deploying the chart to a cluster you have to overwrite these values with your own values or specify an external secret which provides the required values. If you e.g. want to specify the database password, add this to your override file:

global:
  postgresql:
    postgresqlPassword: "<your password>"

You can also provide your own secrets instead of having the Helm chart generate them for you. E.g. to specify your own rasaSecret override this value:

rasaSecret: "<name of your secret>"

Your external secret should look like this (with replaced <your value> entries):

apiVersion: "v1"
kind: "Secret"
metadata:
  name: "<name of your secret>"
type: "Opaque"
data:
  rasaToken: {{ <your value> | b64enc | quote }}
  rasaXToken: {{ <your value>| b64enc | quote }}
  passwordSalt: {{ <your value> | b64enc | quote }}
  jwtSecret: {{<your value> | b64enc | quote }}

To see the required structure for secrets used by the subcharts, please follow the documentation of the subcharts. You can find the necessary links in the values file of the Rasa X chart.

Using HTTPS

We recommend that you enable HTTPS on your server by adding SSL certificates (for example using Let’s encrypt).

The recommended way of doing it is to enable SSL on either the ingress controller or the load balancer serving the ingress. Please refer to the documentation of your cloud provider / ingress controller.

You can also configure the Nginx reverse proxy in the chart to use SSL. To do so, you need a PEM-encoded private key file (privkey.pem) and a PEM-encoded certificate chain file (fullchain.pem). Provide their content in a secret, which looks like the following:

apiVersion: "v1"
kind: "Secret"
metadata:
  name: <your secret name>
type: "Opaque"
stringData:
  privkey.pem: <content of the private key file>
  fullchain.pem: <content of the certificate chain file>

Then specify the name of this secret in your override file:

nginx:
  certificateSecret: "<your secret name>"

This will automatically be mounted in the correct place within the Nginx pod.

Debug Mode

Sometimes it’s helpful to have more log messages in the Rasa pods. To activate the debug mode for all Rasa and Rasa X pods, use the following configuration:

debugMode: "true"

Separate Event Consumer

By default, the Helm chart is configured to launch the event-service as a separate service. This means it is a replicable pod, and this is the recommended setting for high-load setups. For smaller cluster setups, you can configure Rasa X to launch an event consumer automatically as a suprocess. To do this, add the following line to your override file:

separateEventService: "false"

Deploying With Helm

If your cluster has Helm configured, you can install the Rasa X chart with the command:

$ helm repo update
$ helm install --values <path to your override file> <release name> rasa-x/rasa-x

Upgrading the Deployment

If you want to upgrade the Rasa X chart to a newer version or change values for an already installed Rasa X release, you can use this command:

$ helm repo update
$ helm upgrade --values <path to your override file> <release name> rasa-x/rasa-x

Using Helm to Generate Object Configurations

Even if Helm is not configured in your cluster, you can still use the Helm command-line interface to generate the OpenShift / Kubernetes object configurations for Rasa X with your custom overrides:

$ helm repo update
$ helm template --values <path to your override file> <release name> rasa-x/rasa-x generated.yml

You can then deploy these manually by running:

$ kubectl create -f generated.yml  # Kubernetes
$ oc create -f generated.yml       # OpenShift

Logging in for the First Time

Rasa X CE

If you are using Rasa X CE, please set your admin password by executing this within the Rasa X pod:

$ kubectl exec -it <Rasa X pod name> bash  # Kubernetes
$ oc exec -it <Rasa X pod name> bash       # OpenShift


$ cd scripts
$ python manage_users.py create --update me <your password> admin

Rasa X EE

You can create a new user by using the terminal of the Rasa X pod:

$ kubectl exec -it <Rasa X pod name> bash  # Kubernetes
$ oc exec -it <Rasa X pod name> bash       # OpenShift


$ cd scripts
$ python manage_users.py create [username] [password] [role]

Possible values for role are admin, annotator, and tester.

Once you’re logged in, you can set up Integrated Version Control to connect your Rasa X instance to a git repository for easy versioning of your assistant.