This documentation is available to agents as Markdown at https://docs.synthesized.io/tdk/latest/user_guide/050_deployment_operations/production_setup/helm.md. For the complete documentation index, see llms.txt.

Kubernetes and OpenShift

Install Governor and its workers in your Kubernetes or OpenShift cluster with the Helm chart. Governor’s data goes in your own PostgreSQL database, and your ingress serves it over HTTPS.

To try the platform first, use the demo. To run Governor on one server without Kubernetes, use Docker Compose.

Before you start

  • A Kubernetes or OpenShift cluster with the baseline capacity, and an ingress controller.

  • kubectl set up for the cluster, and Helm 3. For a cloud cluster, see how to connect kubectl on Google Cloud, Azure or AWS.

  • An empty PostgreSQL 13 or later database for Governor, reachable from the cluster, and the user name and password for it.

  • Your Synthesized license key.

  • A DNS name for Governor, and a Kubernetes TLS secret with its certificate in the namespace you install into.

The chart is at oci://synthesizedio.jfrog.io/helm/governor. For a cluster without internet access, see Offline Installation.

1. Generate the secrets

Set the database details and generate the secrets as shell variables. Keep a copy of each in your secret store.

  • Linux and macOS

  • Windows (PowerShell 7.2 or later)

export DB_URL="jdbc:postgresql://<host>:5432/<database>"
export DB_USERNAME="<db-username>"
export DB_PASSWORD="<db-password>"
export JWT_SECRET=$(openssl rand -base64 256 | tr -d '\n')
export CREDENTIALS_ENCRYPTION_KEY=$(openssl rand -base64 32)
export ADMIN_EMAIL="<admin-email>"
export ADMIN_DEFAULT_PASSWORD=$(openssl rand -hex 20 | tr -d '\n')
export SYNTHESIZED_KEY="<license-key>"
$DB_URL="jdbc:postgresql://<host>:5432/<database>"
$DB_USERNAME="<db-username>"
$DB_PASSWORD="<db-password>"
$JWT_SECRET=[Convert]::ToBase64String([Security.Cryptography.RandomNumberGenerator]::GetBytes(256))
$CREDENTIALS_ENCRYPTION_KEY=[Convert]::ToBase64String([Security.Cryptography.RandomNumberGenerator]::GetBytes(32))
$ADMIN_EMAIL="<admin-email>"
$ADMIN_DEFAULT_PASSWORD=[Convert]::ToHexString([Security.Cryptography.RandomNumberGenerator]::GetBytes(20))
$SYNTHESIZED_KEY="<license-key>"

Windows PowerShell 5.1 doesn’t support these commands.

Variable What it’s for

DB_URL, DB_USERNAME, DB_PASSWORD

Governor’s database, as a JDBC URL and its credentials.

JWT_SECRET

Signs sign-in tokens. If it changes later, every user is signed out.

CREDENTIALS_ENCRYPTION_KEY

Encrypts the data source passwords Governor stores, with AES and this 256-bit key. Set your own key in every production installation. If the key is lost, the stored passwords can’t be recovered. To rotate it, set the new key and the old one, separated by a semicolon (<new-key>;<old-key>); Governor re-encrypts the passwords at the next restart.

ADMIN_EMAIL, ADMIN_DEFAULT_PASSWORD

The first administrator account. Change the password after the first sign-in.

SYNTHESIZED_KEY

Your license key. It’s checked offline. Without it, Governor runs in free mode. See License.

2. Write values.yaml

Keep the settings that aren’t secret in a values.yaml file. This one sets up the ingress for the web UI:

ingress:
  enabled: true
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
  hosts:
    - host: governor.example.com
      paths:
        - path: /
          service: governor-front
          servicePort: 80
  tls:
    - secretName: governor-tls-secret
      hosts:
        - governor.example.com

governor-front serves the web UI over HTTP on port 80, so the ingress must terminate TLS. Use TLS 1.2 or later.

Value What it sets

ingress.enabled

true creates the ingress resource.

ingress.annotations

Annotations for your ingress controller or cloud provider.

ingress.hosts[].host

Governor’s DNS name.

ingress.hosts[].paths

The paths, each with the service and servicePort it routes to.

ingress.tls[].secretName

The TLS secret with the certificate. Create it before you install.

ingress.tls[].hosts

The DNS names the certificate covers.

Point the DNS name at your ingress controller’s external address.

Other settings for Governor go under api.container.config, for example the UI_* feature flags. Secrets go under api.container.secretConfig. See Governor and Worker Settings.

3. Install the chart

Find the latest chart version with helm show chart oci://synthesizedio.jfrog.io/helm/governor, in its version field. Then install it, with the secrets passed on the command line:

  • Linux and macOS

  • Windows (PowerShell)

helm install governor oci://synthesizedio.jfrog.io/helm/governor --version <chart-version> \
  --namespace <namespace> --create-namespace -f values.yaml \
  --set api.container.secretConfig.SPRING_DATASOURCE_URL=$DB_URL \
  --set api.container.secretConfig.SPRING_DATASOURCE_USERNAME=$DB_USERNAME \
  --set api.container.secretConfig.SPRING_DATASOURCE_PASSWORD=$DB_PASSWORD \
  --set api.container.secretConfig.JWT_SECRET=$JWT_SECRET \
  --set api.container.secretConfig.ADMIN_EMAIL=$ADMIN_EMAIL \
  --set api.container.secretConfig.ADMIN_DEFAULT_PASSWORD=$ADMIN_DEFAULT_PASSWORD \
  --set api.container.secretConfig.SYNTHESIZED_KEY=$SYNTHESIZED_KEY \
  --set api.container.secretConfig.CREDENTIALS_ENCRYPTION_KEY="$CREDENTIALS_ENCRYPTION_KEY"
helm install governor oci://synthesizedio.jfrog.io/helm/governor --version <chart-version> `
  --namespace <namespace> --create-namespace -f values.yaml `
  --set api.container.secretConfig.SPRING_DATASOURCE_URL=$DB_URL `
  --set api.container.secretConfig.SPRING_DATASOURCE_USERNAME=$DB_USERNAME `
  --set api.container.secretConfig.SPRING_DATASOURCE_PASSWORD=$DB_PASSWORD `
  --set api.container.secretConfig.JWT_SECRET=$JWT_SECRET `
  --set api.container.secretConfig.ADMIN_EMAIL=$ADMIN_EMAIL `
  --set api.container.secretConfig.ADMIN_DEFAULT_PASSWORD=$ADMIN_DEFAULT_PASSWORD `
  --set api.container.secretConfig.SYNTHESIZED_KEY=$SYNTHESIZED_KEY `
  --set api.container.secretConfig.CREDENTIALS_ENCRYPTION_KEY="$CREDENTIALS_ENCRYPTION_KEY"

On OpenShift, add --set openShiftEnabled=true.

helm upgrade doesn’t keep the values you passed with --set. Pass them again at each upgrade, or keep them in a Kubernetes Secret that the chart reads through api.container.secretEnv. See Update Helm.

4. Check the pods

kubectl get pods -n <namespace>

The governor-api, governor-front and governor-worker pods should be Running. If governor-api isn’t, the cause is usually the database connection: check the URL, the user name and the password, and read kubectl logs deployment/governor-api -n <namespace>.

Workers

The chart deploys workers as the governor-worker deployment. To run several workflows at once, raise worker.replicaCount. See Multiple Workers.

The chart sets WORKER_USEPLAINTEXT to true, so workers connect to Governor without TLS. To encrypt the connection, turn on the chart’s built-in mutual TLS (tlsInternal.enabled: true) or use your own certificates. See Worker–Governor mTLS.

Check that it works

  1. Open https://governor.example.com and sign in as the first administrator.

  2. Change the administrator’s password.

  3. Under Administration > Workers, check that the worker is connected.

  4. Add a data source and test its connection.

Next steps