Temporal (temporal)

Durable workflow engine running the long agent tasks and pipelines of the Navin Control Plane. One process or separate frontend, history, matching and worker roles on PostgreSQL.

Generated from catalog/services/temporal.yaml: do not edit by hand.

Summary

Version	1.27.4
Use	install and configure
Layer	infrastructure (shown apart)
Category	Data platforms
Installation methods	binary, podman
External connection	no
Sandbox only	no

Licence

SPDX identifier	MIT
Licence policy	core licence (MIT or Apache-2.0)
Licence exception	-
Platform component	temporal

Packages and artifacts

A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.

Kind	Package	Version	Licence	Details
container image	docker.io/temporalio/server	1.27.4	MIT	image key server, used by frontend, history, matching, worker, digest sha256:4cf4366ff5f127558161e9d071892519a87681a8df494f03fb228f585a75a782
container image	docker.io/temporalio/admin-tools	1.27.2-tctl-1.18.2-cli-1.3.0	MIT	image key admin-tools, used by schema, digest sha256:b5ae59dae6ea00c22fc2bdf04a2cfaf59e3e036b8b09ca777f99e2c871396fa2
binary archive	temporal_1.27.4_linux_amd64.tar.gz	1.27.4	MIT	https://github.com/temporalio/temporal/releases/download/v1.27.4/temporal_1.27.4_linux_amd64.tar.gz, x86_64, checksum sha256

Images are pinned by tag in the descriptor, and by digest when the descriptor declares one (the offline bundle then refuses a pulled image that does not carry it); the digest is recorded in the mirror of the Manager when the offline bundle is imported, and every pull or load is checked against it.

Supported systems and architectures

Method	Operating systems	Architectures
binary	RHEL family (dnf), Debian family (apt), Arch Linux (pacman)	x86_64 (architecture of the artifacts of the descriptor)
podman	RHEL family (dnf), Debian family (apt), Arch Linux (pacman)	x86_64, aarch64 (not restricted by the descriptor)

Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.

Prerequisites

Host

• at least 2048 MB of memory (blocking, memory).

Network and ports

Component	Port name	Port	Opened in the host firewall
frontend	grpc	7233/tcp	yes
frontend	http	7243/tcp	yes
frontend	metrics	9090/tcp	yes
frontend	membership	6933/tcp (mode cluster)	yes
history	grpc	7234/tcp	yes
history	membership	6934/tcp	yes
history	metrics	9091/tcp	yes
matching	grpc	7235/tcp	yes
matching	membership	6935/tcp	yes
matching	metrics	9092/tcp	yes
worker	grpc	7239/tcp	yes
worker	membership	6939/tcp	yes
worker	metrics	9096/tcp	yes

Services and connections needed

• db: postgresql.
• visibility: postgresql.

Details and resolution: see Dependencies.

Installation methods and modes

Method	Default	What the method uses
binary	yes	the binary archives of the descriptor, unpacked under the service directory
podman	-	the container images of the descriptor, run by Podman under systemd

Components

Component	Kind	Installation methods	Ports
Schema setup (schema)	one shot	binary, podman	-
Frontend (frontend)	master	binary, podman	7233/tcp, 7243/tcp, 9090/tcp, 6933/tcp (mode cluster)
History (history)	master	binary, podman	7234/tcp, 6934/tcp, 9091/tcp
Matching (matching)	master	binary, podman	7235/tcp, 6935/tcp, 9092/tcp
Internal worker (worker)	worker	binary, podman	7239/tcp, 6939/tcp, 9096/tcp

Single process (standalone) (default)

One process runs frontend, history, matching and worker.

What the mode deploys:

Component	Placement
schema	min 1, max 1
frontend	min 1, max 1
history	not used
matching	not used
worker	not used

Separate roles (cluster)

Frontend, history, matching and worker scale on their own hosts.

What the mode deploys:

Component	Placement
schema	min 1, max 1
frontend	min 2, recommended 2
history	min 2, recommended 3
matching	min 2, recommended 2
worker	min 1, recommended 2

Install this service

The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.

1. Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.

2. Choose the service. On the Service step, select Temporal. The card shows the licence MIT and the dependencies the installation needs. Pick the Method among binary, podman (default binary).

3. Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode: standalone (default), cluster. Each mode deploys the components listed in Installation methods and modes. With several components, place each one on its hosts in Component placement (Suggest placement proposes a placement that respects the cardinalities).

4. Bind the dependencies. On the Bindings step, choose for each dependency (db, visibility) Install with the platform or Use an existing connection; an optional dependency can stay on No binding.

5. Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.

6. Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.

7. Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services.

High availability

Cluster	native (native)
High availability	native (native)
Failover	native (native)
Replication	shared store (shared-store)
Quorum	gossip (gossip)
Discovery	database (database)
Entry point	load balancer (load-balancer)
Official documentation	https://docs.temporal.io/self-hosted-guide/deployment
Peer TLS parameter	tls_enabled
Cluster status command	cluster_health

Prerequisites

Prerequisite	Must be highly available	Modes	Description
db	yes	modes of level ha or cluster	Highly available PostgreSQL (persistence).
visibility	yes	modes of level ha or cluster	Highly available PostgreSQL (visibility).

Topology per mode

Modes	Highest catalog level	Distribution	Quorum component	Fault domains	Description
standalone	standalone (standalone)	single (single)	-	1	One process running frontend, history, matching and worker.
cluster	cluster (cluster)	active-active (active-active)	-	2	2 or more instances of each role; the history shards move between the history instances.

Notes

• Temporal is highly available only if its persistence is: the history, matching and frontend instances hold no durable state of their own.

Configuration parameters

Network

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
Frontend gRPC port (frontend_port)	port	7233	-	no	no	no	gRPC port of the frontend service (SDK clients and workers).
HTTP API port (http_port)	port	7243	-	no	no	no	HTTP API of the frontend (EAI_TEMPORAL_URL of the Navin Control Plane).
History gRPC port (history_port)	port	7234	-	no	no	no	gRPC port of the history service.
Matching gRPC port (matching_port)	port	7235	-	no	no	no	gRPC port of the matching service.
Worker gRPC port (worker_port)	port	7239	-	no	no	no	gRPC port of the internal worker service.
Membership base port (membership_base_port)	port	6933	-	no	no	no	Ringpop ports: frontend base, history base+1, matching base+2, worker base+6.
Metrics port (metrics_port)	port	9090	-	no	no	no	Prometheus endpoint of every Temporal process (base port, plus the role offset in cluster mode).

Cluster

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
History shards (history_shards)	int	512	min 1, max 16384	no	no	no	Fixed at creation of the cluster, cannot be changed later.
Default namespace (default_namespace)	string	navin	^[a-z][a-z0-9-]{1,60}$	no	no	no	Namespace given to the clients (EAI_TEMPORAL_NAMESPACE).

Security

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
TLS (tls_enabled)	bool	false	-	no	no	yes	Serve the frontend (gRPC and HTTP API) over TLS and secure the traffic between the roles with mutual TLS, with the certificates issued by the manager CA.

Dependencies

For each active dependency the Manager takes the first of: the binding chosen in the wizard; a service of the same installation that provides it; a service already installed in the cluster; the only connection of the expected type. Otherwise an optional dependency stays unbound, and a required one is added to the installation in its default mode (the column below names the catalog service added).

Binding	Provided by	Connection type	Endpoint	Optional	When nothing is bound	Description
db	postgresql	postgresql	-	no	postgresql is added to the installation	Main persistence of Temporal (PostgreSQL 12 or later).
visibility	postgresql	postgresql	-	no	postgresql is added to the installation	Visibility store of Temporal (separate PostgreSQL database).

Endpoints

Endpoint	Scheme	Component	Port	Path	TLS parameter	Binding parameters	Binding secrets	Provisioning command
frontend	grpc	frontend	7233 (frontend_port)	-	tls_enabled	tls	-	-
http	http	frontend	7243 (http_port)	-	tls_enabled	tls	-	-

Client configuration files

Files rendered for the client configuration download:

• temporal.env (client.env.j2)

Commands

Command	Component	Target	Description
Set up the schema (setup_schema)	schema	first host	Creates or upgrades the main and visibility schemas (idempotent).
Frontend health (cluster_health)	frontend	every host	Checks the HTTP API of every frontend.

Health checks

Liveness (per instance)

Component	Check	Details
frontend	TCP {{ host.ip or '127.0.0.1' }}:{{ config.frontend_port }}	60 retries
history	TCP {{ host.ip or '127.0.0.1' }}:{{ config.history_port }}	60 retries
matching	TCP {{ host.ip or '127.0.0.1' }}:{{ config.matching_port }}	60 retries
worker	TCP {{ host.ip or '127.0.0.1' }}:{{ config.worker_port }}	60 retries

Readiness (service check)

Check	Details
TCP {{ host.ip or '127.0.0.1' }}:{{ config.frontend_port }}	-

Preflight checks

Check	Type	Meaning	Severity	Components
memory	memory_mb {"min": 2048}	at least 2048 MB of memory	blocking	every component
frontend_port_free	port_free {"param": "frontend_port"}	port 7233 free on the host	blocking	frontend

Uninstall

Paths removed when the data is purged: {{ paths.data }}, {{ paths.log }}.

Upstream documentation

• Homepage: https://temporal.io
• Source: https://github.com/temporalio/temporal
• High availability: https://docs.temporal.io/self-hosted-guide/deployment