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.

Usage​

Namespaces are created on the Temporal Cluster, and provide a range of controls to achieve isolation on Workflow Executions.

  • Namespaces are a mechanism for resource isolation. Heavy traffic from one Namespace will not impact other Namespaces running on the same Cluster. For example, you can use Namespaces to match the development lifecycle by having separate dev and prod Namespaces.
  • If no other Namespace is specified, the Temporal Cluster uses the Namespace "default" for all Temporal SDKs and tctl. See the Registration section for details.
  • Namespaces created on self-hosted Temporal Clusters are case-sensitive. For example, foo and Foo are two different Namespaces. On Temporal Cloud, Namespaces are case-insensitive, and we recommend using lowercase for Namespace names to avoid potential issues.
  • Membership: Task Queue 🔗
    Link preview
    What is a Task Queue?
    A Task Queue is a first-in, first-out queue that a Worker Process polls for Tasks.
    term explanation
    names and Workflow Ids 🔗
    Link preview
    What is a Workflow Id?
    A Workflow Id is a customizable, application-level identifier for a Workflow Execution that is unique to an Open Workflow Execution within a Namespace.
    term explanation
    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 🔗
    Link preview
    What is a Retention Period?
    A Retention Period is the amount of time a Workflow Execution Event History remains in the Cluster's persistence store.
    term explanation
    and the Archival 🔗
    Link preview
    What is Archival?
    Archival is a feature that automatically backs up Event Histories from Temporal Cluster persistence to a custom blob store after the Closed Workflow Execution retention period is reached.
    term explanation
    destination are configured per Namespace through a special CRUD API or through tctl.

Registration​

Registering a Namespace creates the Namespace on the Temporal Cluster. When you register your Namespace, you must also set the Retention Period 🔗

Link preview
What is a Retention Period?
A Retention Period is the amount of time a Workflow Execution Event History remains in the Cluster's persistence store.
term explanation
for the Namespace.

On Temporal Cloud, use the Temporal Cloud UI 🔗

Link preview
How to manage Namespaces in Temporal Cloud
You can create and manage Namespaces from your Temporal Cloud UI.
introduction temporal cloud namespaces
or tcld commands to create and manage Namespaces.

On self-hosted Temporal Cluster, you can register your Namespaces using tctl (recommended) or programmatically using APIs. Note that these APIs and tctl commands will not work with Temporal Cloud.

All SDKs require a Namespace on the Temporal Cluster (or Temporal Cloud) for their Client calls. If not set using Client options, the Workflow Client API looks for the default Namespace. If there is no default Namespace registered with your Temporal Cluster (or Temporal Cloud), all calls will throw errors. You must register your Namespace with the Temporal Cluster (or Temporal Cloud) before setting it in your Client.

On self-hosted Temporal Clusters, you can register your Namespaces in the following ways:

  • In your Cluster setup, create your Namespaces, including the default, in your setup script. For example:

    • If 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 deploying through the Temporal Helm charts, you can create the "default" Namespace by using tctl; for example, tctl --namespace default namespace register.

  • Use the tctl namespace register command with the --retention modfiier to register your Namespaces, one at a time, and set the Retention Period on each.

  • In your Client program, register your Namespace using RegisterNamespaceRequest API available in all the SDKs.

Note that registering a Namespace takes up to 15 seconds to complete. Ensure that you are waiting for this process to complete before making calls to the Namespace.

Manage Namespaces​

Use a custom Authorizer 🔗

Link preview
What is an Authorizer Plugin?
undefined
term
on your Frontend Service in the Temporal Cluster to set restrictions on who can create, update, or deprecate Namespaces.

On Temporal Cloud, use the Temporal Cloud UI 🔗

Link preview
How to manage Namespaces in Temporal Cloud
You can create and manage Namespaces from your Temporal Cloud UI.
introduction temporal cloud namespaces
or tcld commands to manage Namespaces.

On self-hosted Temporal Cluster, you can manage your registered Namespaces using tctl (recommended) or programmatically using APIs. Note that these APIs and tctl commands will not work with Temporal Cloud.

  • How to manage Namespaces using the Go SDK 🔗

    Link preview
    How to manage Namespaces
    You can get details for your Namespaces, update Namespace configuration, and deprecate or delete your Namespaces.
    guide-context

  • How to manage Namespaces using the Java SDK 🔗

    Link preview
    How to manage Namespaces
    You can get details for your Namespaces, update Namespace configuration, and deprecate or delete your Namespaces.
    guide-context

  • Update information and configuration for a registered Namespace on your Temporal Cluster:

  • Get details for a registered Namespace on your Temporal Cluster:

    • With tctl: tctl namespace describe
    • Use the Describe Namespace to return information and configuration details for a registered Namespace.

  • Get details for all registered Namespaces on your Temporal Cluster:

    • With tctl: tctl namespace list
    • Use the List Namespace API to return information and configuration details for all registered Namespaces on your Temporal Cluster.

  • Deprecate a Namespace: The Deprecate Namespace updates the state of a registered Namespace to "DEPRECATED". Once a Namespace is deprecated, you cannot start new Workflow Executions on it. All existing and running Workflow Executions on a deprecated Namespace will continue to run.

  • Delete a Namespace: Deletes a Namespace and all Workflow Executions on the Namespace. Note that this API is supported for Temporal Server version 1.17 and later.

  • With tctl: tctl namespace delete 🔗

    Link preview
    temporal operator namespace delete
    Deletes an existing Namespace.
    cli reference temporal cli operator command-line-interface-cli namespace namespace delete
    .

  • Use the DeleteNamespace API to delete a registered Namespaces. All the running Workflow Executions on a deleted Namespace are also deleted.

Setting​

Set Namespaces in your SDK Client to isolate your Workflow Executions to the Namespace. If you do not set a Namespace, all Workflow Executions started using the Client will be associated with the "default" Namespace. This means, you must have a default Namespace called "default" registered with your Temporal Cluster. See Registration for details.

What is a Global Namespace?​

A Global Namespace is a Namespace 🔗

Link preview
What is a Namespace?
A Namespace is a unit of isolation within the Temporal Platform
term explanation
that exists across Clusters when Multi-Cluster Replication 🔗
Link preview
What is Multi-Cluster Replication?
Multi-Cluster Replication is a feature which asynchronously replicates Workflow Executions from active Clusters to other passive Clusters, for backup and state reconstruction.
term explanation
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 🔗

Link preview
What is a Task?
A Task is the context needed to make progress with a specific Workflow Execution or Activity Execution.
term explanation
; 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 🔗
Link preview
What is Multi-Cluster Replication?
Multi-Cluster Replication is a feature which asynchronously replicates Workflow Executions from active Clusters to other passive Clusters, for backup and state reconstruction.
term explanation
). 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.