Clarify AWS PL DNS instructions for single region vs. HA

docs/cloud/connectivity/aws-connectivity.mdx

@@ -108,10 +108,18 @@ This approach is **optional**; Temporal Cloud works without it. It simply stream
 
 ### Choose the override domain and endpoint
 
-| Endpoint type      | PHZ domain format                  | Example                                |
-| ------------------ | ---------------------------------- | -------------------------------------- |
-| Namespace endpoint | `<namespace-id>.tmprl.cloud`       | `payments.abcde.tmprl.cloud`           |
-| Regional endpoint  | `<cloud>-<region>.region.tmprl.cloud` | `aws-ap-northeast-2.region.tmprl.cloud` |
+| 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). |
+
+:::warning HA Namespaces require the regional override
+
+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.
+
+:::
+
+The step-by-step below walks through the **Namespace endpoint** pattern, which is the simpler single-region case. For HA, follow the [HA Connectivity guide](/cloud/high-availability/ha-connectivity) instead, which uses the same Route 53 mechanics but on the regional records.
 
 ### Step-by-step instructions
 

docs/cloud/high-availability/ha-connectivity.mdx

@@ -103,12 +103,82 @@ For private connectivity, your job is to make sure that:
 - Override the Regional Endpoint's DNS zone to resolve to a VPC Endpoint.
 - Ensure network connectivity between the two regions.
 
