Skip to main content

Configure Temporal Proxy

View Markdown

Temporal Proxy reads one YAML configuration file at startup. Begin with a gateway listener, routing policy, and one or more upstreams. Add inbound access controls, upstream TLS and credentials, and payload encryption according to the deployment boundary you planned.

This page shows how the configuration fits together. Follow the linked task pages for the complete behavior and options of each section.

Assemble the configuration​

The following configuration exposes a plaintext local endpoint and forwards namespaced and Namespace-less calls to a local Temporal Service:

hostPort: 127.0.0.1:7233

routing:
  default: local
  system: local

upstreams:
  - name: local
    hostPort: 127.0.0.1:8233

Build from that baseline in this order:

  1. Define the gateway address with hostPort and, when callers cross an untrusted network, configure top-level tls.
  2. Define each destination in upstreams, then select destinations with routing.
  3. Add Namespace translation under an upstream's namespaces block when local and remote names differ.
  4. Add an upstream tls block and credentials when the destination requires them.
  5. Restrict inbound gRPC services with allowedServices and add auth when the gateway must authenticate or authorize callers.
  6. Add encryption when the proxy must encrypt supported Payload fields before forwarding them.

The configuration areas map to separate operating jobs:

JobConfiguration sectionsGuide
Select destinations and map Namespace namesrouting, upstreams[].hostPort, upstreams[].namespacesRoute requests and translate Namespaces
Protect the gateway and upstream connectionstls, allowedServices, auth, upstreams[].tls, upstreams[].credentials, extensionServersSecure connections and authorize requests
Encrypt Payloadsencryption, optional KMS extensionServersEncrypt Payloads
Rotate and retire encryption keysencryption.default, encryption.overrides, decryptURIsManage encryption keys
Mount configuration and secrets with HelmChart config, env, envFrom, and Secret referencesDeploy Temporal Proxy to Kubernetes

See the Temporal Proxy reference for the top-level key map and the source of truth for the complete schema.

Supply environment-specific values​

Configuration string values support environment variable expansion in either ${VAR} or $VAR form. Keep secrets out of the YAML file and resolve them from the process environment:

upstreams:
  - name: cloud
    hostPort: ${TEMPORAL_NAMESPACE}.${TEMPORAL_ACCOUNT}.tmprl.cloud:7233
    tls: {}
    credentials:
      static:
        apiKey: ${TEMPORAL_API_KEY}

Undefined environment variables expand to an empty string, so verify that every required variable is present before starting the proxy. On Kubernetes, use the chart's Secret integration instead of putting a credential in a ConfigMap. See Supply credentials from a Secret.

An upstream hostPort and tls.serverName can also use Go templates that the proxy resolves for each request. For example, the Temporal Cloud configuration can derive the endpoint from the translated Namespace:

upstreams:
  - name: cloud
    hostPort: '{{ .RemoteNamespace }}.tmprl.cloud:7233'
    tls: {}

Available template values and routing order are documented in Route requests and translate Namespaces.

Start with the configuration​

Pass the configuration path to proxy serve:

proxy serve --config config.yaml

The --config flag also reads the PROXY_CONFIG environment variable. The proxy validates references and supported values while it starts and exits when it finds an invalid configuration. It reads configuration only at startup, so restart every proxy instance after a change.

Before directing application traffic to a new configuration:

  1. Start the proxy in an evaluation environment and resolve every startup error.
  2. Check the gateway health service.
  3. Connect a Client through the gateway and call both a Namespace-scoped operation and a Namespace-less operation.
  4. Confirm the selected upstream, authentication result, and any encryption operations in logs and metrics.
  5. Test direct upstream access when your design intends to prevent bypass.

See Operate and troubleshoot Temporal Proxy for health checks, diagnostics, metrics, and common failure modes.

Continue configuring​