Skip to main content

​
Namespaces

Namespaces provide isolated execution environments within a Temporal cluster. Each namespace has its own workflows, activities, task queues, and configuration, enabling secure multi-tenancy and organizational separation.

​
Namespace Fundamentals

A namespace is the fundamental isolation boundary in Temporal:

Isolation

Workflows in one namespace cannot directly interact with workflows in another namespace. Complete data isolation.

Configuration

Each namespace has independent retention, archival, replication, and search attribute settings.

Multi-Tenancy

Different teams, customers, or environments can share a cluster safely using separate namespaces.

Resource Limits

Rate limits, quotas, and visibility can be configured per-namespace.

​
Namespace Structure

Each namespace contains: 
// From common/namespace/namespace.go
type Namespace struct {
    info          *persistencespb.NamespaceInfo
    config        *persistencespb.NamespaceConfig
    configVersion int64
    notificationVersion int64
    
    customSearchAttributesMapper CustomSearchAttributesMapper
    replicationResolver          ReplicationResolver
}

type NamespaceInfo struct {
    Id          string                    // Unique namespace ID (UUID)
    Name        string                    // User-visible namespace name
    State       enumspb.NamespaceState   // Registered, Deprecated, Deleted
    Description string
    Owner       string
    Data        map[string]string         // Custom key-value metadata
}

​
Namespace ID vs Name

Type: UUID string (e.g., "a1b2c3d4-e5f6-7890-abcd-ef1234567890")Characteristics:
  • Permanent and immutable
  • Used internally for all operations
  • Workflows/history keyed by namespace ID
  • Survives namespace renames
Type: String (e.g., "my-application", "production", "customer-acme")Characteristics:
  • User-visible, mutable (can be renamed)
  • Used in APIs and SDKs
  • Resolved to namespace ID by server
  • Must be unique within cluster

​
Namespace States

Namespaces transition through several states:
1

Registered (Active)

Normal operational state. Workflows can be started, workers can poll, all operations permitted.
2

Deprecated

Soft-deleted state. New workflows cannot be started, but existing workflows continue and can complete. Used for graceful wind-down.
3

Deleted

Hard-deleted state. Namespace cannot be used. Data retained per retention policy, then cleaned up.
func (ns *Namespace) State() enumspb.NamespaceState {
    if ns.info == nil {
        return enumspb.NAMESPACE_STATE_UNSPECIFIED
    }
    return ns.info.State
}

​
Namespace Configuration

Each namespace has extensive configuration options:

​
Retention Policy

type NamespaceConfig struct {
    // How long to keep workflow history after completion
    WorkflowExecutionRetentionTtl *durationpb.Duration  // e.g., 7 days, 30 days, 90 days
    
    // Bad binary checksums (for detecting bad deployments)
    BadBinaries *namespacepb.BadBinaries
}
After retention period expires, workflow history is deleted. Choose retention based on compliance, debugging needs, and storage costs.

​
Archival Configuration

Namespaces can archive workflow histories to long-term storage: 
type ArchivalConfigState struct {
    State enumspb.ArchivalState  // Enabled or Disabled
    URI   string                  // Storage location (s3://bucket, gs://bucket)
}

