Temporal Service configuration
This page discusses the following:
What is Temporal Service configuration?
Temporal Service configuration is the setup and configuration details of your self-hosted Temporal Service, defined using YAML. You must define your Temporal Service configuration when setting up your self-hosted Temporal Service.
For details on using Temporal Cloud, see Temporal Cloud documentation.
Temporal Service configuration is composed of two types of configuration: Static configuration and Dynamic configuration.
Static configuration
Static configuration contains details of how the Temporal Service should be set up. The static configuration is read just once and used to configure service nodes at startup. Depending on how you want to deploy your self-hosted Temporal Service, your static configuration must contain details for setting up:
- Temporal Services—Frontend, History, Matching, Worker
- Membership ports for the Temporal Services
- Persistence (including History Shard count), Visibility, Archival store setups.
- TLS, authentication, authorization
- Server log level
- Metrics
- Temporal Service metadata
- Dynamic config Client
Static configuration values cannot be changed at runtime. Some values, such as the Metrics configuration or Server log level can be changed in the static configuration but require restarting the Temporal Service for the changes to take effect.
For details on static configuration keys, see Temporal Service configuration reference.
For static configuration examples, see https://github.com/temporalio/temporal/tree/master/config.
Dynamic configuration
Dynamic configuration contains configuration keys that you can update in your Temporal Service setup without having to restart the server processes.
All dynamic configuration keys provided by Temporal have default values that are used by the Temporal Service. You can override the default values by setting different values for the keys in a YAML file and setting the dynamic configuration client to poll this file for updates. Setting dynamic configuration for your Temporal Service is optional.
Setting overrides for some configuration keys updates the Temporal Service configuration immediately. However, for configuration fields that are checked at startup (such as thread pool size), you must restart the server for the changes to take effect.
Use dynamic configuration keys to fine-tune your self-deployed Temporal Service setup.
For details on dynamic configuration keys, see Dynamic configuration reference.
For dynamic configuration examples, see https://github.com/temporalio/temporal/tree/master/config/dynamicconfig.
What is Temporal Service security configuration?
Secure your Temporal Service (self-hosted and Temporal Cloud) by encrypting your network communication and setting authentication and authorization protocols for API calls.
For details on setting up your Temporal Service security, see Temporal Platform security features.
mTLS encryption
Temporal supports Mutual Transport Layer Security (mTLS) to encrypt network traffic between services within a Temporal Service, or between application processes and a Temporal Service.
On the self-hosted Temporal Service, configure mTLS in the tls section of the Temporal Service configuration.
mTLS configuration is a static configuration property.
You can then use either the WithConfig or WithConfigLoader server option to start your Temporal Service with this configuration.
The mTLS configuration includes two sections that serve to separate communication within a Temporal Service and client calls made from your application to the Temporal Service.
internode: configuration for encrypting communication between nodes within the Temporal Service.frontend: configuration for encrypting the public endpoints of the Frontend Service.
Setting mTLS for internode and frontend separately lets you use different certificates and settings to encrypt each section of traffic.
Using certificates for Client connections
Use CA certificates to authenticate client connections to your Temporal Service.
On Temporal Cloud, you can set your CA certificates in your Temporal Cloud settings and use the end-entity certificates in your client calls.
On the self-hosted Temporal Service, you can restrict access to Temporal Service endpoints by using the clientCAFiles or clientCAData property and the requireClientAuth property in your Temporal Service configuration.
These properties can be specified in both the internode and frontend sections of the mTLS configuration.
For details, see the tls configuration reference.
Server name specification
On the self-hosted Temporal Service, you can specify serverName in the client section of your mTLS configuration to prevent spoofing and MITM attacks.
Entering a value for serverName enables established connections to authenticate the endpoint.
This ensures that the server certificate presented to any connected client has the specified server name in its CN property.
This measure can be used for internode and frontend endpoints.
For more information on mTLS configuration, see tls configuration reference.
Authentication and authorization
Temporal provides authentication interfaces that can be set to restrict access to your data. These protocols address three areas: servers, client connections, and users.
Temporal offers two plugin interfaces for authentication and authorization of API calls.
The logic of both plugins can be customized to fit a variety of use cases. When plugins are provided, the Frontend Service invokes their implementation before running the requested operation.
What is Temporal Service observability?
You can monitor and observe performance with metrics emitted by your self-hosted Temporal Service or by Temporal Cloud.
Temporal emits metrics by default in a format that is supported by Prometheus. Any metrics software that supports the same format can be used. Currently, we test with the following Prometheus and Grafana versions:
- Prometheus >= v2.0
- Grafana >= v2.5
Temporal Cloud emits metrics through a Prometheus HTTP API endpoint, which can be directly used as a Prometheus data source in Grafana or to query and export Cloud metrics to any observability platform.
For details on Cloud metrics and setup, see the following:
On the self-hosted Temporal Service, expose Prometheus endpoints in your Temporal Service configuration and configure Prometheus to scrape metrics from the endpoints. You can then set up your observability platform (such as Grafana) to use Prometheus as a data source.
For details on self-hosted Temporal Service metrics and setup, see the following: