Kubernetes (Helm)

Deploy Syntho on Kubernetes using Helm charts.

What Helm deploys

This deployment typically includes:

• Frontend (UI)
• Backend
• Core API
• Ray (separate chart)
• PostgreSQL (metadata, optional if you use an external DB)
• Redis (optional if you use an external Redis)

Ray sizing and storage (optional)

Ray capacity depends on your data size and throughput goals. If you didn’t get sizing guidance yet, ask Syntho Support.

Also ensure your cluster can provision shared (RWX) storage for Ray workers when the chart enables shared volumes.

If your StorageClass does not support ReadWriteMany, Ray pods can fail to schedule or start.

OpenShift / CRI-O note: some clusters default to low process limits. Ray can hit those limits when scaling.

Offline deployment

Offline Kubernetes deployments follow the same steps below. You just need to stage artifacts on a connected machine first.

1. Stage Helm charts

   • Download the Helm chart bundles (or clone deployment-tools).
   • Transfer the chart bundles to the offline environment where you run helm upgrade --install.
2. Stage container images

   Your cluster nodes must be able to fetch images.

   • Recommended: mirror images into an internal registry reachable by the cluster nodes.
   • Alternative: preload images onto every node (works, but is harder to operate).

   After mirroring, update image references in both helm/ray/values.yaml and helm/syntho-ui/values.yaml to point to your internal registry (and keep using a specific version tag).
3. Registry authentication step changes

   • If you use an internal registry, create the ImagePullSecret for that registry and reference it via imagePullSecrets.
   • If you preload images on nodes, ensure the chart uses an imagePullPolicy that doesn’t force pulls (commonly IfNotPresent).

Upgrades are the same procedure. Repeat the staging step for the new APPLICATION_VERSION.

Deploy

1

Prerequisites

Make sure you meet the prerequisites before deploying.

2

Get the Helm charts

Use the deployment-tools repository:

• Ray Helm chart
• Syntho Helm chart

If you prefer release artifacts, use the deployment-tools releases matching the version that you are deploying:

• https://github.com/syntho-ai/deployment-tools/releases

Download:

• ray-helm-chart.tar.gz
• syntho-ui-helm-chart.tar.gz

3

Create a namespace

kubectl create namespace syntho

4

Create an ImagePullSecret

kubectl create secret docker-registry syntho-cr-secret \
  --namespace syntho \
  --docker-server=<REGISTRY_HOST> \
  --docker-username=<USERNAME> \
  --docker-password=<PASSWORD>

In both charts, reference it:

imagePullSecrets:
  - name: syntho-cr-secret

Ensure that syntho.azurecr.io is added to your firewall allowlist to enable image pulls

5

Deploy Ray

Ray provides distributed execution for heavy jobs.

Minimal settings in your Ray values file (commonly helm/ray/values.yaml):

Use a specific <version-number> for production. Avoid latest unless Syntho tells you to.

SynthoLicense: <license-key>

kuberay-operator:
  imagePullSecrets:
    - name: syntho-cr-secret

ray-operator:
  imagePullSecrets:
    - name: syntho-cr-secret

ray-cluster:
  imagePullSecrets:
    - name: syntho-cr-secret
  image:
    tag: <version-number>

Deploy:

helm upgrade --install ray-cluster ./helm/ray/chart \
  --values helm/ray/values.yaml \
  --namespace syntho

If your bundle uses a different values filename or path, use that path in --values.

The Ray head service is typically ray-cluster-ray-head. Use it as ray_address in the Syntho chart.

Ray troubleshooting (ArgoCD, permissions)

If Ray pods fail due to volume permissions, set a permissive security context:

ray-cluster:
  head:
    securityContext:
      runAsUser: 0
      runAsGroup: 0
  worker:
    securityContext:
      runAsUser: 0
      runAsGroup: 0

6

Deploy Syntho

Edit your syntho-ui values file (commonly helm/syntho-ui/values.yaml).

Production recommendation: use a hosted / managed PostgreSQL.

See Back up PostgreSQL.

Set images

Set image repositories and tags to the versions provided by Syntho.

Use a specific <version-number> for production. Avoid latest unless Syntho tells you to.

frontend:
  image:
    repository: synthoregistry.azurecr.io/syntho-core-frontend
    tag: <version-number>

backend:
  image:
    repository: synthoregistry.azurecr.io/syntho-core-backend
    tag: <version-number>

core:
  image:
    repository: synthoregistry.azurecr.io/syntho-core-api
    tag: <version-number>

Set license key

Set the license key in the Syntho chart values:

SynthoLicense: <license-key>

Use the same license key value as in helm/ray/values.yaml.

Configure external PostgreSQL (recommended)

Example values

Create an external PostgreSQL host and two databases (common setup):

• Backend metadata DB
• Core API metadata DB

Then configure the Syntho Helm values to use them and disable the embedded databases.

Common values:

backend:
  database_enabled: false
  db:
    host: <pg-host>
    port: 5432
    user: <user>
    password: <password>
    name: <backend-db>

core:
  database_enabled: false
  db:
    host: <pg-host>
    port: 5432
    username: <user>
    password: <password>
    name: <core-db>

Configure Redis

By default, the chart deploys Redis and exposes it as redis-svc.

If you use an external Redis, update these values:

backend:
  redis:
    host: redis-svc
    port: 6379
    db: 0

core:
  redis:
    host: redis-svc
    port: 6379
    db: 1

Using the chart-managed PostgreSQL/Redis (optional)

Keep the embedded dependencies enabled if you don’t run external services.

Disable embedded PostgreSQL by setting database_enabled: false (as shown above).

Minimal example:

backend:
  database_enabled: true
  db:
    host: database
    port: 5432

core:
  database_enabled: true
  db:
    host: database
    port: 5432

If you keep embedded PostgreSQL enabled, the in-cluster service is typically:

• Host: database
• Port: 5432

Frontend URL and Ingress:

frontend_url: <hostname>
frontend_protocol: https # or http

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: <hostname>
      paths:
        - path: /
          pathType: Prefix

The Ingress also routes backend traffic using path-based routing (typically GET /api/*).

You don’t need a separate Ingress for the backend.

Ingress annotations and TLS (nginx + cert-manager example)

ingress:
  enabled: true
  name: frontend-ingress
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: "" # when using cert-manager
    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: # remove this section when not using TLS
    - hosts:
        - <hostname>
      secretName: frontend-tls

Admin user:

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

Backend secret key:

backend:
  secret_key: <random-string>

Core API encryption key:

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

core:
  secret_key: <fernet-key>

Ray address:

ray_address: ray-cluster-ray-head

Use externally managed Kubernetes Secrets (optional)

By default, the chart creates backend-secret and core-secret from your Helm values.

If you want to bring your own Secrets (for example via an external secrets manager), set:

• backend.manualSecretName: <your-secret-name>
• core.manualSecretName: <your-secret-name>

Create the Secrets in the same namespace.

Backend Secret must include:

apiVersion: v1
kind: Secret
metadata:
  name: <backend-manual-secret-name>
type: Opaque
stringData:
  backend.db.password: "<db-password>"
  backend.secret_key: "<backend-secret-key>"
  backend.user.password: "<admin-password>"

Core Secret must include:

apiVersion: v1
kind: Secret
metadata:
  name: <core-manual-secret-name>
type: Opaque
stringData:
  core.secret_key: "<fernet-key>"
  core.database_url: "postgresql+asyncpg://<username>:<password>@<host>:5432/<db>"
  license_key: "<license-key>"

Deploy:

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

If your bundle uses a different values filename or path, use that path in --values.

HTTPS and cookies

If TLS is terminated at a reverse proxy / load balancer / Ingress, Syntho must be configured for https.

If Syntho is configured for http, browsers can reject cookies.

Symptoms include login loops or sessions not sticking.

Fix:

• Set the frontend protocol to https.
• Disable secure cookies.

7

Verify deployment

Check pods:

kubectl get pods -n syntho

Open the UI at your frontend_url.

If pods are not Ready, check logs:

kubectl logs -n syntho <pod-name>

If the UI doesn’t resolve, check DNS and the Ingress external address first.

If this does not work, see Troubleshooting.

8

Back up PostgreSQL

Back up PostgreSQL Syntho application databases before first use to validate the process.

Next steps

• Day-to-day commands: Operations
• Upgrade procedure: Upgrade
• Common issues: Troubleshooting