Skip to main content

Namespaces

This guide provides a comprehensive overview of Namespaces.

A Namespace is a unit of isolation within the Temporal Platform.

A single Namespace is still multi-tenant. You can use Namespaces to match the development lifecycle; for example, having separate dev and prod Namespaces. Or you could use them to ensure Workflow Executions between different teams never communicate; such as ensuring that the teamA Namespace never impacts the teamB Namespace.

  • If no other Namespace is specified, the Temporal Cluster uses the Namespace "default" for all Temporal SDKs and tctl.
    • If you are deploying through Docker Compose or using the auto-setup image in a custom Docker Compose application, the Namespace "default" is created, through the auto-setup script.
    • If you are deploying through the Temporal Helm charts, you can create the "default" Namespace by using tctl; for example, tctl namespace default. We recommend using the default Namespace if you aren’t using multiple Namespaces.
  • Case Insensitive: Because of DNS, Namespaces are case insensitive on the network and routing side. We recommend using lowercase for namespace names to avoid potential issues.
  • Membership: Task Queue names and Workflow Ids must all correspond to a specific Namespace. For example, when a Workflow Execution is spawned, it does so within a specific Namespace.
  • Uniqueness: Temporal guarantees a unique Workflow Id within a Namespace. Workflow Executions may have the same Workflow Id if they are in different Namespaces.
  • Namespace Configuration: Various configuration options like the retention period and the Archival destination are configured per Namespace through a special CRUD API or through tctl.

Global Namespace​

A Global Namespace is a Namespace that exists across Clusters when Multi-Cluster Replication is set up.

The Global Namespace feature enables Workflow Executions to progress through another Cluster in the event of a failover.

A Global Namespace may be replicated to any number of Clusters, but is active in only one Cluster at any given time.

For a failover to be successful, Worker Processes must be polling for Tasks for the Global Namespace on all Clusters.

A Global Namespace has a failover version. Because a failover can be triggered from any Cluster, the failover version prevents certain conflicts from occurring if a failover is mistakenly triggered simultaneously on two Clusters.

Only the active Cluster dispatches Tasks; however, certain conflicts are possible. Unlike regular Namespaces, which provide at-most-once semantics for an Activity Execution, Global Namespaces can support only at-least-once semantics (see Conflict resolution). Worker Processes on the standby Clusters are idle until a failover occurs and their Cluster becomes active.

Temporal Application API calls made to a non-active Cluster are rejected with a NamespaceNotActiveError which contains the name of the current active Cluster. It is the responsibility of the Temporal Application to call the Cluster that is currently active.