Namespaces and multi-cluster

Active contributors: wxing1292, samar, david

Purpose

A namespace is the administrative isolation boundary inside a Temporal cluster: workflows live inside a namespace, retention and archival are configured per namespace, and authorization scopes to a namespace. Multi-cluster (XDC) extends this model so a namespace can be replicated across clusters and failed over.

Namespaces

Source map:

Surface	File / package
Frontend handler	service/frontend/namespace_handler.go
Namespace cache	common/namespace/registry.go
Persistence	common/persistence/metadata_manager.go
Async deletion workflow	service/worker/deletenamespace/

A namespace record carries:

• Identity (name, ID, description).
• Retention period — workflows older than this are deleted.
• Archival configuration.
• Active cluster name (for multi-cluster).
• Replication configuration (which clusters replicate this namespace).
• Custom search-attribute mapping.

The namespace cache is one of the most important per-process structures. Every gRPC handler resolves namespace name → ID via this cache; misses go to the metadata manager. The cache refreshes via a long-polling subscription against the metadata table.

Multi-cluster

The setup:

graph LR
    A[Cluster A<br/>active for ns-1] -->|gRPC stream| B[Cluster B<br/>standby for ns-1]
    A -->|gRPC stream| C[Cluster C<br/>standby for ns-1]
    B -->|verifies events| Metadata[shared cluster_metadata]
    C -->|verifies events| Metadata

Implementation lives across:

• service/history/replication/ — in-shard generation + ingestion.
• service/history/ndc/ — N-DC conflict resolution.
• service/worker/replicator/ — system workflow that pulls events from peer clusters.
• common/cluster/ — cluster metadata cache.
• tests/xdc/ — functional tests with multi-cluster setups.

A complete walk-through is on the Replication / XDC page.

Failover

Failing over a namespace from cluster A to cluster B:

1. Operator calls OperatorService.UpdateNamespace with the new active cluster.
2. Namespace metadata is updated; this row is itself replicated to all clusters.
3. The namespace cache on every host picks up the change.
4. History services switch their executor pairs: cluster B promotes its standby executors to active; cluster A demotes the active to standby.
5. In-flight tasks are reconciled by the N-DC machinery if the version histories diverged.

Entry points for modification

• Adding a namespace setting: add the field to the NamespaceConfig proto in temporalio/api, regen, plumb through service/frontend/namespace_handler.go and the namespace cache.
• Adding a per-namespace tunable: add a dynamic-config setting with namespace scope (see Dynamic config).
• Cluster topology changes: edit cluster_metadata rows via the OperatorService.

Related pages

• Replication / XDC
• Frontend service — namespace cache + handler.
• Internal Worker — async deletion + replication workflows.