From d82ea95b20561841550509e1406612cef793279a Mon Sep 17 00:00:00 2001 From: Luke Knepper Date: Wed, 9 Sep 2026 10:52:11 -0700 Subject: [PATCH] Recommendations for PrivateLink DNS setup. --- docs/cloud/connectivity/aws-connectivity.mdx | 64 ++++++++++++++----- docs/cloud/connectivity/gcp-connectivity.mdx | 54 +++++++++++++--- docs/cloud/connectivity/index.mdx | 20 +++++- .../high-availability/ha-connectivity.mdx | 21 ++++-- 4 files changed, 130 insertions(+), 29 deletions(-) diff --git a/docs/cloud/connectivity/aws-connectivity.mdx b/docs/cloud/connectivity/aws-connectivity.mdx index fd44d9a832..45ce388030 100644 --- a/docs/cloud/connectivity/aws-connectivity.mdx +++ b/docs/cloud/connectivity/aws-connectivity.mdx @@ -19,7 +19,7 @@ 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. -After creating the PrivateLink endpoint, configure your clients to use it through either [private DNS](#configuring-private-dns-for-aws-privatelink) or [direct VPCE targeting](#direct-vpce). Direct VPCE targeting is simplest for single-region Namespaces, but also works for High Availability Namespaces with [more careful setup](#direct-vpce). +After creating the PrivateLink endpoint, configure your clients to use it. We recommend [private DNS](#configuring-private-dns-for-aws-privatelink), which resolves your Namespace Endpoint to the VPC Endpoint and leaves Worker and Client configuration identical to the public-internet case. If you cannot run private DNS, use [direct VPCE targeting](#direct-vpce) instead, which points Workers at the VPC Endpoint and overrides the TLS server name. ## Requirements @@ -76,7 +76,7 @@ Individual Namespaces do not use separate services. ![Highlighted DNS names section shows your hostname](/img/cloud/privatelink/details.png) -The next step is to [configure private DNS](#configuring-private-dns-for-aws-privatelink) so your clients can use the PrivateLink connection. For single-region Namespaces that don't need per-Namespace DNS records, you can use [direct VPCE targeting](#direct-vpce) instead. +The next step is to [configure private DNS](#configuring-private-dns-for-aws-privatelink) so your clients can use the PrivateLink connection. ## Configuring Private DNS for AWS PrivateLink @@ -89,8 +89,9 @@ When you connect to Temporal Cloud through AWS PrivateLink you normally must: By creating a Route 53 **private hosted zone (PHZ)** that maps the public Temporal Cloud hostname (or region hostname) to your VPC Endpoint, you can: -- Keep using the standard Temporal Cloud hostnames in code and configuration. +- Keep using the standard Temporal Cloud hostnames in code and configuration, so SDK samples, demos, and existing deployments work over PrivateLink unchanged. - Eliminate the need to set a custom SNI override. +- Let Namespaces with [High Availability features](/cloud/high-availability) follow a failover to the active region's VPC Endpoint, if you use [pattern C](#choose-a-private-dns-pattern) below. - Make future Endpoint rotations transparent—only the PHZ record changes. This approach is **optional**; Temporal Cloud works without it. It simply streamlines configuration and operations. If you cannot use private DNS, refer to [our guide for updating the server and TLS settings on your clients](/cloud/connectivity#update-dns-or-clients-to-use-private-connectivity). @@ -104,20 +105,53 @@ This approach is **optional**; Temporal Cloud works without it. It simply stream | Route 53 available in your AWS account | You need permission to create Private Hosted Zones and records. | | Namespace details | Needed to choose the correct override domain pattern below. | -### Choose the override domain and endpoint +### Choose a private DNS pattern {/* #choose-a-private-dns-pattern */} -| Endpoint type | PHZ domain format | Example | Use when | -| ------------------ | ---------------------------------- | ------------------------------------ | -------- | -| Namespace endpoint | `.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 | `..api.temporal.io` | `ap-northeast-2.aws.api.temporal.io` | You want to pin a client to a specific Temporal Cloud region. | +Each pattern below resolves a Temporal Cloud hostname to your VPC Endpoint from inside your VPC, so Workers and Clients keep dialing the [Namespace Endpoint](/cloud/namespaces#access-namespaces) with no SNI override. They differ in how much per-Namespace work they take, and in what happens to Namespaces with [High Availability features](/cloud/high-availability) during a failover. -:::caution HA Namespaces need a more nuanced PHZ setup +| Pattern | PHZ domain | Record name | Use when | +| ----------------------------------- | ----------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **A. One record per Namespace** | `..tmprl.cloud` | `..tmprl.cloud` | Single-region Namespaces. Direct and predictable, at the cost of one zone and record per Namespace. | +| **B. Wildcard record** | `.tmprl.cloud` | `*..tmprl.cloud` | Single-region Namespaces, when you don't want to add a record for every new Namespace. Do not use it in a VPC that also reaches Namespaces with High Availability features. | +| **C. Regional records** | `region.tmprl.cloud` | `aws-.region.tmprl.cloud` | Namespaces with High Availability features, which are the only Namespaces this pattern supports. Keeps failover transparent to Workers. | -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. +In all three patterns the record is a `CNAME` whose value is your VPC Endpoint DNS name (`vpce-….vpce.amazonaws.com`), which resolves to that endpoint's addresses in your VPC. + +#### Pattern A: one record per Namespace + +Create a private hosted zone for the Namespace Endpoint itself and add a single `CNAME` in it. Nothing else resolves through that zone, so a mistake affects one Namespace. Follow the [step-by-step instructions](#step-by-step-instructions) below. + +#### Pattern B: wildcard record for the account + +Create one private hosted zone for `.tmprl.cloud` and add a wildcard `CNAME` at `*..tmprl.cloud`, pointing at the same VPC Endpoint DNS name. Every Namespace in the account then resolves to that VPC Endpoint, and new Namespaces work with no DNS change at all. The Route 53 mechanics are otherwise identical to pattern A. + +:::warning A wildcard blocks failover for Namespaces with High Availability features + +The wildcard also matches the Namespace Endpoint of every Namespace with [High Availability features](/cloud/high-availability) in the account. The resolver answers from the PHZ before consulting public DNS, so Temporal Cloud's active-region CNAME is never followed and Workers stay pinned to one region's VPC Endpoint. After a failover, those Workers cannot read or write in the new active region. Use pattern C for those Namespaces. + +::: + +#### Pattern C: regional records + +Create a private hosted zone for `region.tmprl.cloud` and add one `CNAME` per region, each pointing at that region's VPC Endpoint. Workers resolve `..tmprl.cloud` through public DNS to `aws-.region.tmprl.cloud`, and only then through your PHZ to a VPC Endpoint. Because the public CNAME is still followed, a failover moves Workers to the new active region's VPC Endpoint with no change on your side. + +This pattern is available only for Namespaces with High Availability features. They are the only Namespaces whose Namespace Endpoint is guaranteed to resolve through a regional record — see [Deterministic DNS behavior is unique to HA Namespace Endpoints](/cloud/high-availability/ha-connectivity). + +It also keeps Workers productive through a Temporal Cloud outage confined to one region: after the failover, Workers in the affected region resolve the Namespace Endpoint to the other region's VPC Endpoint and keep working, as long as they have a network path to it. Patterns A and B cannot do this, because they pin resolution to a single VPC Endpoint. + +For the full setup, including cross-region reachability and multi-cloud replicas, see [Connectivity for High Availability](/cloud/high-availability/ha-connectivity). + +#### Both kinds of Namespace in one VPC + +Use pattern A for the single-region Namespaces and pattern C for those with High Availability features. The two coexist: pattern A's zones name individual Namespaces, while pattern C's records live in the separate `region.tmprl.cloud` zone that only HA Namespace Endpoints resolve through. Do not add a pattern B wildcard to that VPC — it would match the HA Namespace Endpoints too. + +:::note Pinning a Client to a region + +To pin a Client to a specific Temporal Cloud region rather than following the active one, create the PHZ for the regional endpoint hostname (`..api.temporal.io`, for example `ap-northeast-2.aws.api.temporal.io`) instead. The Client dials that hostname and sets its TLS server name to the Namespace Endpoint, which gives up the configuration and failover advantages described above. ::: -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. +The step-by-step below walks through pattern A. Pattern B uses the same steps with a wildcard record name. For pattern C, follow the [HA Connectivity guide](/cloud/high-availability/ha-connectivity), which uses the same Route 53 mechanics on the regional records. ### Step-by-step instructions @@ -144,7 +178,7 @@ Save the **`vpce-*.amazonaws.com`** value — you will target it in the CNAME re #### 2. Create a Route 53 Private Hosted Zone (do not yet attach Worker VPCs) a. Open _Route 53 → Hosted zones → Create hosted zone_. -b. Enter the domain chosen from the table above, for example, `payments.abcde.tmprl.cloud`. +b. Enter the domain chosen from the table above: `payments.abcde.tmprl.cloud` for pattern A or `abcde.tmprl.cloud` for a pattern B wildcard. c. Type: _Private hosted zone for Temporal Cloud_. d. Leave VPC associations empty for now (you'll add them in step 4). e. Create the hosted zone. @@ -155,7 +189,7 @@ Inside the new PHZ: | Field | Value | | --------------- | ------------------------------------------------------------------------------------- | -| **Record name** | the Namespace Endpoint (for example, `payments.abcde.tmprl.cloud`). | +| **Record name** | The Namespace Endpoint (for example, `payments.abcde.tmprl.cloud`) or `*.abcde.tmprl.cloud` for a pattern B wildcard. | | **Record type** | `CNAME` | | **Value** | Your VPC Endpoint DNS name (`vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com`) | | **TTL** | 60s is typical; 15s for Namespaces with High Availability (to minimize recovery time after failover). | @@ -194,13 +228,13 @@ The DNS resolver inside your VPC returns the private endpoint, while TLS still v ## Configure private DNS for Namespaces with High Availability -For Namespaces with [High Availability features](/cloud/high-availability), you need to override DNS for `region.tmprl.cloud` so each region resolves to the local VPC Endpoint, and you need to ensure Workers can reach whichever region is active. Failover is transparent to clients only when this is set up correctly. +For Namespaces with [High Availability features](/cloud/high-availability), use [pattern C](#choose-a-private-dns-pattern): override DNS for `region.tmprl.cloud` so each region resolves to the local VPC Endpoint, and make sure Workers can reach whichever region is active. Failover is transparent to clients only when this is set up correctly. The complete guidance — including single-cloud (AWS-only) HA, multi-cloud HA (AWS PrivateLink + GCP Private Service Connect), and a recommended failover-testing plan — lives on a single page: [Connectivity for High Availability](/cloud/high-availability/ha-connectivity). ## Direct VPCE targeting without per-Namespace DNS {/* #direct-vpce */} -You can avoid creating DNS records for each Namespace by pointing Workers directly at the VPC Endpoint and overriding the TLS Server Name Indicator (SNI): +If you cannot run private DNS in your VPC, point Workers directly at the VPC Endpoint and override the TLS Server Name Indicator (SNI). This also avoids creating a DNS record per Namespace, though a [pattern B wildcard](#choose-a-private-dns-pattern) does that without changing Client configuration: 1. Create the PrivateLink VPC Endpoint (one per region — all Namespaces in that region share it). 2. Configure each Worker with: diff --git a/docs/cloud/connectivity/gcp-connectivity.mdx b/docs/cloud/connectivity/gcp-connectivity.mdx index 5c81fe3619..1d08a7ff4e 100644 --- a/docs/cloud/connectivity/gcp-connectivity.mdx +++ b/docs/cloud/connectivity/gcp-connectivity.mdx @@ -104,7 +104,7 @@ When you connect to Temporal Cloud through GCP Private Service Connect you norma By creating a **private Cloud DNS zone (PZ)** that maps the public Temporal Cloud hostname (or the region hostname) directly to the PSC endpoint IP address, you can: -- Keep using the standard Temporal Cloud hostnames in code and configuration. +- Keep using the standard Temporal Cloud hostnames in code and configuration, so SDK samples, demos, and existing deployments work over Private Service Connect unchanged. - Eliminate the need to set a custom SNI override. - Make future endpoint rotations transparent—only the DNS record changes. @@ -119,13 +119,49 @@ This approach is **optional**; Temporal Cloud works without it. It simply stream | Cloud DNS API enabled and roles/dns.admin permissions | Needed to create private zones and records. | | Namespace details | Determines which hostname pattern you override (table below). | -### Choose the override domain and endpoint +### Choose a private DNS pattern {/* #choose-a-private-dns-pattern */} -| Temporal Cloud setup | Use this PHZ domain | Example | -| ------------------------------------------ | ---------------------------------- | ---------------------------------------------- | -| Single-region namespace with mTLS auth | `.tmprl.cloud` | `payments.abcde.tmprl.cloud` ↔️ `X.X.X.X` | -| Single-region namespace with API-key auth | `.api.temporal.io` | `us-central1.gcp.api.temporal.io` ↔️ `X.X.X.X` | -| Multi-region namespace | `.api.temporal.io` | `us-central1.gcp.api.temporal.io` ↔️ `X.X.X.X` | +Each pattern below resolves a Temporal Cloud hostname to your Private Service Connect endpoint from inside your network, so Workers and Clients keep dialing the [Namespace Endpoint](/cloud/namespaces#access-namespaces) with no SNI override. They differ in how much per-Namespace work they take, and in what happens to Namespaces with [High Availability features](/cloud/high-availability) during a failover. + +| Pattern | Private zone DNS name | Record name | Use when | +| ------------------------------- | ----------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **A. One record per Namespace** | `..tmprl.cloud` | `..tmprl.cloud` | Single-region Namespaces. Direct and predictable, at the cost of one zone and record per Namespace. | +| **B. Wildcard record** | `.tmprl.cloud` | `*..tmprl.cloud` | Single-region Namespaces, when you don't want to add a record for every new Namespace. Do not use it in a network that also reaches Namespaces with High Availability features. | +| **C. Regional records** | `region.tmprl.cloud` | `gcp-.region.tmprl.cloud` | Namespaces with High Availability features, which are the only Namespaces this pattern supports. See the [failover limitation](#high-availability-and-private-service-connect) above. | + +In all three patterns the record is an `A` record whose value is the internal IP address of your PSC endpoint. + +#### Pattern A: one record per Namespace + +Create a private zone for the Namespace Endpoint itself and add a single `A` record in it. Nothing else resolves through that zone, so a mistake affects one Namespace. Follow the [step-by-step instructions](#step-by-step-instructions) below. + +#### Pattern B: wildcard record for the account + +Create one private zone for `.tmprl.cloud` and add a wildcard `A` record at `*..tmprl.cloud`, pointing at the same PSC endpoint IP address. Every Namespace in the account then resolves to that endpoint, and new Namespaces work with no DNS change at all. The Cloud DNS mechanics are otherwise identical to pattern A. + +:::warning A wildcard blocks failover for Namespaces with High Availability features + +The wildcard also matches the Namespace Endpoint of every Namespace with [High Availability features](/cloud/high-availability) in the account. The resolver answers from the private zone before consulting public DNS, so Temporal Cloud's active-region CNAME is never followed and Workers stay pinned to one region's PSC endpoint. After a failover, those Workers cannot read or write in the new active region. Use pattern C for those Namespaces. + +::: + +#### Pattern C: regional records + +Create a private zone for `region.tmprl.cloud` and add one `A` record per region, each pointing at that region's PSC endpoint IP address. Workers resolve `..tmprl.cloud` through public DNS to `gcp-.region.tmprl.cloud`, and only then through your private zone to a PSC endpoint. Because the public CNAME is still followed, resolution tracks the active region rather than pinning to one endpoint. + +This pattern is available only for Namespaces with High Availability features. They are the only Namespaces whose Namespace Endpoint is guaranteed to resolve through a regional record — see [Deterministic DNS behavior is unique to HA Namespace Endpoints](/cloud/high-availability/ha-connectivity). + +For the full setup, including cross-region reachability and multi-cloud replicas, see [Connectivity for High Availability](/cloud/high-availability/ha-connectivity), and note the [PSC failover limitation](#high-availability-and-private-service-connect) above. + +#### Both kinds of Namespace in one network + +Use pattern A for the single-region Namespaces and pattern C for those with High Availability features. The two coexist: pattern A's zones name individual Namespaces, while pattern C's records live in the separate `region.tmprl.cloud` zone that only HA Namespace Endpoints resolve through. Do not add a pattern B wildcard to that network — it would match the HA Namespace Endpoints too. + +:::note Pinning a Client to a region + +To pin a Client to a specific Temporal Cloud region rather than following the active one, create the private zone for the regional endpoint hostname (`..api.temporal.io`, for example `us-central1.gcp.api.temporal.io`) instead. The Client dials that hostname and sets its TLS server name to the Namespace Endpoint, which gives up the configuration and failover advantages described above. + +::: ### Step-by-step instructions @@ -146,7 +182,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** (for example, `temporal-cloud`). -4. Enter a **DNS name** based on the table above (for example, `payments.abcde.tmprl.cloud` or `us-east-1.aws.api.temporal.io`). +4. Enter a **DNS name** based on the table above: `payments.abcde.tmprl.cloud` for pattern A or `abcde.tmprl.cloud` for a pattern B wildcard. 5. Select **Add networks** and choose the Project and Network that contains your PSC endpoint. 6. Click **Create**. @@ -156,7 +192,7 @@ Inside the new zone, add a _standard A record_: | Field | Value | | -------------------- | -------------------------------------------------------------- | -| DNS name | the namespace endpoint (for example, `payments.abcde.tmprl.cloud`) | +| DNS name | The Namespace Endpoint (for example, `payments.abcde.tmprl.cloud`) or `*.abcde.tmprl.cloud` for a pattern B wildcard. | | Resource record type | A | | TTL | 60s is typical, but you can adjust as needed. | | IPv4 Address | the internal IP address of your PSC endpoint (for example, `10.1.2.3`) | diff --git a/docs/cloud/connectivity/index.mdx b/docs/cloud/connectivity/index.mdx index 976a607d9e..ee7c3abd00 100644 --- a/docs/cloud/connectivity/index.mdx +++ b/docs/cloud/connectivity/index.mdx @@ -19,6 +19,12 @@ Temporal Cloud supports private connectivity to Namespaces via AWS PrivateLink o Namespace access is always securely authenticated via [API keys](/cloud/api-keys#overview) or [mTLS](/cloud/certificates), regardless of how you choose to connect. +:::info "Private Endpoint" in this documentation + +On pages that cover more than one cloud provider, **Private Endpoint** means the endpoint you create and own in your own network to reach Temporal Cloud over a private connection. Each provider names it differently: it is a **VPC Endpoint** on AWS and a **Private Service Connect endpoint** on GCP. Pages specific to one provider use that provider's term. + +::: + For information about IP address stability and allowlisting, see [IP addresses](/cloud/connectivity/ip-addresses). If your security team requires allowlisting specific IP addresses for firewall rules, Temporal Cloud also offers a [Stable IPs configuration option](/cloud/connectivity/ip-addresses) that provides non-changing IP addresses for your Namespace endpoint. ### Required steps @@ -45,6 +51,18 @@ If that's not an option for you, refer to [our guide for updating the server and ::: +### Recommended: keep Clients on the Namespace Endpoint + +For step 2, we recommend private DNS that resolves your [Namespace Endpoint](/cloud/namespaces#access-namespaces) (`..tmprl.cloud`) to your Private Endpoint, rather than reconfiguring Clients to dial the Private Endpoint directly. Two things follow from that: + +- **Clients keep the settings they already use.** The address and TLS configuration are the same as they would be over the public internet, so every SDK sample, demo, and existing deployment works unchanged, and no TLS server name (SNI) override is needed. The hostname the Client dials is still the hostname on the certificate Temporal Cloud presents. +- **Namespaces with High Availability features can follow a failover.** Temporal Cloud repoints the Namespace Endpoint at the active region, so Workers reach whichever region is active without a configuration change. Getting that behavior over a private connection depends on which private DNS pattern you choose. + +There is more than one way to build that private DNS, and the right choice depends on whether the Namespaces reached from that network use [High Availability features](/cloud/high-availability). Compare the patterns for your provider: + +- [Choose a private DNS pattern for AWS PrivateLink](/cloud/connectivity/aws-connectivity#choose-a-private-dns-pattern) +- [Choose a private DNS pattern for GCP Private Service Connect](/cloud/connectivity/gcp-connectivity#choose-a-private-dns-pattern) + For step 3, keep reading for details on [Connectivity Rules](/cloud/connectivity#connectivity-rules). ## Connectivity rules @@ -289,7 +307,7 @@ tcld connectivity-rule list -n "my-namespace.abc123" ## Update DNS or clients to use private connectivity -We strongly recommend using private DNS instead of updating client server and TLS settings: +We strongly recommend using private DNS instead of updating client server and TLS settings, so that Clients [keep using the Namespace Endpoint](#recommended-keep-clients-on-the-namespace-endpoint): - [How to set up private DNS in AWS](/cloud/connectivity/aws-connectivity#configuring-private-dns-for-aws-privatelink) - [How to set up private DNS in GCP](/cloud/connectivity/gcp-connectivity#configuring-private-dns-for-gcp-private-service-connect) diff --git a/docs/cloud/high-availability/ha-connectivity.mdx b/docs/cloud/high-availability/ha-connectivity.mdx index c15c3d7f88..e3d4734110 100644 --- a/docs/cloud/high-availability/ha-connectivity.mdx +++ b/docs/cloud/high-availability/ha-connectivity.mdx @@ -108,6 +108,12 @@ This section describes how to configure routing for Namespaces with High Availab These instructions assume you already have the private connections in place. If not, follow the [AWS PrivateLink](/cloud/connectivity/aws-connectivity) or [GCP Private Service Connect](/cloud/connectivity/gcp-connectivity) creation guides first. +:::info "Private Endpoint" in this section + +Because this page covers both clouds, **Private Endpoint** means the endpoint you create and own in your own network to reach Temporal Cloud privately: a **VPC Endpoint** on AWS and a **Private Service Connect endpoint** on GCP. The cloud-specific sections below use each provider's own term. + +::: + ## How HA + private connectivity works A Namespace with High Availability features has two replicas — a primary and a secondary, in different regions or different cloud providers. At any moment, one is **active** and one is **passive**. On failover, Temporal Cloud changes the active replica. @@ -128,16 +134,23 @@ This is the **only** place in Temporal Cloud where you can depend on Temporal-ma For private connectivity, your job is to make sure that: -- Override the Regional Endpoint's DNS zone to resolve to a VPC Endpoint. +- Override the Regional Endpoint's DNS zone to resolve to a Private Endpoint. - Ensure network connectivity between the two regions. +Overriding the regional records, rather than the Namespace Endpoint, is what makes a failover transparent over a private connection. Workers keep the same address and TLS configuration they would use over the public internet, and resolution follows Temporal Cloud's active-region CNAME into whichever region's Private Endpoint is currently active. It also means a Temporal Cloud outage confined to one region does not strand the Workers in that region: after the failover, they resolve the Namespace Endpoint to the surviving region's Private Endpoint and keep working, as long as they have a network path to it. + :::warning Do not override the Namespace Endpoint in your private hosted zone -For HA Namespaces, the PHZ must override only the regional records (`-.region.tmprl.cloud`) — never the Namespace Endpoint itself (`..tmprl.cloud`). +For HA Namespaces, the PHZ must override only the regional records (`-.region.tmprl.cloud`) — never the Namespace Endpoint itself (`..tmprl.cloud`). This is [pattern C](/cloud/connectivity/aws-connectivity#choose-a-private-dns-pattern) of the private DNS patterns, and it is the only one that supports failover. + +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 Private Endpoint and never reach the new active region. + +Two setups run into this: -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. +- **A wildcard record.** A `*..tmprl.cloud` record matches the Namespace Endpoint of every Namespace in the account, including HA Namespaces. Do not use a wildcard in a network that reaches HA Namespaces. If you want a wildcard for your single-region Namespaces, put them in a separate network from the HA ones. +- **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. -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. +If one network reaches both single-region and HA Namespaces, use a per-Namespace record for each single-region Namespace and the regional records for the HA ones. The two coexist, because only HA Namespace Endpoints resolve through `region.tmprl.cloud`. :::