Rasa X version 0.33.0 or higher is only compatible with Rasa Open Source 2.x. If you are on Rasa Open Source 1.x, please check the [compatibility matrix](https://legacy-docs-rasa-x.rasa.com/docs/rasa-x/changelog/compatibility-matrix) for a compatible version.

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

Rasa X is available as a [Helm Chart](https://helm.sh/) for a cluster setup. If you are not using Helm in your cluster, you can still use the following instructions to generate the Kubernetes or OpenShift object configurations via the Helm command-line interface, and install those configurations manually.

## Installation

##### note  
If you’re installing Rasa Enterprise, please follow the Rasa Enterprise instructions where given. If a step does not have separate instructions, the step applies to both Rasa X and Rasa Enterprise.

##### note  
The support for the Rasa Open Source server deployment in the Rasa X Helm chart will be dropped in the future.  
It's recommended to use [the Rasa Helm chart](https://artifacthub.io/packages/helm/rasa/rasa) to deploy Rasa Open Source, more info you can find in [the docs](/content/docs/rasa/how-to-deploy/index.html).

### 1. Create Namespace

We recommend installing Rasa X in a separate [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) to avoid interfering with existing cluster deployments. To create a new namespace run the following command:

- Kubernetes  
`kubectl create namespace <your namespace>`

### 2. Create Values File

Prepare an empty file called `values.yml` which will include all your custom configuration for the installation with Helm.

### 3. Configure Credentials

To configure the credentials, copy the section below into the `values.yml` file and replace each `<safe credential>` marker with a different alphanumeric string. Please use safe credentials to avoid data breaches.

```yaml
# rasax specific settings
rasax:
  initialUser:
    username: "<username>"
    password: "<safe credential>"
    passwordSalt: "<safe credential>"
    token: "<safe credential>"
    jwtSecret: "<safe credential>"
rasa:
  token: "<safe credential>"
rabbitmq:
  auth:
    password: "<safe credential>"
global:
  postgresql:
    postgresqlPassword: "<safe credential>"
  redis:
    password: "<safe credential>"
```

### 4. Specify Rasa X and Rasa Open Source Versions

You can install the latest stable Rasa X version and the latest Rasa Open Source version by specifying the following in your `values.yml`:

```yaml
rasax:
  tag: "1.1.0"
rasa:
  tag: "undefined-full"
```

To install the latest edge release of Rasa X instead, set the `latest` tag for Rasa X:

```yaml
rasax:
  tag: "latest"
rasa:
  tag: "undefined-full"
```

You can also choose any compatible Rasa X and Rasa Open source versions according to the [Compatibility Matrix](https://legacy-docs-rasa-x.rasa.com/docs/rasa-x/changelog/compatibility-matrix).

### 5. **Optional**: Configure Custom Action Server

See [these instructions](https://legacy-docs-rasa-x.rasa.com/docs/rasa-x/installation-and-setup/configure/add-action-server) to configure a custom action server.

##### note  
If you are following the [Using Helm to Generate Object Configurations](https://legacy-docs-rasa-x.rasa.com/docs/rasa-x/installation-and-setup/install/helm-chart-installation/installation/#using-helm-to-generate-object-configurations) guide, stop here and continue with them.

### 6. Deploy Rasa X

Run the following commands:

```bash
# Add the repository which contains the Rasa X Helm chart
helm repo add rasa-x https://rasahq.github.io/rasa-x-helm

# Deploy Rasa X
helm install --generate-name --namespace <your namespace> --values values.yml rasa-x/rasa-x
```

##### note  
**OpenShift only**: OpenShift requires additional settings related to the security context, in the Rasa X Helm chart repository, you can find an [example values file](https://github.com/RasaHQ/rasa-x-helm/blob/main/examples/openshift-values.yaml) with settings for OpenShift.

Then wait until the deployment is ready. If you want to check on its status, the following command will block until the Rasa X deployment is ready:

```bash
kubectl --namespace <your namespace> wait --for=condition=available --timeout=20m --selector app.kubernetes.io/component=rasa-x deployment
```

### 7. Access Rasa X

By default the Rasa X deployment is exposed via the `nginx` service. You can get the IP address using this command:

```bash
kubectl --namespace <your namespace> get service -l app.kubernetes.io/component=nginx -o jsonpath="{.status.loadBalancer.ingress[0].ip}"
```

You can then access the deployment on `http://<ip>:8000`.

**Note:** Depending on the used cluster/cloud provider this might not work. Please refer to the cloud provider’s documentation/administrator what the recommended way for exposing the `nginx` service is.

### 8. **Optional**: Activate Rasa Enterprise

Rasa X can be upgraded to **Rasa Enterprise** by uploading a valid license. To learn how to do this, please visit the [Product Activation](https://legacy-docs-rasa-x.rasa.com/docs/rasa-x/enterprise/activation) section.

## Reference

### Accessing Secrets

This section describes how to retrieve secrets from your running deployment. You have the option to retrieve the following secrets:

| description                                     | default secret name                        |
|------------------------------------------------|-------------------------------------------|
| PostgreSQL database password                    | `postgresql`                              |
| Redis lock store and cache password             | `redis`                                   |
| RabbitMQ event broker password                  | `rabbit`                                  |

Run the following command, replacing `<secret name>` with one of the values in the table, and `<your namespace>` and `<your release name>` with your namespace and the name of your release:

```bash
secret=<secret name>
namespace=<your namespace>
release_name=<your release name>

kubectl --namespace ${namespace} get secret ${release_name}-${secret} -o yaml | awk -F ': ' '/password/{print $2}' | base64 -d; echo
```

##### note  
If you’re not sure what namespace or release name your deployment runs under, you can use the following commands to find out. To list the available namespaces, run:

```bash
kubectl get namespaces
```

And to list the releases under a particular namespace, run:

```bash
helm list --namespace <your namespace>
```

### Accessing Logs

This section describes how to get logs from the running containers.

1. Get the name of the [pod](https://kubernetes.io/docs/concepts/workloads/pods/pod/) which you want to get the logs of.
   
   ```bash
   kubectl --namespace <your namespace> get pods
   ```

The output should be similar to this:
   
   | NAME                                      | READY | STATUS  | RESTARTS | AGE |
   |-------------------------------------------|-------|---------|----------|-----|
   | rasa-app-58d476497-ktkqn                | 1/1   | Running | 0        | 45m |
   | rasa-duckling-7696b7f474-km6dx         | 1/1   | Running | 0        | 45m |
   | rasa-event-service-7657b6b489-96drn    | 1/1   | Running | 1        | 45m |
   | rasa-nginx-64b6b464f6-p9bmb             | 1/1   | Running | 0        | 45m |
   | rasa-postgresql-0                        | 1/1   | Running | 0        | 45m |
   | rasa-rabbit-0                           | 1/1   | Running | 0        | 45m |
   | rasa-rasa-production-c86fbf7f7-q9pp5    | 1/1   | Running | 0        | 45m |
   | rasa-rasa-worker-5d49485976-6z2kj       | 1/1   | Running | 0        | 45m |
   | rasa-rasa-x-5788cddbb7-5zf86            | 1/1   | Running | 0        | 45m |
   | rasa-redis-master-0                      | 1/1   | Running | 0        | 45m |

`rasa-rasa-x-5788cddbb7-5zf86` is for example the name of the Rasa X container.

2. To get the logs of the container run:
   
   ```bash
   kubectl --namespace <your namespace> logs <name of the pod>
   ```

### Using Helm to Generate Object Configurations

If you don’t want or cannot use Helm to install Rasa X in your cluster, you can still use Helm to generate the Kubernetes / OpenShift resource files.

1. Follow the [installation instructions](https://legacy-docs-rasa-x.rasa.com/docs/rasa-x/installation-and-setup/install/helm-chart-installation/installation/#installation) until the deployment part.

2. Run the following command to generate the Kubernetes / OpenShift resource files and write them in a file `rasa-x-deployment.yml`:
   
   ```bash
   helm repo add rasa-x https://rasahq.github.io/rasa-x-helm
   helm repo update
   helm template --namespace <your namespace> --values values.yml <your release name> rasa-x/rasa-x > rasa-x-deployment.yml
   ```

3. You can then deploy these manually by running:
   
   ```bash
   kubectl --namespace <your namespace> create -f rasa-x-deployment.yml
   ```

## Next Steps

- [Connect a Custom Action Server](https://legacy-docs-rasa-x.rasa.com/docs/rasa-x/installation-and-setup/configure/add-action-server) if you are using custom actions.
- [Set up Integrated Version Control](https://legacy-docs-rasa-x.rasa.com/docs/rasa-x/installation-and-setup/post-deploy-steps/set-up-ivc) to connect your Rasa X instance to a remote Git repository.
- [Set up a CI/CD pipeline](https://legacy-docs-rasa-x.rasa.com/docs/rasa-x/installation-and-setup/post-deploy-steps/set-up-ci-cd) using Rasa X.
- [Deploy a model](https://legacy-docs-rasa-x.rasa.com/docs/rasa-x/installation-and-setup/post-deploy-steps/train-upload-model) using Rasa X.
- [Configure SSL](https://legacy-docs-rasa-x.rasa.com/docs/rasa-x/installation-and-setup/configure/tls) if you’d like to run your Rasa X server on HTTPS.