Merge branch 'main' into MermaidImprovements

Author: Duncanma

docs/cloud/connectivity/aws-connectivity.mdx

@@ -43,9 +43,17 @@ After creating the PrivateLink endpoint, configure your clients to use it throug
 
 ## Requirements
 
-Your AWS PrivateLink endpoint must be in the same region as your Temporal Cloud namespace. If using [replication for High Availability](/cloud/high-availability), the PL connection must be in the same region as one of the replicas.
+* Your AWS PrivateLink (PL) endpoint must be in the same region as your Temporal Cloud Namespace or one of its [High Availability](/cloud/high-availability) replicas.
+  See [cross-region PrivateLink connectivity](#cross-region-privatelink) to access the Namespace from a different region.
+* Your Private DNS must be configured to direct Worker / Client traffic to your VPC Endpoint, as described below.
+* If the Worker / Client does not use the Namespace Endpoint as the connection string in its code, it may need to set the `server_name` config to the Namespace Endpoint string, as described below.
 
-AWS Cross Region endpoints are not supported.
+### Cross-region PrivateLink Connectivity {/* #cross-region-privatelink */}
+
+Temporal Cloud does **not** support [cross-region connectivity for AWS PrivateLink](https://aws.amazon.com/blogs/networking-and-content-delivery/introducing-cross-region-connectivity-for-aws-privatelink/) out of the box. However, if you need to reach Temporal Cloud privately from a different region than your Namespace, you can route traffic to your VPC Endpoint in the Namespace's region using [AWS's native cross-region networking features](https://docs.aws.amazon.com/whitepapers/latest/building-scalable-secure-multi-vpc-network-infrastructure/centralized-access-to-vpc-private-endpoints.html#cross-region-endpoint-access). 
+
+
+When using High Availability on Temporal Cloud, it's best practice to have two VPC Endpoints, one in each of the Namespace's regions, to ensure at least one VPC Endpoint is accessible during a regional outage.
 
 ## Creating an AWS PrivateLink connection
 
@@ -68,7 +76,7 @@ Individual Namespaces do not use separate services.
 
 :::
 
-<JsonTable filename="/json/privatelink_aws.json" />
+<JsonTable filename="/json/privatelink_services_aws.json" />
 
 7. Confirm your service by clicking on the _Verify service_ button. AWS should respond "Service name verified."
 
@@ -118,14 +126,14 @@ This approach is **optional**; Temporal Cloud works without it. It simply stream
 
 ### Choose the override domain and endpoint
 
-| Endpoint type      | PHZ domain format                     | Example                                 | Use when |
-| ------------------ | ------------------------------------- | --------------------------------------- | -------- |
-| Namespace endpoint | `<namespace-id>.tmprl.cloud`          | `payments.abcde.tmprl.cloud`            | **Single-region Namespaces only.** Simplest pattern — one record per Namespace. Do not use this for [High Availability](/cloud/high-availability/ha-connectivity) Namespaces: the override short-circuits Temporal's regional CNAME chain and failover stops working. |
-| Regional endpoint  | `<cloud>-<region>.region.tmprl.cloud` | `aws-ap-northeast-2.region.tmprl.cloud` | **Single-region or HA Namespaces.** One record per Temporal Cloud region, reused by every Namespace active or replicated in that region. **Required for HA Namespaces** — see [Connectivity for High Availability](/cloud/high-availability/ha-connectivity). |
+| Endpoint type      | PHZ domain format                  | Example                              | Use when |
+| ------------------ | ---------------------------------- | ------------------------------------ | -------- |
+| Namespace endpoint | `<namespace-id>.tmprl.cloud`       | `payments.abcde.tmprl.cloud`         | **Single-region Namespaces.** Simplest pattern — one record per Namespace. For [High Availability](/cloud/high-availability/ha-connectivity) Namespaces, overriding the Namespace Endpoint is nuanced — see [Connectivity for High Availability](/cloud/high-availability/ha-connectivity). |
+| Regional endpoint  | `<region>.<cloud>.api.temporal.io` | `ap-northeast-2.aws.api.temporal.io` | You want to pin a client to a specific Temporal Cloud region. |
 
-:::warning HA Namespaces require the regional override
+:::caution HA Namespaces need a more nuanced PHZ setup
 
-For Namespaces with [High Availability](/cloud/high-availability/ha-connectivity), use the regional-endpoint PHZ pattern only. The Namespace-endpoint override is read out of the PHZ before public DNS, so the regional CNAME that Temporal Cloud rewrites on failover is never followed and Workers stay pinned to the old region. If you're switching an existing single-region private Namespace to HA, see [How to enable HA on a Namespace using Private Connectivity](/cloud/high-availability/ha-connectivity#how-to-enable-ha-on-a-namespace-using-private-connectivity) for the PHZ migration steps.
+For Namespaces with [High Availability](/cloud/high-availability/ha-connectivity), the PHZ pattern to use depends on how you want Workers to reach the active region. Overriding the Namespace Endpoint directly is read out of the PHZ before public DNS, so the regional CNAME that Temporal Cloud rewrites on failover isn't followed — which is usually not what you want, but can be the right choice in some topologies (for example, multi-cloud HA with one region per cloud, where Workers on each cloud should always reach their local region). Because the trade-offs depend on your setup, see [Connectivity for High Availability](/cloud/high-availability/ha-connectivity) before choosing a pattern.
 
 :::
 

docs/cloud/connectivity/gcp-connectivity.mdx

@@ -29,6 +29,8 @@ This one-way connection means Temporal cannot establish a connection back to you
 This is useful if normally you block traffic egress as part of your security protocols.
 If you use a private environment that does not allow external connectivity, you will remain isolated.
 
+<a id="high-availability-and-private-service-connect"></a>
+
 :::warning Namespaces with High Availability features and GCP Private Service Connect
 
 Automatic failover via Temporal Cloud DNS is not currently supported with GCP Private Service Connect.
@@ -38,7 +40,9 @@ If you use GCP Private Service Connect, you must manually update your workers to
 
 ## Requirements
 
-Your GCP Private Service Connect connection must be in the same region as your Temporal Cloud namespace. If using [replication for High Availability](/cloud/high-availability), the PSC connection must be in the same region as one of the replicas.
+* Your GCP Private Service Connect endpoint must be in the same region as your Temporal Cloud namespace. If using [replication for High Availability](/cloud/high-availability), the PSC connection must be in the same region as one of the replicas.
+* Your Private DNS must be configured to direct Worker / Client traffic to your PSC endpoint, as described below.
+* If the Worker / Client is not using the Namespace Endpoint, it may need to set the `server_name` config to the Namespace Endpoint string, as described below.
 
 ## Creating a Private Service Connect connection
 
@@ -131,7 +135,7 @@ This approach is **optional**; Temporal Cloud works without it. It simply stream
 | ------------------------------------------ | ---------------------------------- | ---------------------------------------------- |
 | Single-region namespace with mTLS auth     | `<account>.tmprl.cloud`            | `payments.abcde.tmprl.cloud` ↔ `X.X.X.X`       |
 | Single-region namespace with API-key auth  | `<cloud_provider>.api.temporal.io` | `us-central1.gcp.api.temporal.io` ↔ `X.X.X.X`  |
-| Multi-region namespace | `region.tmprl.cloud`               | `gcp-us-central1.region.tmprl.cloud` ↔ `X.X.X.X` |
+| Multi-region namespace | `<cloud_provider>.api.temporal.io` | `us-central1.gcp.api.temporal.io` ↔ `X.X.X.X` |
 
 ### Step-by-step instructions
 
@@ -152,7 +156,7 @@ Save the internal IP -- you will point the A record at it.
 1. Open _Network Services → Cloud DNS → Create zone_.
 2. Select zone type **Private**.
 3. Enter a **Zone name** (e.g., `temporal-cloud`).
-4. Enter a **DNS name** based on the table above (e.g., `payments.abcde.tmprl.cloud` or `aws-us-east-1.region.tmprl.cloud`).
+4. Enter a **DNS name** based on the table above (e.g., `payments.abcde.tmprl.cloud` or `us-east-1.aws.api.temporal.io`).
 5. Select **Add networks** and choose the Project and Network that contains your PSC endpoint.
 6. Click **Create**.
 

docs/cloud/connectivity/index.mdx

@@ -233,7 +233,7 @@ The TLS server name override depends on your authentication method:
 | -------------- | ---------------------- |
 | mTLS (single-region Namespace) | The Namespace Endpoint, e.g. `my-namespace.my-account.tmprl.cloud` |
 | API key (single-region Namespace) | The regional API endpoint, e.g. `us-east-1.aws.api.temporal.io` or `us-central1.gcp.api.temporal.io` |
-| Multi-region Namespace (mTLS or API key) | The active region endpoint, e.g. `aws-us-east-1.region.tmprl.cloud` |
+| Multi-region Namespace (mTLS or API key) | The active region endpoint, e.g. `us-east-1.aws.api.temporal.io` |
 
 If you authenticate with an API key over PrivateLink/PSC and use the wrong server name, the TLS handshake will fail with errors such as `connection reset by peer` even though `nc` reports the port as open.
 

docs/cloud/connectivity/ip-addresses.mdx

@@ -341,6 +341,11 @@ IP addresses are provided in IPv4 or IPv6 format with CIDR notation. At launch,
 
 :::
 
+:::note Don't depend on DNS resolution behavior
+
+Take a dependency on Temporal's published endpoints (the hostnames themselves), not on what they resolve to. The underlying IP addresses, CNAME chains, and resolution behavior can change at any time without notice. The **only** exception is the Namespace Endpoint for a Namespace with [High Availability features](/cloud/high-availability), which deterministically CNAMEs to its active region's regional record — see [Connectivity for High Availability](/cloud/high-availability/ha-connectivity) for details.
+
+:::
 ### How to connect using Stable IPs
 
 To connect to a Namespace with Stable IPs enabled: