Namespaces

Namespace isolation, multi-tenancy, and management in Temporal Server

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

Namespace ID

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

Namespace Name

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:

History Archival

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

Visibility Archival

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

Global Namespace Features

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.

Related Concepts

• Task Queues - Scoped within namespaces
• Workflows - Belong to a namespace
• Workers - Poll specific namespace’s task queues