+:::warning Do not override the Namespace Endpoint in your private hosted zone
+
+For HA Namespaces, the PHZ must override only the regional records (`<provider>-<region>.region.tmprl.cloud`) — never the Namespace Endpoint itself (`<ns>.<account>.tmprl.cloud`).
+
+If the PHZ holds a record for the Namespace Endpoint, the resolver answers from the PHZ before consulting public DNS, so Temporal Cloud's active-region CNAME is never followed. On failover, Workers keep resolving to the old (now passive) region's VPC Endpoint and never reach the new active region.
+
+This matters most when **enabling HA on a Namespace that previously used the [single-region PHZ pattern](/cloud/connectivity/aws-connectivity#configuring-private-dns-for-aws-privatelink)**, where the Namespace Endpoint itself was the overridden name. See [How to enable HA on a Namespace using Private Connectivity](#how-to-enable-ha-on-a-namespace-using-private-connectivity) below for the migration steps.
+
+:::
+
 :::warning Do not attach a Stable IPs public Connectivity Rule
 
 If you attach a public [Connectivity Rule with Stable IPs](/cloud/connectivity/ip-addresses#stable-ip-addresses) to a Namespace, the Namespace Endpoint resolves to a public Stable IP instead of to `<provider>-<region>.region.tmprl.cloud`. Stable IPs DNS behavior supersedes the regional DNS behavior described here, so the Namespace Endpoint's DNS resolution will not work in the way the Private Hosted Zone needs. To keep HA + Private Connectivity working, do not attach a Stable IPs public Connectivity Rule to that Namespace.
 
 :::
 
+## How to enable HA on a Namespace using Private Connectivity: changing private DNS overrides from single-region to multi-region {/* #how-to-enable-ha-on-a-namespace-using-private-connectivity */}
+
+If you are turning on [High Availability features](/cloud/high-availability/enable) on a Namespace that already uses AWS PrivateLink or GCP Private Service Connect, the existing private DNS setup almost certainly needs to change before failover will work.
+
+The common single-region private DNS pattern (described in the [AWS PrivateLink guide](/cloud/connectivity/aws-connectivity#configuring-private-dns-for-aws-privatelink) and the [GCP PSC guide](/cloud/connectivity/gcp-connectivity)) overrides the **Namespace Endpoint** directly. That pattern short-circuits Temporal Cloud's regional CNAME and prevents failover from working — see the warning above.
+
+Follow these steps in order to update your private DNS overrides without interrupting traffic:
+
+1. **Inventory the existing PHZ records.** List the records in your private hosted zone for `tmprl.cloud`. Note any CNAME (or A record) for `<ns>.<account>.tmprl.cloud` — that is the single-region override you'll be removing.
+
+2. **Add regional records for both the source and target HA regions.** Before removing anything, create:
+   - `aws-<source-region>.region.tmprl.cloud` → source-region VPC Endpoint
+   - `aws-<target-region>.region.tmprl.cloud` → target-region VPC Endpoint
+
+   (Or the GCP Cloud DNS equivalents — see [GCP PSC](#single-cloud-ha-on-gcp-private-service-connect) below.) These records are additive and do not yet affect resolution of `<ns>.<account>.tmprl.cloud`, because the Namespace-endpoint override still short-circuits the chain.
+
+3. **Confirm both VPC Endpoints are reachable from your Worker VPCs.** From a Worker host, `dig` the new regional names and confirm they resolve to the right VPC Endpoint. Also verify the network path actually works in both regions (security groups, route tables, cross-region connectivity).
+
+4. **Enable HA on the Namespace.** Follow [Enable High Availability features](/cloud/high-availability/enable). Temporal Cloud creates the replica and starts replicating.
+
+5. **Remove the Namespace-endpoint PHZ record.** Delete the `<ns>.<account>.tmprl.cloud` record from the PHZ. With it gone, Workers resolve the name through public DNS → regional CNAME → PHZ regional override → VPC Endpoint, which is the correct HA chain. **Do not skip this step.** If the Namespace-endpoint override remains, failover does not work.
+
+6. **Test failover end-to-end.** Use [forced failover](/cloud/high-availability/failovers) in a staging environment to confirm Workers converge to the new active region within the expected window (about 30 seconds after the public CNAME update, given the 15-second TTL).
+
+:::caution Order matters
+
+Adding the regional records first (step 2) and removing the Namespace-endpoint record last (step 5) means Workers always have a working DNS resolution. Reversing the order leaves a window where Workers cannot resolve the Namespace Endpoint at all.
+
+:::
+
+## How to migrate to another Temporal Cloud Region when using Private Connectivity {/* #how-to-migrate-regions-with-private-connectivity */}
+
+To move a Namespace to a new Temporal Cloud Region while keeping Private Connectivity in place, the recommended pattern is to use a **separate private hosted zone in each region**, each overriding the Namespace Endpoint to point at that region's own VPC Endpoint. Because a PHZ is scoped only to the VPCs it is associated with, Workers in each region resolve the Namespace Endpoint to their local VPC Endpoint and traffic stays in-region throughout the move.
+
+This is not the only way to handle a region change with Private Connectivity, but it is the most commonly used.
+
+Steps:
+
+1. **Keep the existing Namespace Endpoint PHZ override in the original region.** Do not change anything in the original region's private DNS setup yet.
+
+2. **Create a new VPC Endpoint in the new region.** Follow the [AWS PrivateLink](/cloud/connectivity/aws-connectivity) (or [GCP PSC](/cloud/connectivity/gcp-connectivity)) creation steps in the new region's VPC.
+
+3. **In the new region, create a PHZ that overrides the Namespace Endpoint to point at the new VPC Endpoint.** Use the [single-region PHZ pattern](/cloud/connectivity/aws-connectivity#configuring-private-dns-for-aws-privatelink), scoped only to the new region's Worker VPCs. With one PHZ per region, traffic in each region routes through that region's own VPC Endpoint.
+
+4. **Add a replica in the new region.** Follow [Enable High Availability features](/cloud/high-availability/enable). The new region comes up as a passive replica.
+
+5. **Start Workers in the new region.** They begin processing tasks immediately, even though they are connecting to the passive replica, because Temporal Cloud forwards Workflow and Activity tasks across regions transparently. This is what keeps the region change zero-downtime.
+
+6. **Failover to the new region.** Trigger a [forced failover](/cloud/high-availability/failovers) to make the new region active. Workers in the old region keep running and keep using the old VPC Endpoint — they now connect to the passive replica that lives in the old region, and Temporal Cloud forwards their tasks to the new active region.
+
+7. **Drain and remove Workers and the VPC Endpoint in the old region.** Once you are confident the new region is handling all new work and you no longer need old-region Workers, stop them and tear down the old region's VPC Endpoint and PHZ.
+
+8. **Remove the replica in the old region.** See [Migrate between regions](/cloud/migrate/migrate-within-cloud) for the replica-removal step. The Namespace is now single-region in the new location, and the HA pricing surcharge no longer applies.
+
+:::note Per-region PHZ vs. shared regional-record PHZ
+
+This pattern is **different** from the long-term HA setup described in [Single-cloud HA on AWS PrivateLink](#single-cloud-ha-on-aws-privatelink), which uses one shared PHZ holding regional records (`aws-<region>.region.tmprl.cloud`) and relies on DNS-based failover to switch Workers between regions. The region-change pattern instead uses one PHZ per region, each overriding the Namespace Endpoint itself, and relies on Temporal Cloud's cross-region task forwarding rather than DNS to keep Workers productive across the cutover.
+
+:::
+
 ## Single-cloud HA on AWS PrivateLink
 
 ### How Namespace DNS records work with PrivateLink

docs/cloud/migrate/migrate-within-cloud.mdx

@@ -33,6 +33,12 @@ See [failover scenarios](/cloud/export#failover-scenarios) for details.
 
 [Using High Availability features affects pricing](/cloud/pricing#high-availability-features).
 
+:::info Using AWS PrivateLink or GCP Private Service Connect?
+
+If the Namespace uses Private Connectivity, the steps below need additional DNS and VPC Endpoint work. Follow [How to migrate to another Temporal Cloud Region when using Private Connectivity](/cloud/high-availability/ha-connectivity#how-to-migrate-regions-with-private-connectivity) instead of (or alongside) the public steps below.
+
+:::
+
 ## Steps to migrate
 
 1. Add a Namespace replica in the region you want to migrate to. See [regions](/cloud/regions) for a list of available regions and supported multi-region and multi-cloud configurations.