Skip to main content

Multi-tenant application patterns

How do I build a multi-tenant application using Temporal?

Many SaaS providers and large enterprise platform teams use a single Temporal Namespace with per-tenant Task Queues to power their multi-tenant applications. This approach maximizes resource efficiency while maintaining logical separation between tenants.

This guide covers architectural patterns, design considerations, and practical examples for building multi-tenant applications with Temporal.

Architectural principles​

When designing a multi-tenant Temporal application, follow these principles:

  • Define your tenant model - Determine what constitutes a tenant in your business (customers, pricing tiers, teams, etc.)
  • Prefer simplicity - Start with the simplest pattern that meets your needs
  • Understand Temporal limits - Design within the constraints of your Temporal deployment
  • Test at scale - Performance testing must drive your capacity decisions
  • Plan for growth - Consider how you'll onboard new tenants and scale workers

Architectural patterns​

There are three main patterns for multi-tenant applications in Temporal, listed from most to least recommended:

Use different Task Queues for each tenant's Workflows and Activities.

This is the recommended pattern for most use cases. Each tenant gets dedicated Task Queue(s), with Workers polling multiple tenant Task Queues in a single process.

Pros:

  • Strong isolation between tenants
  • Efficient resource utilization
  • Flexible worker scaling
  • Easy to add new tenants
  • Can handle thousands of tenants per Namespace

Cons:

  • Requires worker configuration management
  • Potential for uneven resource distribution
  • Need to prevent "noisy neighbor" issues at the worker level
Related 📚

2. Shared Workflow Task Queues, separate Activity Task Queues​

Share Workflow Task Queues but use different Activity Task Queues per tenant.

Use this pattern when Workflows are lightweight but Activities have heavy resource requirements or external dependencies that need isolation.

Pros:

  • Easier worker management than full isolation
  • Activity-level tenant isolation
  • Good for compute-intensive Activities

Cons:

  • Less isolation than pattern #1
  • Workflow visibility is shared
  • More complex to reason about

3. Namespace per tenant​

Use a separate Namespace for each tenant.

Only practical for a small number (< 50) of high-value tenants due to operational overhead.

Pros:

  • Complete isolation between tenants
  • Per-tenant rate limiting
  • Maximum security

Cons:

  • Higher operational overhead
  • Credential and connectivity management per Namespace
  • Requires more Workers (minimum 2 per Namespace for HA)
  • Expensive at scale
Related 📚

Task Queue isolation pattern​

This section details the recommended pattern for most multi-tenant applications.

Worker design​

When a Worker starts up:

  1. Load tenant configuration - Retrieve the list of tenants this Worker should handle (from config file, API, or database)
  2. Create Task Queues - For each tenant, generate a unique Task Queue name (e.g., customer-{tenant-id})
  3. Register Workflows and Activities - Register your Workflow and Activity implementations once, passing the tenant-specific Task Queue name
  4. Poll multiple Task Queues - A single Worker process polls all assigned tenant Task Queues
// Example: Go worker polling multiple tenant Task Queues
for _, tenant := range assignedTenants {
    taskQueue := fmt.Sprintf("customer-%s", tenant.ID)

    worker := worker.New(client, taskQueue, worker.Options{})
    worker.RegisterWorkflow(YourWorkflow)
    worker.RegisterActivity(YourActivity)
}

Routing requests to Task Queues​

Your application needs to route Workflow starts and other operations to the correct tenant Task Queue:

// Example: Starting a Workflow for a specific tenant
taskQueue := fmt.Sprintf("customer-%s", tenantID)
workflowOptions := client.StartWorkflowOptions{
    ID:        workflowID,
    TaskQueue: taskQueue,
}

Consider creating an API or service that:

  • Maps tenant IDs to Task Queue names
  • Tracks which Workers are handling which tenants
  • Allows both your application and Workers to read the mappings of 1. Tenant IDs to Task Queues and 2. Workers to tenants.

Capacity planning​

