Configuration

Static YAML configuration recognised by temporal-server. Examples live in config/. The Go types are in common/config/config.go; when in doubt that file is authoritative.

Top-level structure

log: ... # Logger config
persistence: ... # Primary + visibility persistence
global: ... # Cluster-wide concerns: TLS, metrics, tracer, auth
clusterMetadata: ... # Cluster name + multi-cluster topology
dcRedirectionPolicy: ... # Active/standby request routing
services: ... # Per-service listeners
archival: ... # Cluster-level archival defaults
namespaceDefaults: ... # Per-namespace defaults at creation
publicClient: ... # SDK config used by Internal Worker
dynamicConfigClient: ... # Where to read dynamic config from

Selected blocks

log

log:
  stdout: true
  level: info
  outputFile: ''
  format: json

persistence

persistence:
  numHistoryShards: 4
  defaultStore: cass-default
  visibilityStore: es-visibility
  datastores:
    cass-default:
      cassandra:
        hosts: '127.0.0.1'
        keyspace: temporal
    es-visibility:
      elasticsearch:
        version: v7
        url: { scheme: http, host: 127.0.0.1, port: 9200 }

numHistoryShards is fixed at cluster creation. The supported datastore types are cassandra:, sql: (MySQL / PG / SQLite), and elasticsearch: (visibility only).

services

One block per service the binary may host:

services:
  frontend:
    rpc:
      grpcPort: 7233
      httpPort: 7243
      bindOnLocalHost: true
  history:
    rpc: { grpcPort: 7234, ... }
  matching:
    rpc: { grpcPort: 7235, ... }
  worker:
    rpc: { grpcPort: 7239, ... }

Each service has its own metrics, pprof, tls sub-blocks.

global

global:
  membership:
    name: temporal
    maxJoinDuration: 30s
    broadcastAddress: '127.0.0.1'
  tls:
    internode: { ... } # mTLS between services
    frontend: { ... } # public TLS
  authorization:
    jwtKeyProvider:
      keySourceURIs: ['...']
    permissionsClaimName: permissions
    authorizer: default
    claimMapper: default
  metrics:
    prometheus: { ... }
    tags:
      env: production
  tracerProvider:
    serviceName: temporal-frontend
    exporter: otlp
    endpoint: otel-collector:4317

clusterMetadata

clusterMetadata:
  enableGlobalNamespace: true
  failoverVersionIncrement: 10
  masterClusterName: clusterA
  currentClusterName: clusterB
  clusterInformation:
    clusterA: { enabled: true, initialFailoverVersion: 1, rpcAddress: '...' }
    clusterB: { enabled: true, initialFailoverVersion: 2, rpcAddress: '...' }

archival

archival:
  history:
    state: enabled
    enableRead: true
    provider:
      filestore: { fileMode: '0666', dirMode: '0766' }
      s3store: { ... }
  visibility:
    state: enabled

Environment variables

A handful of legacy env vars are still honoured (see cmd/server/main.go and common/config/):

• TEMPORAL_HOME (alias --root).
• TEMPORAL_CONFIG_DIR (alias --config).
• TEMPORAL_ENVIRONMENT (alias --env).
• TEMPORAL_AVAILABILITY_ZONE (alias --zone).
• TEMPORAL_ALLOW_NO_AUTH (alias --allow-no-auth).
• TEMPORAL_CONFIG_FILE (alias --config-file) — preferred form.

The --root / --config / --env flags are deprecated; new deployments should use --config-file.

Validating a config file

temporal-server --config-file my-cluster.yaml render-config

The render-config subcommand prints the merged config (after templating) so you can verify substitutions.

temporal-server validate-dynamic-config my-dynamic.yaml

Validates a dynamic-config YAML against the known set of declared keys.

Where to read more

• Deployment
• Systems → Dynamic config
• common/config/config.go