Skip to main content

Kubernetes

Zigflow provides an official Helm chart for deploying to Kubernetes.

What you will learn​

  • How to install the Zigflow Helm chart from the OCI registry
  • How to deliver a workflow definition via inline YAML or Kubernetes Secret
  • How to connect the worker to Temporal and configure environment variables
  • How to scale workers and configure horizontal pod autoscaling

Helm chart​

The chart is published to the GitHub Container Registry as an OCI artifact.

Install​

Replace ${ZIGFLOW_VERSION} with a published version:

helm install my-workflow oci://ghcr.io/mrsimonemms/charts/zigflow@${ZIGFLOW_VERSION}

Minimal configuration​

The chart requires at minimum a Temporal server address and a workflow definition. The simplest configuration uses an inline workflow:

values.yaml
config:
  temporal-address: temporal:7233

workflow:
  useInline: true
  inline:
    document:
      dsl: 1.0.0
      namespace: zigflow
      name: hello-world
      version: 1.0.0
    do:
      - greet:
          set:
            message: Hello from Ziggy
          output:
            as:
              data: ${ . }

Install with custom values:

helm install my-workflow oci://ghcr.io/mrsimonemms/charts/zigflow@${ZIGFLOW_VERSION} \
  -f values.yaml

Workflow delivery options​

The chart supports two ways to provide the workflow file:

Option 1 — Inline YAML (default)​

Set workflow.useInline: true and provide the workflow under workflow.inline. The chart renders the workflow into a ConfigMap.

Option 2 — Kubernetes Secret​

Set workflow.useInline: false and create a Secret that contains the workflow:

kubectl create secret generic workflow \
  --from-file=workflow.yaml=./workflow.yaml

The chart mounts the Secret at workflow.file (default /data/workflow.yaml).

values.yaml
workflow:
  useInline: false
  secret: workflow
  file: /data/workflow.yaml

Connecting to Temporal​

Pass Temporal connection settings through the config map, which accepts any CLI flag name:

values.yaml
config:
  temporal-address: temporal:7233
  temporal-namespace: default
  log-level: info

For Temporal Cloud, use environment variables via the envvars list to keep credentials in a Secret:

values.yaml
config:
  temporal-address: your-namespace.tmprl.cloud:7233
  temporal-tls: "true"

envvars:
  - name: TEMPORAL_NAMESPACE
    valueFrom:
      secretKeyRef:
        name: temporal-config
        key: namespace
  - name: TEMPORAL_API_KEY
    valueFrom:
      secretKeyRef:
        name: temporal-config
        key: api-key

Environment variables for workflows​

Workflow $env variables are passed with the ZIGGY_ prefix by default. Add them to the envvars list:

values.yaml
envvars:
  - name: ZIGGY_API_BASE_URL
    value: https://api.example.com

Inside the workflow:

endpoint: ${ $env.API_BASE_URL }

Health and readiness probes​

The chart configures liveness and readiness probes automatically using the /health endpoint on port 3000.

No additional configuration is required for standard deployments.

Replicas and scaling​

Workers are stateless. You can run multiple replicas of the same worker against the same Temporal task queue. Temporal distributes executions across available workers.

values.yaml
replicaCount: 3

Horizontal Pod Autoscaling is available but disabled by default:

values.yaml
autoscaling:
  enabled: true
  minReplicas: 1
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80

Image configuration​

values.yaml
image:
  repository: ghcr.io/mrsimonemms/zigflow
  pullPolicy: IfNotPresent
  tag: "0.1.0"  # Defaults to chart version if not set

Full values reference​

See the Helm chart README for the complete values reference.

Common mistakes​

The pod starts but the workflow does not execute. Check that the task queue name (document.namespace) matches what your client uses. Also confirm the worker is connected to the correct Temporal namespace.

ImagePullBackOff for the chart image. Verify the version tag exists in ghcr.io/mrsimonemms/charts/zigflow.

Workflow not updating after a values change. The chart renders the inline workflow into a ConfigMap. After a helm upgrade, the pod must be restarted to pick up the new workflow.