diff --git a/docs/cloud/get-started/namespaces.mdx b/docs/cloud/get-started/namespaces.mdx index 0d11d8b4eb..8ca131a9c6 100644 --- a/docs/cloud/get-started/namespaces.mdx +++ b/docs/cloud/get-started/namespaces.mdx @@ -131,16 +131,16 @@ utility at a command line interface (CLI). Follow these steps. -## What is a Cloud Namespace Id? {#temporal-cloud-namespace-id} +## What is a Cloud Namespace ID? {#temporal-cloud-namespace-id} -A Cloud Namespace Id is a globally unique identifier for a [Namespace](/namespaces) in Temporal Cloud. A Namespace Id is +A Cloud Namespace ID is a globally unique identifier for a [Namespace](/namespaces) in Temporal Cloud. A Namespace ID is formed by concatenating the following: 1. A [Namespace Name](#temporal-cloud-namespace-name) 1. A period (.) 1. The [Account ID](#temporal-cloud-account-id) to which the Namespace belongs -For example, for the Account ID `123de` and Namespace Name `accounting-production`, the Namespace Id is +For example, for the Account ID `123de` and Namespace Name `accounting-production`, the Namespace ID is `accounting-production.123de`. ## What is a Cloud gRPC Endpoint? {#temporal-cloud-grpc-endpoint} @@ -158,7 +158,8 @@ A gRPC endpoint appears on the detail page for each Cloud Namespace. Follow thes 2. Navigate to the Namespace list page from the left-side vertical navigation. 3. Tap or click on the Namespace Name to select and open the page for the Namespace whose endpoint you want to retrieve. 4. On the Namespace detail page, click on the "Connect" button in the top right corner of the page. -5. Click the copy icon next to the gRPC address to copy it to your clipboard. +5. If multiple endpoints are displayed, choose which [type of endpoint](/cloud/namespaces/#access-namespaces) best fits your use case. +6. Click the copy icon next to the gRPC address to copy it to your clipboard. See [How to access a Namespace in Temporal Cloud](/cloud/namespaces/#access-namespaces) for more information on different gRPC endpoint types and how to access them. @@ -235,155 +236,124 @@ 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. +See [Namespace Best Practices](/best-practices/managing-namespace) for an overview of: -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. +- naming conventions +- typical organizational patterns +- safeguards for production +- tagging + +## How to call Workflows from different Namespaces? 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 +## Namespace Constraints and Limitations {#limits} -Before considering an appropriate Namespace configuration, you should be aware of the following constraints: +Temporal Cloud Namespaces operate under the following constraints: - By default, each account is allocated with a limit of ten Namespaces. As you create and use your Namespaces, for example by scheduling Workflows, Temporal Cloud automatically raises your limit. Our service identifies your usage patterns. It responds by slowly increasing your allowance, up to 100 Namespaces. You can request further increases beyond the 100 Namespace limit by opening a [support ticket](/cloud/support#support-ticket). -- Each Namespace has a rate limit, which is measured in Actions per second (APS). A namespace may be throttled when its - throughput becomes too high. Throttling means limiting the rate at which actions are performed to prevent overloading - the system. A Namespace's default limit is set at 400 APS and automatically adjusts based on recent usage (over the - prior 7 days). Your APS limit will never fall below this default value. -- Each Namespace has a default service-level agreement (SLA) of 99.9% uptime. -- You can opt-in to using [High Availability features](https://docs.temporal.io/cloud/high-availability) with a 99.99% - contractual SLA. +- Each Namespace has [rate limits](/cloud/limits#namespace-level) for actions, operations, schedules, requests, and visibility requests. + A namespace may be rate limited when its throughput becomes too high to prevent overloading the system. + Namespace limits automatically adjust based on the prior 7 days of usage. +- By default, Namespaces have a [service-level agreement (SLA)](/cloud/sla) of 99.9% availability against service errors. +- You can opt-in to using [High Availability features](https://docs.temporal.io/cloud/high-availability) to increase the + SLA to 99.99%. + - Note: If a Namespace's [action per second limit](/cloud/limits#actions-per-second) has been raised above the default, + then it will require a support ticket to enable High Availability. + Support will ensure that Temporal Cloud has capacity to handle the additional APS before it adds the replica. - A Namespace is a security isolation boundary. Access to Temporal by [Worker Processes](/workers#worker-process) is permitted at the Namespace level. Isolating applications or environments (development, test, staging, production) - should take this into consideration. -- A Namespace is provisioned with an endpoint for executing your Workflows. Accessing a Namespace from a Temporal Client + should take this into consideration. See the [best practices for organizing Namespaces](/best-practices/managing-namespace) +- A Namespace is provisioned with [endpoints](constraints-and-limitations) for executing your Workflows. Accessing a Namespace from a Worker or Temporal Client requires [API keys](/cloud/api-keys) or [mTLS](/cloud/certificates) authentication. -- [Workflow Id](/workflow-execution/workflowid-runid#workflow-id)uniqueness is per Namespace. +- Every open Workflow in a Namespace needs a unique [Workflow ID](/workflow-execution/workflowid-runid#workflow-id). + This does not apply to closed Workflows, which may have the same Workflow ID in the same Namespace. + Open Workflows in different Namespaces may have the same Workflow ID. - [Task Queue](/task-queue) names are unique per Namespace. - Closed Workflow retention is per Namespace. - RBAC [permissions](/cloud/users#namespace-level-permissions) are implemented at the Namespace level. - -### 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. -- 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. -- Workflows that need to communicate with each other should (for now) be in the same Namespace. -- If you need to share Namespaces across team or domain boundaries, be sure to ensure the uniqueness of Workflow Ids. - -### 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>+- For Workflows in different Namespaces to communicate with each other, they must use Nexus. ## How to access a Namespace in Temporal Cloud {#access-namespaces} {/* How to access a Namespace in Temporal Cloud */} -Temporal Cloud normally supports authentication to Namespaces using [API keys](/cloud/api-keys) _or_ -[mTLS](/cloud/certificates). If you need to migrate from one authentication method to another, or you require both API -key and mTLS authentication to be enabled on your Namespace, please contact +Temporal Cloud supports authentication to Namespaces using [API keys](/cloud/api-keys) _or_ +[mTLS](/cloud/certificates). To migrate a Namespace from one authentication method to another, or to use both API +key and mTLS authentication on the same Namespace, please contact [Support](https://docs.temporal.io/cloud/support#support-ticket). :::info -Namespace authentication requiring both API key and mTLS is in -[pre-release](/evaluate/development-production-features/release-stages), and doesn't support +Using both API key and mTLS authentication on the same Namespace is in +[pre-release](/evaluate/development-production-features/release-stages) and cannot be used along with [High Availability features](/cloud/high-availability). ::: -See the documentation for [API keys](/cloud/api-keys) and [mTLS certificates](/cloud/certificates) for more information -on how to create and manage your credentials. - -Programmatically accessing your Namespace requires specific endpoints based on your authentication method. There are two -types of gRPC endpoints for accessing a Namespace in Temporal Cloud: - -- A namespace endpoint (`