Workflow configuration

This document covers how to configure the workflow service through its Helm Chart.

Application configuration

Everything in this section goes into the chart’s workflowConfig value, which becomes the workflow service’s entire configuration file.

The chart ships a populated workflowConfig. If you leave a setting unchanged, the workflow service runs with each setting’s. If you delete a key from that block, the service runs with no value, except service.hostname, which is derived from the pod’s hostname.

To override individual keys, use the environment variable listed with each setting, supplied through the chart’s envVars, extraEnvVars, or additionalSecrets.

`http`

Value	Description
`http.port`	Port the workflow service listens on. Serves the Restate handler, `/healthz`, and `/metrics`. The chart’s container port, probes, and Service all assume the default, so changing the port means changing `service.port` with it. Environment variable: `RHIZE_WORKFLOW_HTTP_PORT` Default: `8081` Example: `8081` Type: string

`libreDataStoreGraphQl`

The BAAS GraphQL endpoint, and the CA certificate used to reach that endpoint over TLS.

Value Description

Value	Description
`libreDataStoreGraphQl.serverUrl` [Required]	URL of the BAAS GraphQL endpoint. Every query and mutation the engine performs goes here, so an unreachable value leaves the engine unable to load or record anything. Environment variable: `RHIZE_WORKFLOW_LIBREDATASTOREGRAPHQL_SERVERURL` Default: `http://baas-alpha:8080/graphql` Example: `http://baas-alpha:8080/graphql` Type: string
`libreDataStoreGraphQl.caFile`	Path to a PEM CA certificate to add to the system trust pool when calling the GraphQL endpoint over TLS. Leave empty to use system roots only. A path that cannot be read or parsed stops the workflow service from starting. Set to `/certs/ca-cert.pem` by the chart when `graphqlCA` is provided. Environment variable: `RHIZE_WORKFLOW_LIBREDATASTOREGRAPHQL_CAFILE` Example: `/certs/ca-cert.pem` Type: string

libreDataStoreGraphQl.serverUrl
[Required]

URL of the BAAS GraphQL endpoint. Every query and mutation the engine performs goes here, so an unreachable value leaves the engine unable to load or record anything.
Environment variable: RHIZE_WORKFLOW_LIBREDATASTOREGRAPHQL_SERVERURL
Default: http://baas-alpha:8080/graphql
Example: http://baas-alpha:8080/graphql
Type: string

libreDataStoreGraphQl.caFile

Path to a PEM CA certificate to add to the system trust pool when calling the GraphQL endpoint over TLS. Leave empty to use system roots only. A path that cannot be read or parsed stops the workflow service from starting. Set to /certs/ca-cert.pem by the chart when graphqlCA is provided.
Environment variable: RHIZE_WORKFLOW_LIBREDATASTOREGRAPHQL_CAFILE
Example: /certs/ca-cert.pem
Type: string

`logging`

Value	Description
`logging.level`	Minimum log level: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, or `panic`. An invalid value logs a warning and falls back to `trace`. Environment variable: `RHIZE_WORKFLOW_LOGGING_LEVEL` Default: `debug` Example: `info` Type: string
`logging.type`	Output format. `json` emits structured JSON to stderr, `multi` writes console format to stderr and JSON to stdout, and anything else falls back to console. Environment variable: `RHIZE_WORKFLOW_LOGGING_TYPE` Default: `console` Example: `console` Type: string

`oidc`

Value	Description
`oidc.serverUrl` [Required]	Base URL of the OIDC provider. Environment variable: `RHIZE_WORKFLOW_OIDC_SERVERURL` Default: `http://keycloak:80` Example: `http://keycloak:80` Type: string
`oidc.realm` [Required when `oidc.enableGenericOidc` is `false`]	Keycloak realm. Environment variable: `RHIZE_WORKFLOW_OIDC_REALM` Default: `libre` Example: `libre` Type: string
`oidc.clientId` [Required]	Client ID. Tokens are obtained with the client credentials grant, so the client’s service account needs the required roles in the provider. Environment variable: `RHIZE_WORKFLOW_OIDC_CLIENTID` Example: `libreWorkflow` Type: string
`oidc.clientSecret` [Required]	Client secret paired with `oidc.clientId`. Supply from a Kubernetes Secret. Environment variable: `RHIZE_WORKFLOW_OIDC_CLIENTSECRET` Example: `Qm7xT2vLp9RcW4nZk8HbY3jDf6sGa1Ue` Type: string
`oidc.enableGenericOidc`	Switches to a generic OIDC provider such as Okta rather than Keycloak-specific handling. Environment variable: `RHIZE_WORKFLOW_OIDC_ENABLEGENERICOIDC` Default: `false` Example: `false` Type: boolean
`oidc.customRolesKey` [Required when `oidc.enableGenericOidc` is `true`]	Claim to read roles from when using a non-Keycloak provider. Environment variable: `RHIZE_WORKFLOW_OIDC_CUSTOMROLESKEY` Example: `rhize.com/roles` Type: string
`oidc.customAudienceKey`	Claim to read the audience from when using a non-Keycloak provider. Environment variable: `RHIZE_WORKFLOW_OIDC_CUSTOMAUDIENCEKEY` Example: `rhize.com/aud` Type: string
`oidc.credentialsScope`	Optional scope requested during the client credentials grant. Environment variable: `RHIZE_WORKFLOW_OIDC_CREDENTIALSSCOPE` Example: `openid` Type: string

`openTelemetry`

Value	Description
`openTelemetry.serverUrl`	OTLP gRPC endpoint for trace export, sent without TLS. Environment variable: `RHIZE_WORKFLOW_OPENTELEMETRY_SERVERURL` Default: `http://grafana:4317` Example: `http://tempo-distributor.monitoring.svc.cluster.local:4317` Type: string

`secret`

Value	Description
`secret.key` [Required when a workflow reads a stored secret]	Passphrase used to derive the `age` scrypt identity that decrypts secret values stored in BAAS. Must be the same passphrase the secrets were encrypted with. Supply from a Kubernetes Secret. Environment variable: `RHIZE_WORKFLOW_SECRET_KEY` Example: `ExamplePassphrase-Rhize-2026` Type: string

`kafka`

Value	Description
`kafka.serverName` [Required when a workflow uses a Kafka write task]	Hostname of the Kafka or Redpanda broker, joined with `serverPort` to form the bootstrap address. Only used by the Kafka write task. Environment variable: `RHIZE_WORKFLOW_KAFKA_SERVERNAME` Default: `redpanda` Example: `redpanda` Type: string
`kafka.serverPort` [Required when a workflow uses a Kafka write task]	Broker port. Environment variable: `RHIZE_WORKFLOW_KAFKA_SERVERPORT` Default: `29092` Example: `9092` Type: string

`typescript`

Where the expressions in JSONata, GraphQL, REST, and rule evaluation tasks are evaluated: inside the workflow service, or by typescript-host-service.

Value	Description
`typescript.mode`	`local` evaluates expressions inside the workflow service, so no `typescript-host-service` is needed. `grpc` sends them to `typescript-host-service` at `typescript.serverName` and `typescript.serverPort`. Environment variable: `RHIZE_WORKFLOW_TYPESCRIPT_MODE` Default: `local` Example: `local` Type: string
`typescript.poolSize`	Number of JavaScript runtimes kept ready for `local` evaluation. Size it to the most expressions evaluated at once, such as the branch count of a parallel gateway. `0` uses one per CPU, with a minimum of 4. Environment variable: `RHIZE_WORKFLOW_TYPESCRIPT_POOLSIZE` Default: `0` Example: `0` Type: integer
`typescript.serverName` [Required when `typescript.mode` is `grpc`]	Hostname of `typescript-host-service`. Environment variable: `RHIZE_WORKFLOW_TYPESCRIPT_SERVERNAME` Example: `typescript-host-service` Type: string
`typescript.serverPort` [Required when `typescript.mode` is `grpc`]	gRPC port of `typescript-host-service`, matching that service’s `grpc.listener` port. Environment variable: `RHIZE_WORKFLOW_TYPESCRIPT_SERVERPORT` Example: `9082` Type: string

`restate`

Value	Description
`restate.adminUrl` [Required]	Restate admin API. Used at startup to register this deployment with Restate, and afterwards to list services and manage invocations. Registration failure is logged as a warning rather than being fatal, but an unregistered engine never receives work. Environment variable: `RHIZE_WORKFLOW_RESTATE_ADMINURL` Default: `http://restate:9070` Example: `http://restate:9070` Type: string
`restate.serverUrl` [Required]	Restate ingress URL the workflow service posts to when invoking handlers. Environment variable: `RHIZE_WORKFLOW_RESTATE_SERVERURL` Example: `http://restate:8080` Type: string

`service`

Value	Description
`service.hostname` [Required]	Address Restate is told to call this engine back on, combined with `http.port` to form the registered deployment URI. The derived value only resolves when that prefix happens to match the Kubernetes Service name, so existing deployments set it explicitly. Environment variable: `RHIZE_WORKFLOW_SERVICE_HOSTNAME` Default: pod hostname up to the first `-` Example: `workflow` Type: string

`jsonSchema`

Value	Description
`jsonSchema.registry` [Required when a workflow uses a JSON Schema task]	Base URL of the JSON Schema registry. Schema references in a JSON Schema task that are not already absolute `http://` or `https://` URLs are resolved against this prefix. Environment variable: `RHIZE_WORKFLOW_JSONSCHEMA_REGISTRY` Example: `http://schema-registry:8080` Type: string

Helm chart values

Values shared by every chart are documented in shared-helm-values.md. Only values specific to this chart are listed here.

Note that this chart deploys a StatefulSet, not a Deployment, and creates a headless Service alongside the normal one.

Value	Description
`workflowConfig` [Required]	The complete application configuration, rendered verbatim into the `workflow-config` ConfigMap as `config.yaml`. Every key in the section above goes here. Default: the block described above Example: the Application configuration section Type: object
`envVars`	Map of literal environment variable names to values, passed straight to the container. The usual way to override a single config key without restructuring `workflowConfig`. Example: see the example block below Type: map
`extraEnvVars`	Raw list of container `env` entries, rendered as-is so each supports `value` or `valueFrom`. Use for credentials sourced from an existing Secret. Example: see the example block below Type: list
`additionalSecrets`	List of entries that each carry one value from a Kubernetes Secret into an environment variable: `name` is the variable the service reads, `secretName` is the Secret to take the value from, and `secretKey` is the name of the entry within that Secret. This is how every credential should reach the workflow service, using the environment variable names listed in the tables above: `RHIZE_WORKFLOW_OIDC_CLIENTSECRET` and `RHIZE_WORKFLOW_SECRET_KEY`. `extraEnvVars` does the same job and also accepts values from sources other than Secrets. Example: see the example block below Type: list
`podManagementPolicy`	StatefulSet pod management. `OrderedReady` starts pods one at a time; `Parallel` starts them all at once for a faster rollout. This is safe because every replica receives a copy of each broker message, and the duplicate copies are discarded further along, so a message is still only acted on once. Default: `OrderedReady` Example: `OrderedReady` Type: string
`updateStrategy`	Overrides the StatefulSet update strategy. Empty means the StatefulSet default of `RollingUpdate`. Example: `{type: RollingUpdate}` Type: object
`graphqlCA`	Contents of a PEM CA certificate for calling the GraphQL endpoint over TLS, given as a YAML block, `graphqlCA: \|`, with the certificate’s lines indented beneath. When set, the certificate is mounted at `/certs/ca-cert.pem` and `libreDataStoreGraphQl.caFile` is set to that path. Example: `-----BEGIN CERTIFICATE-----…` Type: string

A log level set directly, two credentials taken from Secrets, and one variable taken from a Secret through extraEnvVars:

envVars:
  RHIZE_WORKFLOW_LOGGING_LEVEL: info
additionalSecrets:
  - name: RHIZE_WORKFLOW_OIDC_CLIENTSECRET
    secretName: libre-secrets
    secretKey: libreBPMN
  - name: RHIZE_WORKFLOW_SECRET_KEY
    secretName: libre-secrets
    secretKey: workflowSecret
extraEnvVars:
  - name: EXTERNAL_DB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: libre-secrets
        key: externalDbPassword

`brokers`

Add a broker here for each MQTT or AMQP broker whose messages should start or resume a workflow, or that a message throw event publishes to. A message arriving on one of its topics starts a workflow with a matching message start event and resumes a workflow waiting at a matching message catch event.

brokers is a map whose keys are broker ids you choose, so each setting is written brokers.<id>.<field>. The id is meaningful: a BPMN message named <id>.<topic> binds to <topic> on that broker.

These are the only chart values that reach the pod as environment variables and nothing else, with no ConfigMap involved. The id and the field name both become part of the variable name, so brokers.test_mqtt.protocol arrives as RHIZE_WORKFLOW_BROKERS_TEST_MQTT_PROTOCOL. Every field accepts either a scalar, which becomes a literal value, or a map naming an existing Kubernetes Secret and the entry within it — {secretName: …, secretKey: …} — so that the value never appears in the manifest.

Value	Description
`brokers.<id>.protocol` [Required when the broker entry is defined]	Kind of broker: `MQTT` or `AMQP`. Environment variable: `RHIZE_WORKFLOW_BROKERS_<ID>_PROTOCOL` Example: `MQTT` for MQTT, `AMQP` for AMQP Type: string
`brokers.<id>.connectionString` [Required when the broker entry is defined]	Address of the broker. The scheme has to match the protocol: `mqtt://` on 1883 or `mqtts://` for MQTT, `amqp://` on 5672 or `amqps://` on 5671 for AMQP. The `s` variants are the TLS ports. Environment variable: `RHIZE_WORKFLOW_BROKERS_<ID>_CONNECTIONSTRING` Example: `mqtt://mqtt:1883` for MQTT, `amqp://amqp-broker:5672` for AMQP Type: string
`brokers.<id>.username`	Username for the broker. Usually a literal, since it is not sensitive. Omit for an anonymous connection. Environment variable: `RHIZE_WORKFLOW_BROKERS_<ID>_USERNAME` Example: `rhize-workflow` Type: string or map
`brokers.<id>.password`	Password for the broker. Give this as a map naming a Kubernetes Secret and the entry within it rather than as a literal. Environment variable: `RHIZE_WORKFLOW_BROKERS_<ID>_PASSWORD` Example: `{secretName: libre-secrets, secretKey: mqttPassword}` Type: string or map
`brokers.<id>.certificate`	Client certificate for the broker, for use with an `mqtts://` or `amqps://` connection string. Environment variable: `RHIZE_WORKFLOW_BROKERS_<ID>_CERTIFICATE` Example: `{secretName: libre-secrets, secretKey: mqttCert}` Type: string or map
`defaultBroker`	Broker id that a BPMN message with a bare topic name, carrying no `<id>.` prefix, falls back to. Name one of the ids in `brokers`, or leave this empty to require every message name to carry a prefix. Environment variable: `RHIZE_WORKFLOW_DEFAULTBROKER` Example: `test_mqtt` Type: string

Two brokers, with the MQTT password taken from a Secret:

defaultBroker: test_mqtt
brokers:
  test_mqtt:
    protocol: MQTT
    connectionString: "mqtt://mqtt:1883"
    password:
      secretName: libre-secrets
      secretKey: mqttPassword
  test_amqp:
    protocol: AMQP
    connectionString: "amqp://amqp-broker:5672"
    username: svc

A workflow uses a broker through the Message section of an event’s properties in the BPMN editor. Choose a Global message reference, or create one, and give it a Name made of the broker id, a ., and the topic. With the brokers above:

On a message start event, the Name test_mqtt.orders starts the workflow each time a message arrives on the orders topic of test_mqtt.
On a message intermediate throw event, the Name test_amqp.order-accepted publishes to the order-accepted topic of test_amqp when the workflow reaches that event.

TypeScript host service configuration