func (ns *Namespace) HistoryArchivalState() ArchivalConfigState {
    return ArchivalConfigState{
        State: ns.config.HistoryArchivalState,
        URI:   ns.config.HistoryArchivalUri,
    }
}
Supported Backends:
  • Amazon S3 (s3://bucket/prefix)
  • Google Cloud Storage (gs://bucket/prefix)
  • Local filesystem (file:///path)
Use Cases: Compliance, audit trails, long-term debugging
Separate from history archival, archives visibility records (workflow metadata).
func (ns *Namespace) VisibilityArchivalState() ArchivalConfigState {
    return ArchivalConfigState{
        State: ns.config.VisibilityArchivalState,
        URI:   ns.config.VisibilityArchivalUri,
    }
}

​
Custom Search Attributes

Namespaces can define custom search attributes for workflow search: 
type CustomSearchAttributesMapper struct {
    fieldToAlias map[string]string  // Internal field -> user alias
    aliasToField map[string]string  // User alias -> internal field
}

type NamespaceConfig struct {
    CustomSearchAttributeAliases map[string]string
}
Use search attributes to make workflows searchable by business-relevant fields like customer ID, order number, or status.

​
Namespace Replication

For multi-cluster deployments, namespaces can be replicated: 
type ReplicationPolicy int

const (
    // Single cluster - no replication
    ReplicationPolicyOneCluster ReplicationPolicy = 0
    
    // Multi-cluster - workflows replicated
    ReplicationPolicyMultiCluster ReplicationPolicy = 1
)

​
Global Namespaces

Active-Passive Replication: One cluster is active (handles writes), others are passive (replicate).Failover: Can change which cluster is active, enabling disaster recovery.Cross-Cluster Visibility: View workflows from any cluster.Use Cases: Business continuity, disaster recovery, global presence.
type ReplicationResolver interface {
    ReplicationState() enumspb.ReplicationState
    ActiveClusterName(businessID string) string
    ClusterNames(businessID string) []string
}

func (ns *Namespace) IsOnCluster(clusterName string) bool {
    for _, cluster := range ns.ClusterNames(EmptyBusinessID) {
        if cluster == clusterName {
            return true
        }
    }
    return false
}

​
Namespace Registry

The server maintains an in-memory cache of all namespaces:

​
Namespace Cache

1

Load from database

On startup, all namespace metadata loaded from persistence
2

Cache in memory

Namespace objects cached by ID and name for fast lookup
3

Watch for changes

Background process polls for namespace updates
4

Refresh cache

When namespace created/updated, cache entry refreshed
Cache refresh has eventual consistency. Namespace changes propagate to all server instances within seconds.

​
Namespace Sharding

While namespaces provide logical isolation, workflows are physically distributed:
  • Workflows hashed across shards by (Namespace ID, Workflow ID)
  • Multiple namespaces per shard - shards not dedicated to namespaces
  • Enables scale - even single namespace can use all shards

​
Namespace Operations

​
Creating Namespaces

# Using tctl
tctl namespace register \
  --name my-namespace \
  --description "My application namespace" \
  --retention 7d

# Using Temporal Cloud
# Done via Web UI or tcld CLI

​
Updating Namespaces

# Update retention
tctl namespace update \
  --name my-namespace \
  --retention 30d

# Enable archival
tctl namespace update \
  --name my-namespace \
  --history-archival-state enabled \
  --history-uri "s3://my-bucket/temporal-archive"

​
Describing Namespaces

tctl namespace describe --name my-namespace

​
Namespace Best Practices

One Namespace Per Environment

Use separate namespaces for dev, staging, production. Prevents accidental cross-environment issues.

Namespace Per Customer

For SaaS applications, use one namespace per customer for isolation and resource control.

Meaningful Names

Use descriptive names like myapp-prod, customer-acme, not generic names like ns1.

Document Ownership

Use description and metadata fields to track which team owns each namespace.

​
Anti-Patterns

Don’t create namespaces per workflow type: Namespaces are heavyweight. Use task queues for routing different workflow types.
Don’t over-provision namespaces: Each namespace adds overhead. Prefer fewer namespaces with task queue routing.

​
Namespace Limits and Quotas

Namespaces can have rate limits:
  • RPS limits: Max requests per second for operations
  • Worker limits: Max concurrent pollers per task queue
  • Workflow limits: Max concurrent workflows
  • Visibility limits: Max list/query rate
Limits configured via dynamic configuration or Temporal Cloud settings. Protects cluster from runaway workloads.

​
Namespace Security

Namespace-level security controls:

​
Authorization

  • API key per namespace (Temporal Cloud)
  • mTLS certificates can be scoped to namespaces
  • RBAC policies can restrict access to specific namespaces

​
Audit Logging

  • Audit logs track all namespace operations
  • Who created/modified namespace
  • What changed in configuration

​
Namespace Observability

Key metrics per namespace:
  • Workflow Start Rate: Workflows started per second
  • Workflow Completion Rate: Workflows completed per second
  • Open Workflows: Currently executing workflows
  • Task Queue Backlog: Pending tasks across all task queues
  • Error Rates: Failed workflows, activities, tasks
// Metrics are tagged with namespace name
metricsHandler.WithTags(metrics.NamespaceTag(namespace.Name().String()))

​
Default Namespace

Each cluster has a default namespace:
  • Created automatically on cluster bootstrap
  • Used if no namespace specified in SDK clients (for development)
  • Not special otherwise - same capabilities as any namespace
Don’t use default namespace for production. Create dedicated namespaces with appropriate configuration.

Build docs developers (and LLMs) love

Get started for freeTalk to us