Key questions to answer through performance testing:

Namespace capacity:

Worker capacity:

  • How many tenants can a single Worker process handle?
  • What are the CPU and memory requirements per tenant?
  • How many concurrent Workflow executions per tenant?
  • How many concurrent Activity executions per tenant?

SDK configuration to tune:

  • MaxConcurrentWorkflowTaskExecutionSize
  • MaxConcurrentActivityExecutionSize
  • MaxConcurrentWorkflowTaskPollers
  • MaxConcurrentActivityTaskPollers
  • Worker replicas (in Kubernetes deployments)

Provisioning new tenants​

Automate tenant onboarding with a Temporal Workflow:

  1. Create a tenant onboarding Workflow that:

    • Validates tenant information
    • Provisions infrastructure
    • Deploys/updates Worker configuration
    • Triggers Worker restarts or scaling
    • Verifies the tenant is operational

  2. Store tenant-to-Worker mappings in a database or configuration service

  3. Update Worker deployments to pick up new tenant assignments

Practical example​

Scenario: A SaaS company has 1,000 customers and expects to grow to 5,000 customers over 3 years. They have 2 Workflows and ~25 Activities per Workflow. All customers are on the same tier (no segmentation yet).

Assumptions​

ItemValue
Current customers1,000
Workflow Task Queues per customer1
Activity Task Queues per customer1
Max Task Queue pollers per Namespace5,000
SDK concurrent Workflow task pollers5
SDK concurrent Activity task pollers5
Max concurrent Workflow executions200
Max concurrent Activity executions200

Capacity calculations​

Task Queue poller limits:

  • Each Worker uses 10 pollers per tenant (5 Workflow + 5 Activity)
  • Maximum Workers in Namespace: 5,000 pollers ÷ 10 = 500 Workers

Worker capacity:

  • Each Worker can theoretically handle 200 Workflows and 200 Activities concurrently
  • Conservative estimate: 250 tenants per Worker (accounting for overhead)
  • For 1,000 customers: 4 Workers minimum (plus replicas for HA)
  • For 5,000 customers: 20 Workers minimum (plus replicas for HA)

Namespace capacity:

  • At 250 tenants per Worker, need 2 Workers per group of tenants (for HA)
  • Maximum tenants in Namespace: (500 Workers ÷ 2) × 250 = 62,500 tenants
note

These are theoretical calculations based on SDK defaults. Always perform load testing to determine actual capacity for your specific workload. Monitor CPU, memory, and Temporal metrics during testing.

While testing, also pay attention to your metrics capacity and cardinality.

Worker assignment strategies​

Option 1: Static configuration

  • Each Worker reads a config file listing assigned tenant IDs
  • Simple to implement
  • Requires deployment to add tenants

Option 2: Dynamic API

  • Workers call an API on startup to get assigned tenants
  • Workers identified by static ID (1 to N)
  • API returns tenant list based on Worker ID
  • More flexible, no deployment needed for new tenants

Best practices​

Monitoring​

Track these metrics per tenant:

Handling noisy neighbors​

Even with Task Queue isolation, monitor for tenants that:

  • Generate excessive load
  • Have high failure rates
  • Cause Worker resource exhaustion

Strategies:

  • Implement per-tenant rate limiting in your application
  • Move problematic tenants to dedicated Workers
  • Use Workflow/Activity timeouts aggressively

Tenant lifecycle​

Plan for:

  • Onboarding - Automated provisioning Workflow
  • Scaling - When to add new Workers for growing tenants
  • Offboarding - Graceful tenant removal and data cleanup
  • Rebalancing - Redistributing tenants across Workers

Search Attributes​

Use Search Attributes to enable tenant-scoped queries:

// Add tenant ID as a Search Attribute
searchAttributes := map[string]interface{}{
    "TenantId": tenantID,
}

This allows filtering Workflows by tenant in the UI and SDK:

TenantId = 'customer-123' AND ExecutionStatus = 'Running'
Related 📚