Consolidate namespace best practices guidance (#4348)

Co-authored-by: Brian MacDonald <brian.macdonald@temporal.io>

Author: bechols

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
 

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**: `<use-case>_<environment>`
+**Naming convention**: `<use-case>-<environment>`
+
+**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**: `<use-case>_<service>_<environment>`
+**Naming convention**: `<use-case>-<service>-<environment>`
+
+**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**: `<use-case>_<domain>_<environment>`
+**Naming convention**: `<use-case>-<domain>-<environment>`
 
-**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}

docs/cloud/get-started/namespaces.mdx

@@ -236,77 +236,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:
-
-<pre>&lt;use-case>_&lt;environment></pre>
-
-#### 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:
-
-<pre>&lt;use-case>_&lt;service>_&lt;environment></pre>
-
-#### 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:
-
-<pre>&lt;use-case>_&lt;domain>_&lt;environment></pre>
-
-Sample workflowId convention:
-
-<pre>&lt;service-string>_&lt;workflow-id></pre>
+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}
 

docs/production-deployment/multi-tenant-patterns.mdx

@@ -23,6 +23,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:
@@ -120,6 +124,11 @@ Only practical for a smaller number of high-value tenants due to operational ove
 - Requires a new [Worker](/workers) pool deployment for each customer (minimum 2 per Namespace for high availability)
 - Not cost-effective 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.
+
 <RelatedReadContainer>
   <RelatedReadItem path="/evaluate/development-production-features/multi-tenancy#namespace-isolation" text="Namespace Isolation in Temporal Cloud" archetype="cloud-guide" />
 </RelatedReadContainer>
@@ -272,6 +281,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: