Fixing errors about Namespace connectivity and best practices #4127

lukeknep · 2026-01-17T00:29:37Z

What does this PR do?

Fixes some errors on the Namespace "General Guidance" section and on the "Connecting to your Namespace" section.

Notes to reviewers

Product owner for Connectivity is @lukeknep
Product owner for Nexus is @prasek

vercel · 2026-01-17T00:29:42Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
temporal-documentation	Error		Jan 20, 2026 7:03pm

github-actions · 2026-01-17T00:30:03Z

📖 Docs PR preview links

Cloud
- High Availability
  - Enable High Availability
- Namespaces
Namespace

meiliang86 · 2026-01-17T00:58:30Z

docs/cloud/get-started/namespaces.mdx

+- 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 [Workflow Id](/workflow-execution/workflowid-runid#workflow-id) in a Namespace must be unique. Workflow Ids in different Namespaces may be the same.


Should probably point out that only open workflow requires this uniqueness constraints. You can have multiple closed workflows with the same ID.

oh good to know!

bechols

Lots of small comments/suggestions, but this is a big improvement.

bechols · 2026-01-17T00:46:55Z

docs/cloud/get-started/namespaces.mdx

-  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.
+  the system.
+  - Each Namespace's default limit is set at 400 APS and automatically adjusts based on recent usage (over the


I think default APS limit is 500 now - updated as we're rolling out capacity units. Worth double checking with TLo but good to fix since we're touching the line.

bechols · 2026-01-17T00:47:28Z

docs/cloud/get-started/namespaces.mdx

  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
+- A Namespace is provisioned with [endpoints](constraints-and-limitations) for executing your Workflows. Accessing a Namespace from a Worker or Temporal Client


Suggested change

- A Namespace is provisioned with [endpoints](constraints-and-limitations) for executing your Workflows. Accessing a Namespace from a Worker or Temporal Client

- A Namespace exposes [endpoints](#access-namespaces) for executing your Workflows. Accessing a Namespace from a Worker or Temporal Client

bechols · 2026-01-17T00:48:04Z

docs/cloud/get-started/namespaces.mdx

+- 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 [Workflow Id](/workflow-execution/workflowid-runid#workflow-id) in a Namespace must be unique. Workflow Ids in different Namespaces may be the same.


Do we use Id (rather than ID) everywhere?

ah no, we use ID

bechols · 2026-01-17T00:49:18Z

docs/cloud/get-started/namespaces.mdx

 - 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.
+- Environments such as production and development usually have requirements for isolation. We recommend that each


Link to (and/or replace in favor of) https://docs.temporal.io/best-practices/managing-namespace#organizational-patterns ?

oh yes definitely, this entire section should be taken out and just linked to that ^ much better one

docs/cloud/get-started/namespaces.mdx

bechols · 2026-01-17T00:51:16Z

docs/cloud/get-started/namespaces.mdx

+        - This endpoint is unique to each Namespace. It will always connect to the Namespace, no matter which region(s) the Namespace is using. (Recommended for Namespaces with High Availability)
+        - A Temporal Client that uses a Namespace endpoint doesn't have to be aware of which region the Namespace is in.
+    - Restrictions:
+        - If [High Availability](/cloud/high-availability) is not enabled, then accessing a Namespace via API key + Namespace endpoint is not supported. To use the Namespace endpoint with API keys, a Namespace must have [High Availability](/cloud/high-availability) enabled.


But this is changing soon, right?

docs/cloud/get-started/namespaces.mdx

bechols · 2026-01-17T00:56:48Z

docs/cloud/get-started/namespaces.mdx

+### Configuring a Temporal Client with API keys or mTLS

- To use API keys to connect with the [Temporal CLI](/cli), [Client SDK](/develop), [tcld](/cloud/tcld),
+To use API keys to connect with the [Temporal CLI](/cli), [Client SDK](/develop), [tcld](/cloud/tcld),


Minor: risk of drift vs the list at https://docs.temporal.io/cloud/api-keys#api-key-supported-tooling

docs/cloud/get-started/namespaces.mdx

bechols · 2026-01-17T00:59:18Z

docs/cloud/get-started/namespaces.mdx

- Set up your allow list for outgoing network requests from your Clients and Workers with the IP address ranges of the
+For enhanced protection:
+- Set up [private connectivity](/cloud/connectivity#private-network-connectivity-for-namespaces) to the Namespace.
+- In your own networking architecture, set up an allow list for outgoing network requests from your Clients and Workers with the IP address ranges of the


Needs to cover multiple regions if it's a HA namespace

daniel-goldstein · 2026-01-20T17:35:33Z

docs/cloud/get-started/namespaces.mdx

+        - Temporal Cloud has only one regional endpoint for each cloud region. The same regional endpoint can access any Namespace that is active in that region (or that has a [replica](/cloud/high-availability) in that region).
+        - A Temporal Client can use a regional endpoint to ensure connection to a Namespace always happens within that region.
+    - Restrictions:
+        - When using mTLS to authenticate, the Temporal Client must set the `server_name` property in its request to the value of the Namespace endpoint.


I'm not able to easily ctrl+f the linked docs for occurrences of server_name. Should we instead say that the "Temporal Client must override the Server Name Indication (SNI) in its TLS configuration to the value of the Namespace endpoint", perhaps linking to an example, and then refer to SNI later in this doc?

I will attempt to rewrite

daniel-goldstein · 2026-01-20T17:35:48Z

Left one comment inline otherwise LGTM

Co-authored-by: Ben Echols <benjamin.echols@temporal.io>

bechols · 2026-01-20T22:57:55Z

docs/encyclopedia/namespaces/namespaces.mdx


- **Workflow ID uniqueness**: Temporal guarantees a unique Workflow Id within a Namespace.
-  Workflow Executions may have the same Workflow Id if they are in different Namespaces.
+- **Workflow ID uniqueness**: Temporal guarantees that each running Workflow Exeecution within a Namespace has a unique Workflow ID.


Typo: "Exeecution" should be "Execution"

Suggested change

- **Workflow ID uniqueness**: Temporal guarantees that each running Workflow Exeecution within a Namespace has a unique Workflow ID.

- **Workflow ID uniqueness**: Temporal guarantees that each running Workflow Execution within a Namespace has a unique Workflow ID.

docs/cloud/get-started/namespaces.mdx

bechols · 2026-01-20T22:58:00Z

docs/cloud/high-availability/enable.mdx

 There are charges associated with Replication and enabling High Availability features. For pricing details, visit
 Temporal Cloud's [Pricing](/cloud/pricing) page.

+If the Namespace's APS limit has been raised above the [default limit](https://docs.temporal.io/cloud/namespaces#constraints-and-limitations), then it will require a support ticket to to add a replica. Support will ensure that Temporal Cloud has capacity in the replica's region to handle the additional APS. Please


Two issues on this line:

Duplicate word: "to to add" should be "to add"

Not ideal link: suggest using /cloud/capacity-modes#namespace-capacity instead

Suggested change

If the Namespace's APS limit has been raised above the [default limit](https://docs.temporal.io/cloud/namespaces#constraints-and-limitations), then it will require a support ticket to to add a replica. Support will ensure that Temporal Cloud has capacity in the replica's region to handle the additional APS. Please

If the Namespace's APS limit has been raised above the [default limit](/cloud/capacity-modes#namespace-capacity), then it will require a support ticket to add a replica. Support will ensure that Temporal Cloud has capacity in the replica's region to handle the additional APS. Please

bechols · 2026-01-20T22:58:03Z

docs/cloud/get-started/namespaces.mdx

+        - Temporal Cloud has only one regional endpoint for each cloud region. The same regional endpoint can access any Namespace that is active in that region (or that has a [replica](/cloud/high-availability) in that region).
+        - A Temporal Client can use a regional endpoint to ensure connection to a Namespace always happens within that region.
+    - Restrictions:
+        - When using mTLS to authenticate, the Temporal Client override the Server Name Indication (SNI) in the TLS configuration with the value of the Namespace endpoint.


Grammar: "the Temporal Client override" should be "the Temporal Client must override"

Suggested change

- When using mTLS to authenticate, the Temporal Client override the Server Name Indication (SNI) in the TLS configuration with the value of the Namespace endpoint.

- When using mTLS to authenticate, the Temporal Client must override the Server Name Indication (SNI) in the TLS configuration with the value of the Namespace endpoint.

bechols · 2026-01-20T22:58:05Z

docs/cloud/get-started/namespaces.mdx

+    - Restrictions:
+        - When using mTLS to authenticate, the Temporal Client override the Server Name Indication (SNI) in the TLS configuration with the value of the Namespace endpoint.
+          In the Temporal SDKs, this can be done using the "TLS Server Name" property in requests to Temporal Cloud.
+          For example, in the [Temporal CLI](/cloud/certificates#configure-temporal-cli, this can be done by using `TEMPORAL_TLS_SERVER_NAME=<namespace endpoint>` or `--tls-server-name <namespace endpoint>`.


Broken markdown link: Missing closing parenthesis. Should be [Temporal CLI](/cloud/certificates#configure-temporal-cli) (note the closing ) before the comma).

Suggested change

For example, in the [Temporal CLI](/cloud/certificates#configure-temporal-cli, this can be done by using `TEMPORAL_TLS_SERVER_NAME=<namespace endpoint>` or `--tls-server-name <namespace endpoint>`.

For example, in the [Temporal CLI](/cloud/certificates#configure-temporal-cli), this can be done by using `TEMPORAL_TLS_SERVER_NAME=<namespace endpoint>` or `--tls-server-name <namespace endpoint>`.

Fixing errors about Namespace connectivity and best practices

6b2bc84

lukeknep requested a review from a team as a code owner January 17, 2026 00:29

lukeknep requested a review from daniel-goldstein January 17, 2026 00:30

Adding a replica to a high APS Namespace requires a support ticket

79d1b5f

vercel bot had a problem deploying to Preview January 17, 2026 00:41 Failure

meiliang86 reviewed Jan 17, 2026

View reviewed changes

bechols approved these changes Jan 17, 2026

View reviewed changes

daniel-goldstein reviewed Jan 20, 2026

View reviewed changes

lukeknep and others added 2 commits January 20, 2026 11:00

Apply suggestions from code review

061a50d

Co-authored-by: Ben Echols <benjamin.echols@temporal.io>

Cleaning up with review comments

575d7df

vercel bot had a problem deploying to Preview January 20, 2026 19:03 Failure

bechols reviewed Jan 20, 2026

View reviewed changes

docs/cloud/get-started/namespaces.mdx Show resolved Hide resolved

bechols reviewed Jan 20, 2026

View reviewed changes

	- A Namespace is provisioned with [endpoints](constraints-and-limitations) for executing your Workflows. Accessing a Namespace from a Worker or Temporal Client
	- A Namespace exposes [endpoints](#access-namespaces) for executing your Workflows. Accessing a Namespace from a Worker or Temporal Client

	- Workflow ID uniqueness: Temporal guarantees that each running Workflow Exeecution within a Namespace has a unique Workflow ID.
	- Workflow ID uniqueness: Temporal guarantees that each running Workflow Execution within a Namespace has a unique Workflow ID.

	If the Namespace's APS limit has been raised above the [default limit](https://docs.temporal.io/cloud/namespaces#constraints-and-limitations), then it will require a support ticket to to add a replica. Support will ensure that Temporal Cloud has capacity in the replica's region to handle the additional APS. Please
	If the Namespace's APS limit has been raised above the [default limit](/cloud/capacity-modes#namespace-capacity), then it will require a support ticket to add a replica. Support will ensure that Temporal Cloud has capacity in the replica's region to handle the additional APS. Please

	- When using mTLS to authenticate, the Temporal Client override the Server Name Indication (SNI) in the TLS configuration with the value of the Namespace endpoint.
	- When using mTLS to authenticate, the Temporal Client must override the Server Name Indication (SNI) in the TLS configuration with the value of the Namespace endpoint.

	For example, in the [Temporal CLI](/cloud/certificates#configure-temporal-cli, this can be done by using `TEMPORAL_TLS_SERVER_NAME=<namespace endpoint>` or `--tls-server-name <namespace endpoint>`.
	For example, in the [Temporal CLI](/cloud/certificates#configure-temporal-cli), this can be done by using `TEMPORAL_TLS_SERVER_NAME=<namespace endpoint>` or `--tls-server-name <namespace endpoint>`.

Fixing errors about Namespace connectivity and best practices #4127

Are you sure you want to change the base?

Fixing errors about Namespace connectivity and best practices #4127

Uh oh!

Conversation

lukeknep commented Jan 17, 2026 • edited by sync-by-unito bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Notes to reviewers

Uh oh!

vercel bot commented Jan 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📖 Docs PR preview links

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bechols left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bechols Jan 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

daniel-goldstein Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

daniel-goldstein commented Jan 20, 2026

Uh oh!

bechols Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bechols Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bechols Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bechols Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

lukeknep commented Jan 17, 2026 •

edited by sync-by-unito bot

Loading

vercel bot commented Jan 17, 2026 •

edited

Loading

github-actions bot commented Jan 17, 2026 •

edited

Loading

bechols Jan 17, 2026 •

edited

Loading

daniel-goldstein Jan 20, 2026 •

edited

Loading

bechols Jan 20, 2026 •

edited

Loading

bechols Jan 20, 2026 •

edited

Loading

bechols Jan 20, 2026 •

edited

Loading

bechols Jan 20, 2026 •

edited

Loading