Deploy Syntho using Helm

To deploy the Syntho Application, we will use the Helm chart in the same repository as mentioned before. The chart can be found in the Releases of the deployment-tools repo or it can be cloned directly from the Github repo, which will make the path to the chart helm/syntho-ui

To configure the UI, the values.yaml file in helm/syntho-ui can be used. The following sections will describe the different fields that can be set.

Configuring the UI

For the UI, we will need to set the image repository and tag first:

image:
  repository: synthoregistry.azurecr.io/syntho-core-frontend
  tag: latest

We will also need to set the domain name for the UI.

frontend_url: <hostname-or-ip>
frontend_protocol: https # http or https depending on the availability of an SSL certificate

An ingress is required for the UI and is part of the Helm chart, we can set the ingress configuration as follows for the UI:

ingress:
    enabled: true
    name: frontend-ingress
    className: nginx  # Set to class name of the ingress controller you are using
    annotations: {
      cert-manager.io/cluster-issuer: "", # In case cert-manager is used for SSL
      nginx.ingress.kubernetes.io/proxy-buffer-size: "32k",
      nginx.ingress.kubernetes.io/affinity: "cookie",
      nginx.ingress.kubernetes.io/use-regex: "true",
      nginx.ingress.kubernetes.io/proxy-connect-timeout: "600",
      nginx.ingress.kubernetes.io/proxy-read-timeout: "600",
      nginx.ingress.kubernetes.io/proxy-send-timeout: "600",
      nginx.ingress.kubernetes.io/proxy-body-size: "512m",
    }
    hosts:
      - host: <hostname>
        paths:
          - path: /
            pathType: Prefix
    
    tls:  # In case SSL is not used, the tls section can be removed
      - hosts:
        - <hostname>
        secretName: frontend-tls  # Set to either existing secret or when using cert-manager to manage certificates

This will create an Ingress definition for both the UI and backend application. Part of the traffic will be routed to the backend, in order to be able to serve all traffic from the same domain name.

Configuring the Backend

The backend is responsible for user management and workspace management. We need to set a few variables correctly. To start off, we need to set the image:

backend:
  image:
    repository: synthoregistry.azurecr.io/syntho-core-backend
    tag: latest

Backend Database and Backend Redis

We then need to set the database credentials and Redis credentials. If the instances defined in the Helm chart are being used, no changes are needed. Otherwise, the following need to be changed:

backend:
  db:
    host: <hostname>
    port: <port>
    user: <username>
    password: <password>
    name: <database>
  redis:
    host: redis-svc
    port: 6379
    db: 0

The Redis section can be set as defined above if the Redis instance is being used from the Helm chart. The default behavior will deploy the Redis instance defined in the chart. If a different Redis instance is being used, host, port and db might need to be changed.

The database section needs to be changed if a different database is being used. The default behavior will deploy the database instance defined in the chart. If a different database outside the Helm chart is being used, the host, port, user, password, and database name need to be changed. To disable the usage and deployment of the database instance defined in the chart, the following can be set:

backend:
  database_enabled: false

If the database is being used from the Helm chart, the value host can be set to database and port to 5432. The other values can be changed in case a different username, password, or database name is preferred. This will automatically adjust the database instance defined in the Helm chart.

Backend Ingress

The backend ingress is implemented as part of the ingress defined for the UI. We use path-based routing in the ingress in order to route part of the traffic to the backend (specifically everything going to /api/* ). There's no additional ingress necessary for the backend.

Admin user credentials

Setting up the credentials for the first administrative user is also necessary. We can define this user in the following way:

backend:
  user:
    username: admin
    password: password
    email: [e-mail]

This user can be used to log into the UI and create other users.

Secret key

Lastly, we need to set an additional variable, as defined in the block below:

secret_key: (^ky&f)l&$3sqf2tctv-(pgzvh!+9$j%b5xe2y@&%p2ay*h$$a  # Random string to use as a secret key

Configuring the Core API

To configure the Core API, we will need to first set the correct image. To set the image we will use the image field in the core section.

image:
  repository: synthoregistry.azurecr.io/syntho-core-api
  tag: latest

Furthermore, we need to set the database hostname and credentials:

core:
  db:
    username: <database-username>
    password: <database-password>
    name: <database-name>
    host: <database-host>
    port: <database-port>

The deployment can possibly create the database instance itself. In that case, the database_enabled field should be set to true:

core:
  database_enabled: true

This will create a database with the specified username, password, and database name. The host for this database is backend and the port will be 5432 as this is a Postgres database.

Lastly, we need to set a secret key for encryption purposes, the credentials for a Redis instance and the Ray head IP or hostname to connect to. The Ray head hostname is the one mentioned in the section Deploy Ray using Helm.

secret_key: UNIbrRR0CnhPEB0BXKQSDASaNzT1IYgQWWaLyQ1W1iPg= # Fernet Key: generate by running  python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
redis:
    host: redis-svc
    port: 6379
    db: 1
ray_address: <ray-head-ip-or-hostname>

The fernet key can be generated using the cryptography library in Python. Running the following command will result in a randomly generated fernet key in your CLI:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

The Redis instance can be set by adjusting the redis: section. The default values will point it towards the Redis instance deployed as part of the Helm chart.

Setting secrets

By default, this Helm chart creates two secrets called core-secret and backend-secret. Both secrets contain values that will be attached to the relevant pods using the content that is in the secret.

It is possible to change this secret into one that will be created outside of the helm chart, instead of relying on the secret created from the Helm chart. This can help with integrating external secret management tools.

For the Backend, if the value backend.manualSecretName is set in the Helm chart values, then the secret has to be created manually (with the name supplied in the value of manualSecretName). The same applies for the Core API, where the value is core.manualSecretName.

The structure for the secrets of both the Core API and Backend is as follows:

# backend-secret
apiVersion: v1
kind: Secret
metadata:
  name: backend-secret
type: Opaque
data:
  backend.db.password: <base64-encoded>
  backend.secret_key: <base64-encoded>
  backend.user.password: <base64-encoded>

# core-secret
apiVersion: v1
kind: Secret
metadata:
  name: "core-secret"
type: Opaque
stringData:
  core.secret_key: {{ .Values.core.secret_key }}
  core.database_url: "postgresql+asyncpg://{{ .Values.core.db.username }}:{{ .Values.core.db.password }}@{{ .Values.core.db.host }}:{{ .Values.core.db.port | default "5432" }}/{{ .Values.core.db.name }}"
  license_key: {{ .Values.SynthoLicense }}

If separate secrets are required, please create them in the same namespace using the structure above.

Deploy

To deploy the Syntho Application, we will use the Helm chart provided by the Syntho team. The chart can be found in the helm/syntho folder.

helm install syntho-ui ./helm/syntho-ui --values values.yaml --namespace syntho