diff --git a/docs/best-practices/managing-aps-limits.mdx b/docs/best-practices/managing-aps-limits.mdx index 2bb42674ba..0c323d0fb1 100644 --- a/docs/best-practices/managing-aps-limits.mdx +++ b/docs/best-practices/managing-aps-limits.mdx @@ -175,7 +175,11 @@ An APS limit is set per Namespace, so multiple use cases with multiple traffic p #### How to Mitigate -Plan for a set of Namespaces (one per environment) per use case. See [Managing a Namespace](/best-practices/managing-namespace) for more details. +Plan for a set of Namespaces (one per environment) per use case. This gives each use case its own APS envelope and +reduces the blast radius when one workload spikes or misbehaves. + +If you are deciding whether to split by use case, service, or domain, see +[Managing a Namespace](/best-practices/managing-namespace) for a topology decision framework. ## Provisioned Capacity and TRUs diff --git a/docs/best-practices/managing-namespace.mdx b/docs/best-practices/managing-namespace.mdx index e98116b903..465b0868ba 100644 --- a/docs/best-practices/managing-namespace.mdx +++ b/docs/best-practices/managing-namespace.mdx @@ -27,6 +27,15 @@ For reference documentation, see: A [Namespace](/namespaces) 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)](/cloud/namespaces). + +Related guidance: +- [Managing Temporal Cloud access control](/best-practices/cloud-access-control) +- [Multi-tenant application patterns](/production-deployment/multi-tenant-patterns) +- [Managing Actions per Second (APS) limits in Temporal Cloud](/best-practices/managing-aps-limits) + ## Naming Conventions ### Use lowercase and hyphens @@ -66,30 +75,72 @@ 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](/cloud/limits#actions-per-second) 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**: `_` +**Naming convention**: `-` + +**Example**: `payments-prd`, `orders-dev` -**Example**: `payments_prod`, `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**: `__` +**Naming convention**: `--` + +**Example**: `payments-gateway-prd`, `payments-processor-prd` + +Choose this pattern when: -**Example**: `payments_gateway_prod`, `payments_processor_prod` +- 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](/nexus) to connect Workflows across Namespace boundaries. This provides better security, fault isolation, and modularity than sharing a Namespace. -**Naming convention**: `__` +**Naming convention**: `--` -**Example**: `payments_checkout_prod`, `payments_refunds_prod` +**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](/sending-messages#sending-signals) or [Child Workflows](/child-workflows) within the same Namespace. @@ -98,6 +149,33 @@ When multiple teams share a Namespace, prefix each Workflow ID with a service-sp Task Queue names must also be unique within the Namespace. ::: +### Pattern 4: Namespace per tenant + +Use a separate [Namespace](/namespaces) 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](/task-queue) is simpler and more scalable. +See [Multi-tenant application patterns](/production-deployment/multi-tenant-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](/nexus) where possible instead of sharing Temporal primitives across team or domain boundaries. + ## Production Safeguards ### Use an Authorizer (open source only) {#authorizer} diff --git a/docs/cloud/get-started/namespaces.mdx b/docs/cloud/get-started/namespaces.mdx index 193027a39d..466b112b2d 100644 --- a/docs/cloud/get-started/namespaces.mdx +++ b/docs/cloud/get-started/namespaces.mdx @@ -232,77 +232,11 @@ See the [`tcld` namespace create](/cloud/tcld/namespace/#create) command referen ## What are some Namespace best practices? {#best-practices} -This section provides general guidance for organizing [Namespaces](/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. +For guidance on how many Namespaces to create, how to split workloads across services or domains, and when to isolate +tenants or teams, see [Namespace best practices](/best-practices/managing-namespace). -Each team can have their own Namespace for improved modularity, security, debugging, and fault isolation. Namespaces -contain the blast radius of misbehaving Workers that may exhaust rate limits. Sensitive Workflow state (PCI data) can be -secured with per-Namespace permissions and encrypted with a separate encryption key. - -Temporal Applications in different Namespaces may be connected with [Nexus](/cloud/nexus) by exposing a clean service -contract for others to use with built-in [Nexus access controls](/cloud/nexus/security). Nexus supports cross-team, -cross-domain, multi-region, and multi-cloud use cases. - -### Constraints and limitations - -Before considering an appropriate Namespace configuration, you should be aware of the constraints -listed on the [Temporal Cloud Limits](/cloud/limits) page. - -For advice on managing Namespaces within limits, see the [Namespace Best Practices](/best-practices/managing-namespace) page. - -### 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](/workflow-execution). -- Namespaces can be split along additional boundaries such as service, application, domain or even sub-domain. -- Namespaces should be used to reduce the "blast radius" for mission-critical applications. -- 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. -- Use [Nexus](/nexus) to communicate across team, domain, and Namespace boundaries with a clean service contract instead of sharing Temporal primitives directly. - Nexus enables each team to have their own Namespace for improved security, troubleshooting, and fault isolation while sharing capabilities through Nexus Endpoints. - -### 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](/sending-messages#sending-signals) or by -starting [Child Workflows](/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>
+This page focuses on Temporal Cloud namespace mechanics such as naming rules, provisioning, authentication, tagging, and +accessing Namespace endpoints. ## How to access a Namespace in Temporal Cloud {#access-namespaces} diff --git a/docs/production-deployment/multi-tenant-patterns.mdx b/docs/production-deployment/multi-tenant-patterns.mdx index bb7d787d35..b9149c3233 100644 --- a/docs/production-deployment/multi-tenant-patterns.mdx +++ b/docs/production-deployment/multi-tenant-patterns.mdx @@ -21,6 +21,10 @@ Many SaaS providers and large enterprise platform teams use a single Temporal [N This guide covers architectural patterns, design considerations, and practical examples for building multi-tenant applications with Temporal. +For related guidance on where to draw Namespace boundaries and how to scope credentials and permissions, see +[Namespace best practices](/best-practices/managing-namespace) and +[Managing Temporal Cloud access control](/best-practices/cloud-access-control). + ## Architectural principles When designing a multi-tenant Temporal application, follow these principles: @@ -90,6 +94,11 @@ Only practical for a small number (< 50) of high-value tenants due to operationa - Requires more [Workers](/workers) (minimum 2 per Namespace for high availability) - Expensive at scale +This pattern is usually chosen when tenant boundaries also need to be credential boundaries. For example, each tenant may +need its own service accounts, API keys, dashboards, or rate limits. If that is your primary driver, review +[Managing Temporal Cloud access control](/best-practices/cloud-access-control) together with +[Namespace best practices](/best-practices/managing-namespace) before committing to Namespace-per-tenant isolation. + @@ -229,6 +238,20 @@ While testing, also pay attention to your [metrics capacity and cardinality](/cl ## Best practices +### How tenant isolation affects Namespace and access design + +Your multi-tenant architecture also determines how much isolation you get from Namespaces and access controls: + +- **Shared Namespace with per-tenant Task Queues**: Best for scale and operational simplicity, but tenant isolation is + mostly enforced by your application and worker routing logic rather than by Temporal credentials. +- **Separate Namespaces for domains or services**: Useful when teams need separate credentials, dashboards, APS + envelopes, or on-call boundaries. +- **Namespace per tenant**: Strongest isolation, but highest provisioning and credential-management overhead. + +If tenants, teams, or regulated workloads need different credentials or RBAC boundaries, decide that together with your +Namespace topology. See [Namespace best practices](/best-practices/managing-namespace) and +[Managing Temporal Cloud access control](/best-practices/cloud-access-control). + ### Monitoring Track these [metrics](/references/sdk-metrics) per tenant: