Namespace best practices
This page covers namespace best practices that apply to both open source Temporal and Temporal Cloud. Platform-specific guidance is clearly labeled throughout.
For reference documentation, see:
A Namespace is a unit of isolation within the Temporal Platform. It ensures that Workflow Executions, Task Queues, and resources are logically separated, preventing conflicts and enabling safe multi-tenant usage.
Use this page to decide how many Namespaces you need and where to draw boundaries between environments, services, domains, and tenants. For Cloud-specific namespace mechanics such as creation, tagging, and gRPC endpoints, see Namespaces (Temporal Cloud).
Related guidance:
- Managing Temporal Cloud access control
- Multi-tenant application patterns
- Managing Actions per Second (APS) limits in Temporal Cloud
Naming Conventions
Use lowercase and hyphens
Use lowercase letters and hyphens (-) as separators in Namespace names.
- Temporal Cloud: Namespace names are case-insensitive, so
MyNamespaceandmynamespacerefer to the same Namespace. - Open source: Namespace names are case-sensitive, so
MyNamespaceandmynamespaceare different Namespaces.
To avoid confusion across environments, always use lowercase.
Example: payment-checkout-prd
Follow a consistent naming pattern
Use a pattern like <use-case>-<domain>-<environment> to name Namespaces:
| Component | Max Length | Examples |
|---|---|---|
| Use case | 10 chars | payments, fulfill, orders |
| Domain | 10 chars | checkout, notify, inventory |
| Environment | 3 chars | dev, stg, prd |
Examples: payments-checkout-dev, fulfill-notify-prd, orders-inventory-stg
Why this pattern?
- Simple and easy to understand
- Clearly separates environments
- Groups related services under domains
- Allows platform teams to implement chargeback to application teams
- Namespace-level limits are isolated between different services and environments
Cloud Namespace names are limited to 39 characters.
If you need to include region, use short codes (e.g., aps1, use1).
Organizational Patterns
Choose your Namespace boundary intentionally
Start with the smallest number of Namespaces that gives you clear ownership and safe isolation. In Temporal Cloud, a Namespace boundary affects:
- APS limits and rate limiting
- access control and credential scope
- blast radius for misconfigured or overloaded Workers
- observability boundaries for dashboards and alerts
- operational overhead for provisioning, tagging, and lifecycle management
Use the following decision table as a starting point:
| If you need... | Prefer... | Why |
|---|---|---|
| Basic environment isolation for a single application or use case | Namespace per use case and environment | This is the simplest pattern and works well for most initial deployments |
| Separate operational ownership for services within the same use case | Namespace per use case, service, and environment | This isolates credentials, limits, and operational changes per service |
| Stronger boundaries across teams, domains, or business capabilities | Namespace per use case, domain, and environment | This reduces blast radius and lets teams own their own Namespace contracts |
| Tenant-specific credentials, rate limits, or compliance boundaries | Namespace per tenant | Use this only for a small number of high-value tenants because of the operational overhead |
As a default, start with one Namespace per use case and environment. Split later when APS pressure, security requirements, ownership boundaries, or troubleshooting needs justify the extra operational cost.
Pattern 1: Namespace per use case and environment
For simple configurations without multiple services or team boundaries.
Naming convention: <use-case>-<environment>
Example: payments-prd, orders-dev
Choose this pattern when:
- one team owns the use case
- environments need clean separation
- workload volume and criticality do not yet require further isolation
Pattern 2: Namespace per use case, service, and environment
When multiple services that are part of the same use case communicate externally to Temporal via API (HTTP/gRPC).
Naming convention: <use-case>-<service>-<environment>
Example: payments-gateway-prd, payments-processor-prd
Choose this pattern when:
- services need separate credentials or access policies
- one service can exhaust APS or operational limits independently of the others
- teams want separate ownership of deployment, alerting, or on-call boundaries
Pattern 3: Namespace per use case, domain, and environment
When multiple services need to communicate with each other, use Temporal Nexus to connect Workflows across Namespace boundaries. This provides better security, fault isolation, and modularity than sharing a Namespace.
Naming convention: <use-case>-<domain>-<environment>
Example: payments-checkout-prd, payments-refunds-prd
Choose this pattern when:
- multiple teams or domains need independent release cadence and ownership
- failures in one domain should not affect the others
- you want a stronger permission boundary between capabilities
- you plan to expose cross-Namespace contracts through Nexus
For systems without Nexus, services can communicate via Signals or Child Workflows within the same Namespace.
When multiple teams share a Namespace, prefix each Workflow ID with a service-specific string to ensure uniqueness. Task Queue names must also be unique within the Namespace.
Pattern 4: Namespace per tenant
Use a separate Namespace per tenant only when each tenant needs a true isolation boundary.
This is usually appropriate only for a small number of high-value tenants that require:
- dedicated credentials and access control
- tenant-specific rate limits or capacity decisions
- strict compliance or data-isolation boundaries
- independent debugging, alerting, and operational ownership
For most SaaS use cases, a shared Namespace with per-tenant Task Queues is simpler and more scalable. See Multi-tenant application patterns for those designs.
What should cause you to split a Namespace later?
Revisit your topology when one or more of the following becomes true:
- one workload is consuming enough APS that it regularly threatens others in the same Namespace
- one team needs tighter access controls or dedicated credentials
- production troubleshooting requires clearer dashboards, alerts, or ownership boundaries
- one application or domain is business-critical enough that its blast radius must be reduced
- a tenant or regulated workload needs stronger separation than Task Queue isolation can provide
Splitting a Namespace increases safety, but it also adds overhead for provisioning, tagging, credentials, and cross-Namespace coordination. Use Nexus where possible instead of sharing Temporal primitives across team or domain boundaries.
Production Safeguards
Use an Authorizer (open source only)
Use a custom Authorizer on your Frontend Service to set restrictions on who can create, update, or deprecate Namespaces.
If an Authorizer is not set, Temporal uses the nopAuthority authorizer that unconditionally allows all API calls.
On Temporal Cloud, role-based access controls provide namespace-level authorization without custom configuration.
Enable deletion protection (Temporal Cloud only)
Enable deletion protection for production Namespaces to prevent accidental deletion.
Enable High Availability (Temporal Cloud only)
For business-critical use cases with strict uptime requirements, enable High Availability features for a 99.99% contractual SLA.
Use Infrastructure as Code (Temporal Cloud only)
Use the Temporal Cloud Terraform provider to manage Namespaces. If Terraform isn't suitable, scripting against the Cloud Ops API or tcld is a good alternative.
This provides:
- Documentation of each Namespace's purpose and owners
- Prevention of infrastructure drift
- Version-controlled configuration changes
Use prevent_destroy = true in your Terraform configuration to prevent accidental Namespace deletion via Terraform.
This is separate from Temporal Cloud deletion protection, which prevents deletion through any interface.
Reference: Example Terraform configuration
Tagging (Temporal Cloud only)
Tags are key-value metadata pairs that help organize, track, and manage Namespaces.
Tags complement your naming convention by adding metadata that doesn't fit in the Namespace name. While the name captures use case, domain, and environment, tags can capture additional dimensions like team ownership, data sensitivity, or business criticality.
Recommended tag categories
| Tag Key | Purpose | Examples |
|---|---|---|
environment | Deployment stage | dev, staging, production |
team | Owning team | platform, payments, identity |
division | Business unit | engineering, finance, ops |
criticality | Business importance | high, medium, low |
data-sensitivity | Data classification | pii, pci, public |
latency-sensitivity | Performance tier | realtime, batch, async |
For tag structure, limits, and management instructions, see How to tag a Namespace.
SDK Client Configuration
Set Namespaces in your SDK Client to isolate your Workflow Executions.
If you do not set a Namespace, all Workflow Executions started using the Client will be associated with the default Namespace.
You must register a Namespace before setting it in your Client.
For configuration details, see: