How to manage Namespaces in Temporal Cloud

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

Create a Namespace
Access a Namespace
Manage Namespaces
Delete a Namespace

What is a Cloud Namespace Name?

A Cloud Namespace Name is a customer-supplied name for a Namespace in Temporal Cloud. Each Namespace Name, such as accounting-production, is unique within the scope of a customer's account. It cannot be changed after the Namespace is provisioned.

Each Namespace Name must conform to the following rules:

A Namespace Name must contain at least 2 characters and no more than 34 characters.
A Namespace Name must begin with a letter, end with a letter or number, and contain only letters, numbers, and the hyphen (-) character.
Each hyphen (-) character must be immediately preceded and followed by a letter or number; consecutive hyphens are not permitted.
All letters in a Namespace Name must be lowercase.

What is a Temporal Cloud Account Id?

A Temporal Cloud Account Id is a unique identifier for a customer for the entire time they use Temporal Cloud. Temporal Technologies assigns each Account Id, which is an opaque code of five or six alphanumeric characters, such as f45a2. The Account Id is shown in the upper-right corner of Workflows and Schedules listed in the Web UI.

info

For more information on obtaining a Temporal Cloud Account Id, see our Cloud account commands page.

What is a Cloud Namespace Id?

A Cloud Namespace Id is a globally unique identifier for a Namespace in Temporal Cloud. A Namespace Id is formed by concatenating the following:

A Namespace Name
A period (.)
The Account Id to which the Namespace belongs

For example, for the Account Id f45a2 and Namespace Name accounting-production, the Namespace Id is accounting-production.f45a2.

How to create a Namespace in Temporal Cloud

info

The user who creates a Namespace is automatically granted Namespace Admin permission for that Namespace.

To create a Namespace, a user must have the Developer or Global Admin account-level Role.

tip

By default, each account has a quota of 10 Namespaces. If you want to increase this limit, open a support ticket.

Information needed to create a Namespace

To create a Namespace in Temporal Cloud, gather the following information:

Namespace Name and region.
Retention Period for the Event History of closed Workflow Executions.
CA certificate for the Namespace.
Codec Server endpoint to show decoded payloads to users in the Event History for Workflow Executions in the Namespace. For details, see Securing your data.
Permissions for each user.

Create a Namespace using Temporal Cloud UI

Gather the information listed earlier in Information needed to create a Namespace.
Go to the Temporal Cloud UI and log in.
On the left side of the window, click Namespaces.
On the Namespaces page, click Create Namespace in the upper-right portion of the window.
On the Create Namespace page in Name, enter the Namespace Name.
In Region, select the region in which to host this Namespace.
In Retention Period, specify a value from 1 to 90 days. When choosing this value, consider your needs for Event History versus the cost of maintaining that Event History. Typically, a development Namespace has a short retention period and a production Namespace has a longer retention period. (If you need to change this value later, contact Temporal Support.)
In Certificate, paste the CA certificate for this Namespace.
Optional: In Codec Server, enter the URL and port number of your Codec Server endpoint. For details, see Securing your data.
Click Create Namespace.

Create a Namespace using tcld

See the tcld namespace create command reference for details.

What are some Namespace best practices?

This section provides general guidance for organizing Namespaces across use cases, services, applications, or domains. Temporal Cloud provides Namespace–as-a-service, so the Namespace is the endpoint. Customers should consider not only a Namespace naming convention but also how to group or isolate workloads using the Namespace as a boundary.

Constraints and limitations

Before considering an appropriate Namespace configuration, you should be aware of the following constraints:

Each Temporal account has a default limit of 10 Namespaces. You can request an increase by creating a ticket for Temporal Support.
Cross-Namespace communications between Workflows is not yet supported. For now, you can use the SDK client from within an Activity as a workaround.
Each Namespace has a rate limit ("throttling"). The default rate limit is 200 Actions per second but can be increased via a support ticket.
Each Namespace has a service-level agreement (SLA) of 99.9% uptime.
For now, Namespaces are single-region only.
A Namespace is a security isolation boundary. Access to Temporal by Worker Processes is permitted at the Namespace level. Isolating applications or environments (development, test, staging, production) should take this into consideration.
A Namespace is an endpoint. To access a Namespace from a Temporal Client requires mTLS authorization, which requires CA certificates.
Workflow Id uniqueness is per Namespace.
Task Queue names are unique per Namespace.
Closed Workflow retention is per Namespace.
RBAC permissions are implemented at the Namespace level.

General guidance

Namespace configuration requires some consideration. Following are some general guidelines to consider.

Namespaces are usually defined per use case. A use case can encompass a broad range of Workflow types and a nearly unlimited scale of concurrent Workflow Executions.
Namespaces can be split along additional boundaries such as service, application, domain or even sub-domain.
Environments such as production and development usually have requirements for isolation. We recommend that each environment has its own Namespace.
Namespaces should be used to reduce the "blast radius" for mission-critical applications.
Workflows that need to communicate with each other should (for now) be in the same Namespace.
If you need to share Namespaces across team or domain boundaries, be sure to ensure the uniqueness of Workflow Ids.

Examples

Following are some ideas about how to organize Namespaces.

Example 1: Namespace per use case and environment

We recommend using one Namespace for each use case and environment combination for simple configurations in which multiple services and team or domain boundaries don't exist.

Sample naming convention:

<use-case>_<environment>

Example 2: Namespace per use case, service, and environment

We recommend using one Namespace for each use case, service, and environment combination when multiple services that are part of same use case communicate externally to Temporal via API (HTTP/gRPC).

Sample naming convention:

<use-case>_<service>_<environment>

Example 3: Namespace per use case, domain, and environment

We recommend using one namespace per use case, domain, and environment combination when multiple services that are part of the same use case need to communicate with each another via Signals or by starting Child Workflows. In this case, though, you must be mindful about Workflow Id uniqueness by prefixing each Workflow Id with a service-specific string. The name of each Task Queue must also be unique. If multiple teams are involved, the domain could also represent a team boundary.

Sample naming convention:

<use-case>_<domain>_<environment>

Sample workflowId convention:

<service-string>_<workflow-id>

How to access a Namespace in Temporal Cloud

Each Namespace in Temporal Cloud has two unique endpoints, both of which include the Namespace Id.

For programmatic access, a gRPC endpoint in the form <NamespaceId>.tmprl.cloud; for example, accounting-production.f45a2.tmprl.cloud:7233.
For accessing Temporal Web UI, an HTTPS endpoint in the form https://cloud.temporal.io/namespaces/<namespaceId>; for example, https://cloud.temporal.io/namespaces/accounting-production.f45a2.