From f7bbb39612a6ff93d9f44f5272283c56645daa04 Mon Sep 17 00:00:00 2001 From: Luke Knepper Date: Thu, 2 Jul 2026 20:21:03 -0700 Subject: [PATCH 1/4] fix the direct VPCE error --- docs/cloud/connectivity/aws-connectivity.mdx | 91 ++++++++++++++++++-- 1 file changed, 84 insertions(+), 7 deletions(-) diff --git a/docs/cloud/connectivity/aws-connectivity.mdx b/docs/cloud/connectivity/aws-connectivity.mdx index 692c532eb7..57d6d9ac70 100644 --- a/docs/cloud/connectivity/aws-connectivity.mdx +++ b/docs/cloud/connectivity/aws-connectivity.mdx @@ -29,7 +29,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) (single-region Namespaces only). +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). ## Requirements @@ -211,12 +211,89 @@ For single-region Namespaces, you can avoid creating DNS records for each Namesp With this approach, new Namespaces do not require new DNS records. -:::warning Not compatible with High Availability Namespaces +**Single-region Namespace** -This approach does not work for Namespaces with High Availability features. -HA Namespaces rely on Temporal's public DNS CNAME records to route traffic to the active region during failover. -If you bypass DNS, your Workers cannot follow the CNAME to the new region. -For HA Namespaces, use [private DNS](#configuring-private-dns-for-aws-privatelink) instead. +```mermaid +--- +title: Direct VPCE targeting (single region) +--- +%%{init: {'themeVariables':{'fontFamily':'Inter, ui-sans-serif, system-ui, sans-serif','edgeLabelBackground':'transparent'},'flowchart':{'nodeSpacing':18,'rankSpacing':45,'curve':'basis','subGraphTitleMargin':{'top':6,'bottom':12}}}}%% +flowchart LR + classDef worker fill:#7C3AED22,stroke:#7C3AED,stroke-width:1px; + classDef ns fill:#59FDA024,stroke:#59FDA0,stroke-width:1px; + classDef endpoint fill:transparent,stroke:#c2c8d2,stroke-width:1px; + classDef region fill:transparent,stroke:#9aa4b2,stroke-width:1.5px; + classDef pool fill:transparent,stroke:#c2c8d2,stroke-width:1px; + subgraph SREG["Your VPC — us-east-1"] + subgraph SWP["Worker Pool"] + SW1["Worker"]:::worker + SW2["Worker"]:::worker + end + SVPCE["VPC Endpoint
vpce-…-us-east-1"]:::endpoint + SWP -->|"Server name:
my-namespace.my-account.tmprl.cloud"| SVPCE + end + SNS["Namespace
(Temporal Cloud)"]:::ns + SVPCE --> SNS + class SREG region + class SWP pool +``` + +Workers set their **Endpoint** to the VPC Endpoint DNS name and their **Server name** to the Namespace Endpoint, so the TLS handshake still presents the public Namespace hostname. + +:::note Using direct VPCE targeting with High Availability Namespaces + +Direct VPCE targeting also works for Namespaces with [High Availability features](/cloud/high-availability), but it takes more careful setup. Because each VPC Endpoint is pinned to its region and does not follow Temporal Cloud's active-region CNAME on failover, you cannot rely on DNS to move Workers between regions. This is the same trade-off as targeting a [Regional Endpoint](/cloud/high-availability/ha-connectivity#regional-endpoint) instead of the Namespace Endpoint. + +To stay available through a failover: + +- Run Workers in every region the Namespace can be active in. +- Point each region's Workers at the VPC Endpoint **local to that region** — the Endpoint value differs per region. +- Set the **Server name** (SNI override) to the Namespace Endpoint value in every region — it is the same everywhere. + +Workers connected to the passive region's VPC Endpoint stay productive: Temporal Cloud forwards their tasks to the active region. On failover, no DNS change is needed, because Workers are already connected in both regions and the surviving region takes over. + +**High Availability Namespace** + +```mermaid +--- +title: Direct VPCE targeting (High Availability) +--- +%%{init: {'themeVariables':{'fontFamily':'Inter, ui-sans-serif, system-ui, sans-serif','edgeLabelBackground':'transparent'},'flowchart':{'nodeSpacing':18,'rankSpacing':45,'curve':'basis','subGraphTitleMargin':{'top':6,'bottom':12}}}}%% +flowchart LR + classDef worker fill:#7C3AED22,stroke:#7C3AED,stroke-width:1px; + classDef ns fill:#59FDA024,stroke:#59FDA0,stroke-width:1px; + classDef endpoint fill:transparent,stroke:#c2c8d2,stroke-width:1px; + classDef region fill:transparent,stroke:#9aa4b2,stroke-width:1.5px; + classDef pool fill:transparent,stroke:#c2c8d2,stroke-width:1px; + subgraph HPRIM["us-east-1 (active)"] + subgraph HWPA["Worker Pool"] + HWA1["Worker"]:::worker + HWA2["Worker"]:::worker + end + HVPA["VPC Endpoint
vpce-…-us-east-1"]:::endpoint + HNSA["Replica
(Active)"]:::ns + HWPA -->|"Server name:
my-namespace.my-account.tmprl.cloud"| HVPA + HVPA --> HNSA + end + subgraph HSEC["us-west-2 (passive)"] + subgraph HWPB["Worker Pool"] + HWB1["Worker"]:::worker + HWB2["Worker"]:::worker + end + HVPB["VPC Endpoint
vpce-…-us-west-2"]:::endpoint + HNSB["Replica
(Passive)"]:::ns + HWPB -->|"Server name:
my-namespace.my-account.tmprl.cloud"| HVPB + HVPB --> HNSB + end + HNSB -.->|"Tasks forwarded to active"| HNSA + HNSA <-->|Replication| HNSB + class HPRIM,HSEC region + class HWPA,HWPB pool +``` + +The **Server name** is identical in both regions; only the **Endpoint** (the local VPC Endpoint DNS name) differs. Passive-region Workers reach the passive Replica, and Temporal Cloud forwards their tasks to the active region. + +If you would rather not run Workers in every region, use [private DNS](#configuring-private-dns-for-aws-privatelink) with the regional-record pattern described in [Connectivity for High Availability](/cloud/high-availability/ha-connectivity) instead, which relies on DNS-based failover to move Workers between regions. ::: @@ -231,7 +308,7 @@ For each additional AWS account or VPC: 1. In that account, create the AWS PrivateLink VPC endpoint targeting the regional service name from the [regions table](#available-aws-regions-privatelink-endpoints-and-dns-record-overrides) — same as in the [creation steps](#creating-an-aws-privatelink-connection) above. 2. Configure DNS in that VPC. You have two options: - Create a Route 53 Private Hosted Zone in that account scoped to the appropriate VPC(s), following the [private DNS steps](#configuring-private-dns-for-aws-privatelink) above. Each VPC's PHZ should point at the VPC Endpoint local to that VPC. - - Or, use [direct VPCE targeting](#direct-vpce) (single-region Namespaces only). + - Or, use [direct VPCE targeting](#direct-vpce). For High Availability Namespaces, follow the [additional setup](#direct-vpce) so each region's Workers target their local VPC Endpoint. 3. **Optional:** if you want to enforce private-only access for a Namespace, add a Connectivity Rule for each VPC endpoint and attach all of them (plus a public rule, if needed) to the Namespace. See [Connectivity Rules](/cloud/connectivity#connectivity-rules). There is no upper limit on the number of VPC endpoints you can connect from your side to a regional PrivateLink service. The default per-account limit on private Connectivity Rules is 50 — [contact support](/cloud/support#support-ticket) if you need to raise it. From 688975cafdc0951aacca6b589c71aa288adb058b Mon Sep 17 00:00:00 2001 From: Luke Knepper Date: Fri, 3 Jul 2026 16:48:40 -0700 Subject: [PATCH 2/4] Direct VPCE Corrections --- docs/cloud/connectivity/aws-connectivity.mdx | 75 +++++++++----------- 1 file changed, 33 insertions(+), 42 deletions(-) diff --git a/docs/cloud/connectivity/aws-connectivity.mdx b/docs/cloud/connectivity/aws-connectivity.mdx index 57d6d9ac70..8408188fa4 100644 --- a/docs/cloud/connectivity/aws-connectivity.mdx +++ b/docs/cloud/connectivity/aws-connectivity.mdx @@ -23,6 +23,16 @@ keywords: import { ToolTipTerm, DiscoverableDisclosure, CaptionedImage, JsonTable } from '@site/src/components'; + + [AWS PrivateLink](https://aws.amazon.com/privatelink/) allows you to open a path to Temporal without opening a public egress. It establishes a private connection between your Amazon Virtual Private Cloud (VPC) and Temporal Cloud. This one-way connection means Temporal cannot establish a connection back to your service. @@ -202,14 +212,14 @@ The complete guidance — including single-cloud (AWS-only) HA, multi-cloud HA ( ## Direct VPCE targeting without per-Namespace DNS {/* #direct-vpce */} -For single-region Namespaces, 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): +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): 1. Create the PrivateLink VPC Endpoint (one per region — all Namespaces in that region share it). 2. Configure each Worker with: - - **Endpoint**: the VPC Endpoint DNS name (e.g., `vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com:7233`) + - **Endpoint**: the DNS name of the VPC Endpoint in the region where the Worker runs (e.g., `vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com:7233`) - **Server name** (SNI override): the Namespace Endpoint value (e.g., `my-namespace.my-account.tmprl.cloud`) -With this approach, new Namespaces do not require new DNS records. +With this approach, new Namespaces do not require new DNS records. Workers set their **Endpoint** to the VPC Endpoint DNS name and their **Server name** to the Namespace Endpoint, so the client SDK accepts the TLS handshake from Temporal Cloud. **Single-region Namespace** @@ -217,86 +227,67 @@ With this approach, new Namespaces do not require new DNS records. --- title: Direct VPCE targeting (single region) --- -%%{init: {'themeVariables':{'fontFamily':'Inter, ui-sans-serif, system-ui, sans-serif','edgeLabelBackground':'transparent'},'flowchart':{'nodeSpacing':18,'rankSpacing':45,'curve':'basis','subGraphTitleMargin':{'top':6,'bottom':12}}}}%% +%%{init: {'themeVariables':{'fontFamily':'Inter, ui-sans-serif, system-ui, sans-serif'},'flowchart':{'nodeSpacing':18,'rankSpacing':45,'curve':'basis','subGraphTitleMargin':{'top':6,'bottom':12}}}}%% flowchart LR classDef worker fill:#7C3AED22,stroke:#7C3AED,stroke-width:1px; classDef ns fill:#59FDA024,stroke:#59FDA0,stroke-width:1px; classDef endpoint fill:transparent,stroke:#c2c8d2,stroke-width:1px; classDef region fill:transparent,stroke:#9aa4b2,stroke-width:1.5px; - classDef pool fill:transparent,stroke:#c2c8d2,stroke-width:1px; - subgraph SREG["Your VPC — us-east-1"] - subgraph SWP["Worker Pool"] - SW1["Worker"]:::worker - SW2["Worker"]:::worker - end - SVPCE["VPC Endpoint
vpce-…-us-east-1"]:::endpoint - SWP -->|"Server name:
my-namespace.my-account.tmprl.cloud"| SVPCE + subgraph SREG["Your VPC"] + SW["Worker(s)
Server name:
my-namespace.my-account.tmprl.cloud"]:::worker + SVPCE["VPC Endpoint
vpce-…"]:::endpoint + SW --> SVPCE end SNS["Namespace
(Temporal Cloud)"]:::ns - SVPCE --> SNS + SVPCE -->|PrivateLink| SNS class SREG region - class SWP pool ``` -Workers set their **Endpoint** to the VPC Endpoint DNS name and their **Server name** to the Namespace Endpoint, so the TLS handshake still presents the public Namespace hostname. - :::note Using direct VPCE targeting with High Availability Namespaces Direct VPCE targeting also works for Namespaces with [High Availability features](/cloud/high-availability), but it takes more careful setup. Because each VPC Endpoint is pinned to its region and does not follow Temporal Cloud's active-region CNAME on failover, you cannot rely on DNS to move Workers between regions. This is the same trade-off as targeting a [Regional Endpoint](/cloud/high-availability/ha-connectivity#regional-endpoint) instead of the Namespace Endpoint. -To stay available through a failover: +::: + +**Namespace with High Availability** + +To use the Direct VPCE approach with a Namespace that has High Availability: -- Run Workers in every region the Namespace can be active in. - Point each region's Workers at the VPC Endpoint **local to that region** — the Endpoint value differs per region. - Set the **Server name** (SNI override) to the Namespace Endpoint value in every region — it is the same everywhere. +- **(Recommended)** To stay available during a failover, run Workers in every region the Namespace can be active in. -Workers connected to the passive region's VPC Endpoint stay productive: Temporal Cloud forwards their tasks to the active region. On failover, no DNS change is needed, because Workers are already connected in both regions and the surviving region takes over. - -**High Availability Namespace** +Workers connected to the passive region's VPC Endpoint stay productive: Temporal Cloud forwards their tasks to the active region (you can [configure this forwarding behavior](/cloud/high-availability/enable#change-forwarding-behavior)). On failover, no DNS change is needed, because Workers are already connected in both regions and the surviving region takes over. ```mermaid --- title: Direct VPCE targeting (High Availability) --- -%%{init: {'themeVariables':{'fontFamily':'Inter, ui-sans-serif, system-ui, sans-serif','edgeLabelBackground':'transparent'},'flowchart':{'nodeSpacing':18,'rankSpacing':45,'curve':'basis','subGraphTitleMargin':{'top':6,'bottom':12}}}}%% +%%{init: {'themeVariables':{'fontFamily':'Inter, ui-sans-serif, system-ui, sans-serif'},'flowchart':{'nodeSpacing':18,'rankSpacing':45,'curve':'basis','subGraphTitleMargin':{'top':6,'bottom':12}}}}%% flowchart LR classDef worker fill:#7C3AED22,stroke:#7C3AED,stroke-width:1px; classDef ns fill:#59FDA024,stroke:#59FDA0,stroke-width:1px; classDef endpoint fill:transparent,stroke:#c2c8d2,stroke-width:1px; classDef region fill:transparent,stroke:#9aa4b2,stroke-width:1.5px; - classDef pool fill:transparent,stroke:#c2c8d2,stroke-width:1px; subgraph HPRIM["us-east-1 (active)"] - subgraph HWPA["Worker Pool"] - HWA1["Worker"]:::worker - HWA2["Worker"]:::worker - end + HWA["Worker(s)
Server name:
my-namespace.my-account.tmprl.cloud"]:::worker HVPA["VPC Endpoint
vpce-…-us-east-1"]:::endpoint HNSA["Replica
(Active)"]:::ns - HWPA -->|"Server name:
my-namespace.my-account.tmprl.cloud"| HVPA - HVPA --> HNSA + HWA --> HVPA + HVPA -->|PrivateLink| HNSA end subgraph HSEC["us-west-2 (passive)"] - subgraph HWPB["Worker Pool"] - HWB1["Worker"]:::worker - HWB2["Worker"]:::worker - end + HWB["Worker(s)
Server name:
my-namespace.my-account.tmprl.cloud"]:::worker HVPB["VPC Endpoint
vpce-…-us-west-2"]:::endpoint HNSB["Replica
(Passive)"]:::ns - HWPB -->|"Server name:
my-namespace.my-account.tmprl.cloud"| HVPB - HVPB --> HNSB + HWB --> HVPB + HVPB -->|PrivateLink| HNSB end HNSB -.->|"Tasks forwarded to active"| HNSA HNSA <-->|Replication| HNSB class HPRIM,HSEC region - class HWPA,HWPB pool ``` -The **Server name** is identical in both regions; only the **Endpoint** (the local VPC Endpoint DNS name) differs. Passive-region Workers reach the passive Replica, and Temporal Cloud forwards their tasks to the active region. - -If you would rather not run Workers in every region, use [private DNS](#configuring-private-dns-for-aws-privatelink) with the regional-record pattern described in [Connectivity for High Availability](/cloud/high-availability/ha-connectivity) instead, which relies on DNS-based failover to move Workers between regions. - -::: - ## Adding PrivateLink from additional AWS accounts A common pattern is to have separate AWS accounts for different lines of business, environments (staging, production), or compliance scopes (PCI vs non-PCI), each with its own VPC and Workers connecting to the same Temporal Cloud account. From d96510d009c5f05f8f99b26bc10620392123e7d2 Mon Sep 17 00:00:00 2001 From: Luke Knepper Date: Fri, 3 Jul 2026 16:55:33 -0700 Subject: [PATCH 3/4] Direct VPCE Corrections 2 --- docs/cloud/connectivity/aws-connectivity.mdx | 30 ++++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/cloud/connectivity/aws-connectivity.mdx b/docs/cloud/connectivity/aws-connectivity.mdx index 8408188fa4..90071f4a31 100644 --- a/docs/cloud/connectivity/aws-connectivity.mdx +++ b/docs/cloud/connectivity/aws-connectivity.mdx @@ -263,28 +263,28 @@ Workers connected to the passive region's VPC Endpoint stay productive: Temporal --- title: Direct VPCE targeting (High Availability) --- -%%{init: {'themeVariables':{'fontFamily':'Inter, ui-sans-serif, system-ui, sans-serif'},'flowchart':{'nodeSpacing':18,'rankSpacing':45,'curve':'basis','subGraphTitleMargin':{'top':6,'bottom':12}}}}%% -flowchart LR +%%{init: {'themeVariables':{'fontFamily':'Inter, ui-sans-serif, system-ui, sans-serif'},'flowchart':{'nodeSpacing':55,'rankSpacing':70,'curve':'basis','subGraphTitleMargin':{'top':6,'bottom':12}}}}%% +flowchart TD classDef worker fill:#7C3AED22,stroke:#7C3AED,stroke-width:1px; classDef ns fill:#59FDA024,stroke:#59FDA0,stroke-width:1px; classDef endpoint fill:transparent,stroke:#c2c8d2,stroke-width:1px; classDef region fill:transparent,stroke:#9aa4b2,stroke-width:1.5px; - subgraph HPRIM["us-east-1 (active)"] - HWA["Worker(s)
Server name:
my-namespace.my-account.tmprl.cloud"]:::worker - HVPA["VPC Endpoint
vpce-…-us-east-1"]:::endpoint - HNSA["Replica
(Active)"]:::ns - HWA --> HVPA - HVPA -->|PrivateLink| HNSA - end subgraph HSEC["us-west-2 (passive)"] - HWB["Worker(s)
Server name:
my-namespace.my-account.tmprl.cloud"]:::worker - HVPB["VPC Endpoint
vpce-…-us-west-2"]:::endpoint - HNSB["Replica
(Passive)"]:::ns + HWB["Worker(s)
Server name:
namespace.
acct.
tmprl.cloud"]:::worker + HVPB["VPC
Endpoint
vpce-…
-us-west-2"]:::endpoint + HNSB["Replica
(Passive,
forwards
to active)"]:::ns HWB --> HVPB - HVPB -->|PrivateLink| HNSB + HVPB -->|Private
Link| HNSB + end + subgraph HPRIM["us-east-1 (active)"] + HWA["Worker(s)
Server name:
namespace.
acct.
tmprl.cloud"]:::worker + HVPA["VPC
Endpoint
vpce-…
-us-east-1"]:::endpoint + HNSA["Namespace
(Active)"]:::ns + HWA --> HVPA + HVPA -->|Private
Link| HNSA end - HNSB -.->|"Tasks forwarded to active"| HNSA - HNSA <-->|Replication| HNSB + + class HPRIM,HSEC region ``` From 0b594c0b73b2637be65f5c94e70ef350a12fe229 Mon Sep 17 00:00:00 2001 From: Luke Knepper Date: Sun, 5 Jul 2026 21:07:14 -0700 Subject: [PATCH 4/4] tweaks --- docs/cloud/connectivity/aws-connectivity.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/cloud/connectivity/aws-connectivity.mdx b/docs/cloud/connectivity/aws-connectivity.mdx index 90071f4a31..dcc0263a4a 100644 --- a/docs/cloud/connectivity/aws-connectivity.mdx +++ b/docs/cloud/connectivity/aws-connectivity.mdx @@ -270,18 +270,18 @@ flowchart TD classDef endpoint fill:transparent,stroke:#c2c8d2,stroke-width:1px; classDef region fill:transparent,stroke:#9aa4b2,stroke-width:1.5px; subgraph HSEC["us-west-2 (passive)"] - HWB["Worker(s)
Server name:
namespace.
acct.
tmprl.cloud"]:::worker - HVPB["VPC
Endpoint
vpce-…
-us-west-2"]:::endpoint + HWB["Worker(s)
Server name
namespace.
acct.
tmprl.cloud"]:::worker + HVPB["VPC
Endpoint
vpce-…
us-west-2"]:::endpoint HNSB["Replica
(Passive,
forwards
to active)"]:::ns HWB --> HVPB - HVPB -->|Private
Link| HNSB + HVPB --> HNSB end subgraph HPRIM["us-east-1 (active)"] - HWA["Worker(s)
Server name:
namespace.
acct.
tmprl.cloud"]:::worker - HVPA["VPC
Endpoint
vpce-…
-us-east-1"]:::endpoint + HWA["Worker(s)
Server name
namespace.
acct.
tmprl.cloud"]:::worker + HVPA["VPC
Endpoint
vpce-…
us-east-1"]:::endpoint HNSA["Namespace
(Active)"]:::ns HWA --> HVPA - HVPA -->|Private
Link| HNSA + HVPA --> HNSA end