Temporal

Overview

Temporal is an open-source (MIT) durable-execution platform — applications write workflows as ordinary code, and the Temporal server guarantees they run to completion, surviving process crashes, restarts, and long waits. This template deploys a single-process Temporal server exposing the gRPC frontend to your workloads, plus the Temporal Web UI, both internal-only, backed by a highly available PostgreSQL cluster by default. Database and schema setup run automatically at boot, including schema migrations on version upgrades.

Architecture

Temporal server — A single-replica standard workload running all four Temporal services (frontend, history, matching, worker) in one process; gRPC frontend on port 7233, internal-only. Stateless by design: all workflow state lives in PostgreSQL.
Temporal Web UI (optional, default on) — A standard workload serving the UI on port 8080, internal-only (the UI has no built-in authentication).
PostgreSQL (HA, default) — The postgres-highly-available template as a subchart: 3× Patroni PostgreSQL, 3× etcd, and a HAProxy leader-routing endpoint Temporal connects through.
PostgreSQL (dev/lightweight, optional) — The single-instance postgres template instead, for lighter non-HA deployments.

What Gets Created

Standard Temporal Server Workload — A single replica running all four Temporal services in one process, serving gRPC on port 7233. No volume set — all state lives in the database.
Standard Temporal UI Workload (optional) — The Temporal Web UI on port 8080.
Database Workloads — HA mode: a stateful Patroni PostgreSQL workload, a stateful etcd workload, and a standard HAProxy leader-routing workload. Single mode: one stateful PostgreSQL workload.
Volume Sets — The database subchart’s persistent volumes (10 GiB per replica by default). Temporal itself has none.
Secrets — The database credentials from the subchart.
Identity & Policy — A least-privilege policy granting the server identity reveal on exactly the database credentials secret. The UI workload has no identity — it mounts no secrets.
Cron Backup Workload (optional) — When database backups are enabled.

This template does not create a GVC. You must deploy it into an existing GVC.

Prerequisites

None for a default install. For optional database backups, you need a bucket and access setup for one of the supported providers — see Backing Up. Install the template using your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Choosing a Database Mode

Exactly one of the two database modes must be enabled — the chart enforces this at render and fails the install with a clear message otherwise.

	`postgresHA` (default)	`postgres`
What runs	3× Patroni PostgreSQL, 3× etcd, HAProxy leader endpoint	One single-replica PostgreSQL workload
Database failover	Automatic (Patroni leader election)	None
Footprint	8 replicas across 3 workloads (3× Patroni, 3× etcd, 2× HAProxy)	1 workload
Best for	Production	Development and lightweight installs

A fresh HA-mode install converges in roughly 4–6 minutes — the server waits for the database, then runs full schema setup before it starts listening. Single mode is ready in under 3 minutes.

Configuration

The default values.yaml for this template:

image: temporalio/auto-setup:1.29.7 # Temporal server + schema tools; boot runs schema setup, then the server

resources:
  cpu: 1000m
  memory: 2Gi
  minCpu: 500m
  minMemory: 1Gi

historyShards: 512 # PERMANENT after first install — cannot ever be changed for this cluster
namespaceRetention: 72h # how long closed workflow histories are kept in the default namespace

ui: # internal-only: the Temporal UI has no built-in authentication
  enabled: true
  image: temporalio/ui:2.52.1
  resources:
    cpu: 500m
    memory: 512Mi
    minCpu: 125m
    minMemory: 128Mi

internalAccess: # internal firewall scope for the gRPC frontend (:7233) and the UI (:8080)
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads: [] # used with workload-list, e.g. //gvc/GVC_NAME/workload/WORKLOAD_NAME

postgresHA: # default: highly available PostgreSQL
  enabled: true
  postgres:
    username: temporal
    password: change-me-temporal-db-password # change before installing
    database: temporal
  replicas: 3
  volumeset:
    capacity: 10 # initial capacity in GiB per replica (minimum is 10)
  backup:
    enabled: false # optional — see Backing Up
    mode: logical # logical or wal-g
    resources:
      cpu: 100m
      memory: 128Mi
    logical:
      image: ghcr.io/controlplane-com/backup-images/postgres-backup:17.1.0
      schedule: "0 2 * * *"
    walg:
      intervalSeconds: 21600
    provider: aws # options: aws, gcp, minio
    aws:
      bucket: temporal-pg-backup-bucket
      region: us-east-1
      cloudAccountName: my-s3-cloud-account
      policyName: temporal-pg-backup-policy
      prefix: postgres/backups
    gcp:
      bucket: temporal-pg-backup-bucket
      cloudAccountName: my-gcs-cloud-account
      prefix: postgres/backups
    minio:
      endpoint: http://my-minio-workload:9000
      bucket: temporal-pg-backup-bucket
      accessKey: my-minio-username
      secretKey: my-minio-password
      prefix: postgres/backups

postgres: # dev/lightweight: single-instance PostgreSQL (disable postgresHA first)
  enabled: false
  config:
    username: temporal
    password: change-me-temporal-db-password # change before installing
    database: temporal
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)
  backup:
    enabled: false # optional — see Backing Up
    image: ghcr.io/controlplane-com/backup-images/postgres-backup:18.1.0
    schedule: "0 2 * * *"
    resources:
      cpu: 100m
      memory: 128Mi
    provider: aws # options: aws, gcp, minio
    aws:
      bucket: temporal-pg-backup-bucket
      region: us-east-1
      cloudAccountName: my-s3-cloud-account
      policyName: temporal-pg-backup-policy
      prefix: postgres/backups
    gcp:
      bucket: temporal-pg-backup-bucket
      cloudAccountName: my-gcs-cloud-account
      prefix: postgres/backups
    minio:
      endpoint: http://my-minio-workload:9000
      bucket: temporal-pg-backup-bucket
      accessKey: my-minio-username
      secretKey: my-minio-password
      prefix: postgres/backups

Temporal Server

image — The upstream auto-setup image: at boot it creates the temporal and temporal_visibility databases, applies or upgrades the schema, registers the default namespace, then starts the server — all idempotently, so restarts and upgrades are safe. Image bumps apply new schema migrations automatically at boot.
resources — CPU and memory for the server container.
historyShards — The cluster’s history shard count. Permanent: fixed at the cluster’s first boot and can never be changed — the server refuses a different value later. Size it before installing; 512 suits most deployments.
namespaceRetention — How long closed workflow histories stay queryable in the default namespace (e.g. 72h, 96h).

Web UI

ui.enabled — Set false to remove the UI workload.
ui.image / ui.resources — The Temporal UI container image and its CPU/memory.

The Temporal Web UI has no built-in authentication and is internal-only by design — this template has no knob to expose it publicly. To offer browser access from outside the internal scope, put your own authenticating proxy in front of it.

Access

Both workloads are internal-only — there is no public-access option in this template. The gRPC frontend serves workers and clients running as workloads in your org. internalAccess.type sets the internal firewall scope for both the gRPC frontend (:7233) and the UI (:8080):

Type	Description
`none`	No internal access.
`same-gvc`	Allow access from all workloads in the same GVC (default).
`same-org`	Allow access from all workloads in the same organization.
`workload-list`	Allow access only from workloads listed in `internalAccess.workloads`.

Database

Enable exactly one of postgresHA (production, default) or postgres (dev/lightweight) — see Choosing a Database Mode. In both modes, change the database password before installing (postgresHA.postgres.password / postgres.config.password). Temporal is wired to the active database automatically — the HAProxy leader endpoint in HA mode, or the single instance directly in dev mode.

Connecting

What	Value
gRPC frontend (workers/clients)	`{release}-temporal.{gvc}.cpln.local:7233`
Namespace	`default`
Web UI (internal)	`http://{release}-temporal-ui.{gvc}.cpln.local:8080`
PostgreSQL (internal, HA mode)	`{release}-postgres-ha-proxy.{gvc}.cpln.local:5432`, credentials in the `{release}-postgres-config` secret
PostgreSQL (internal, single mode)	`{release}-postgres.{gvc}.cpln.local:5432`, credentials in the `{release}-pg-config` secret

Always use the full .cpln.local FQDN in worker and client connection config — short workload names do not resolve.

Running Workers

Workers run as their own workloads (in the internal access scope) and connect to the gRPC frontend. A minimal Python worker:

import asyncio
from temporalio.client import Client
from temporalio.worker import Worker

async def main():
    client = await Client.connect(
        "my-release-temporal.my-gvc.cpln.local:7233",  # full FQDN required
        namespace="default",
    )
    worker = Worker(
        client,
        task_queue="my-task-queue",
        workflows=[MyWorkflow],
        activities=[my_activity],
    )
    await worker.run()

if __name__ == "__main__":  # required — see note below
    asyncio.run(main())

Python workers must guard their entrypoint with if __name__ == "__main__": — the Temporal Python SDK’s workflow sandbox re-imports the worker module, and an unguarded module-level main() crashes the worker.

Backing Up

Database backups are optional and disabled by default. They cover the Temporal databases — all workflow histories, task queues, timers, and visibility data. Enable them with postgresHA.backup.enabled or postgres.backup.enabled (matching your database mode), and complete the storage setup for your provider before installing. The values below are shown under backup.* — set them within the enabled database block.

AWS S3
Google Cloud Storage
S3-compatible (MinIO, R2, Wasabi)

Create a bucket

Create an S3 bucket. Set backup.aws.bucket and backup.aws.region to match.

Set up a Cloud Account

If you do not have one, create a Cloud Account for your AWS account. Set backup.aws.cloudAccountName to its name.

Create a bucket-scoped IAM policy

Create an AWS IAM policy with the JSON below (replace YOUR_BUCKET), then set backup.aws.policyName to the policy’s name:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "s3:ListBucket",
      "s3:GetBucketLocation",
      "s3:GetObject",
      "s3:PutObject",
      "s3:DeleteObject",
      "s3:AbortMultipartUpload"
    ],
    "Resource": [
      "arn:aws:s3:::YOUR_BUCKET",
      "arn:aws:s3:::YOUR_BUCKET/*"
    ]
  }]
}

Create a bucket

Create a GCS bucket. Set backup.gcp.bucket to its name.

Set up a Cloud Account

If you do not have one, create a Cloud Account for your GCP project. Set backup.gcp.cloudAccountName to its name — the backup identity is granted access to the bucket keylessly (no stored credentials).

Create a bucket

Create your bucket on the server. Set backup.minio.bucket to its name.

Set the endpoint

Set backup.minio.endpoint to the S3 API address including port. For the minio marketplace template deployed in the same GVC, this is http://WORKLOAD_NAME:9000.

Set credentials

Set backup.minio.accessKey and backup.minio.secretKey to credentials with access to the bucket.

In HA mode, backup.mode selects logical (scheduled pg_dump via a cron workload) or wal-g (continuous WAL archiving). The single-instance mode takes scheduled logical dumps.

Important Notes

Change the database password (postgresHA.postgres.password / postgres.config.password) before installing.
historyShards is permanent — the shard count is fixed at the cluster’s first boot and can never be changed; the server refuses a different value later. Size it before installing (512 suits most deployments).
Never expose the Web UI publicly — it has no built-in authentication. To offer browser access from outside the internal scope, put your own authenticating proxy in front of it.
Temporal connects and runs schema setup as the database superuser provisioned by the PostgreSQL subchart — it needs CREATE DATABASE and DDL rights at every version upgrade.
Upgrades restart the single server replica and apply schema migrations automatically at boot — expect a brief frontend outage per Helm upgrade; in-flight workflows resume where they left off once the server is back.
Keep the server at one replica — manually scaling the workload will not form a working cluster (required inter-service ports are not declared and the database connection limit would be exceeded).
Uninstall deletes the database volume sets — all workflow histories and state. Enable backups if the data matters.

External References

Temporal Documentation

Official Temporal documentation

Self-Hosted Guide

Running and operating a self-hosted Temporal service

SDKs

Writing workflows, activities, and workers in every supported language

Namespaces

Namespaces and workflow-history retention

Web UI Reference

The Temporal Web UI reference

Temporal Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

Architecture

What Gets Created

Prerequisites

UI

CLI

Terraform

Pulumi

Choosing a Database Mode

Configuration

Temporal Server

Web UI

Access

Database

Connecting

Running Workers

Backing Up

Important Notes

External References

Temporal Documentation

Self-Hosted Guide

SDKs

Namespaces

Web UI Reference

Temporal Template

​Overview

​Architecture

​What Gets Created

​Prerequisites

UI

CLI

Terraform

Pulumi

​Choosing a Database Mode

​Configuration

​Temporal Server

​Web UI

​Access

​Database

​Connecting

​Running Workers

​Backing Up

​Important Notes

​External References

Temporal Documentation

Self-Hosted Guide

SDKs

Namespaces

Web UI Reference

Temporal Template

Overview

Architecture

What Gets Created

Prerequisites

Choosing a Database Mode

Configuration

Temporal Server

Web UI

Access

Database

Connecting

Running Workers

Backing Up

Important Notes

External References