Skip to content

Draft of PrivateLink docs improvements #4492

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lukeknep wants to merge 3 commits into
base: main
Choose a base branch
from
+211 −146
Open

Draft of PrivateLink docs improvements #4492

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1a6f23d
Draft of PrivateLink docs improvements
lukeknep Apr 28, 2026
eda95b7
Updates to PrivateLink docs
lukeknep Apr 28, 2026
287fdc4
updates
lukeknep Apr 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 49 additions & 69 deletions docs/cloud/connectivity/aws-connectivity.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,14 +108,19 @@ This approach is **optional**; Temporal Cloud works without it. It simply stream

### Choose the override domain and endpoint

| Temporal Cloud setup | Use this PHZ domain | Example |
| ----------------------------------------- | ---------------------------------- | ----------------------------------------------- |
| Single-region namespace with mTLS auth | `<account>.tmprl.cloud` | `payments.abcde.tmprl.cloud` ↔ `vpce-...` |
| Single-region namespace with API-key auth | `<cloud_provider>.api.temporal.io` | `us-east-1.aws.api.temporal.io` ↔ `vpce-...` |
| Multi-region namespace | `region.tmprl.cloud` | `aws-us-east-1.region.tmprl.cloud` ↔ `vpce-...` |
| 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` |

### Step-by-step instructions

:::warning Order matters

A Route 53 private hosted zone with no records causes DNS resolution to fail (NXDOMAIN) inside any associated VPC. If you create an empty PHZ for `<account>.tmprl.cloud` and associate it with a VPC where Workers are running, **all Worker traffic to Temporal Cloud in that VPC stops** until you add the CNAME record. Follow the steps below in order to avoid this.

:::

#### 1. Collect your PrivateLink endpoint DNS name

```bash
Expand All @@ -128,28 +133,38 @@ aws ec2 describe-vpc-endpoints \
# vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com
```

Save the **`vpce-*.amazonaws.com`** value -- you will target it in the CNAME record.
Save the **`vpce-*.amazonaws.com`** value — you will target it in the CNAME record.

#### 2. Create a Route 53 Private Hosted Zone
#### 2. Create a Route 53 Private Hosted Zone (do not yet attach Worker VPCs)

1. Open _Route 53 → Hosted zones → Create hosted zone_.
2. Enter the domain chosen from the table above, e.g., `payments.abcde.tmprl.cloud`.
3. Type: _Private hosted zone for Temporal Cloud_.
4. Associate the hosted zone with every VPC that contains Temporal Workers and/or SDK clients.
5. Create hosted zone.
a. Open _Route 53 → Hosted zones → Create hosted zone_.
b. Enter the domain chosen from the table above, e.g., `payments.abcde.tmprl.cloud`.
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.

#### 3. Add a CNAME record

Inside the new PHZ:

| Field | Value |
| --------------- | ------------------------------------------------------------------------------------- |
| **Record name** | the namespace endpoint (e.g., `payments.abcde.tmprl.cloud`). |
| **Record name** | the Namespace Endpoint (e.g., `payments.abcde.tmprl.cloud`). |
| **Record type** | `CNAME` |
| **Value** | Your VPC Endpoint DNS name (`vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com`) |
| **TTL** | 60s is typical; 15s for MRN namespaces; adjust as needed. |
| **TTL** | 60s is typical; 15s for Namespaces with High Availability (to minimize recovery time after failover). |

#### 4. Associate the PHZ with your Worker VPCs and verify

#### 4. Verify DNS resolution from inside the VPC
Now that the record exists, associate the PHZ with every VPC that contains Temporal Workers or SDK clients (Route 53 → your zone → _Edit settings_ → _Add VPC_).

:::tip Test with a non-production VPC first

We strongly recommend that you test with a non-production VPC first. Attach the PHZ to a non-production VPC, validate end-to-end resolution and connectivity from a host in that VPC, and only then attach production Worker VPCs. This catches misconfigured records before they affect production traffic.

:::

Verify DNS resolution from inside one of the associated VPCs:

```bash
dig payments.abcde.tmprl.cloud
Expand All @@ -171,62 +186,11 @@ clientOptions := client.Options{

The DNS resolver inside your VPC returns the private endpoint, while TLS still validates the original hostname—simplifying both code and certificate management.

## Configure Private DNS for Multi-Region Namespaces

:::tip Namespaces with High Availability features and AWS PrivateLink

Proper networking configuration is required for failover to be transparent to clients and workers when using PrivateLink.
This page describes how to configure routing for Namespaces with High Availability features on AWS PrivateLink.

:::

To use AWS PrivateLink with High Availability features, you may need to:

- Override the regional DNS zone.
- Ensure network connectivity between the two regions.

This page provides the details you need to set this up.
## Configure private DNS for Namespaces with High Availability

### Customer side solutions
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.

When using PrivateLink, you connect to Temporal Cloud through a VPC Endpoint, which uses addresses local to your network.
Temporal treats each `region.<tmprl_domain>` as a separate zone.
This setup allows you to override the default zone, ensuring that traffic is routed internally for the regions you’re using.

A Namespace's active region is reflected in the target of a CNAME record.
For example, if the active region of a Namespace is AWS us-west-2, the DNS configuration would look like this:

| Record name | Record type | Value |
| ----------------------------------- | ----------- | -------------------------------- |
| ha-namespace.account-id.tmprl.cloud | CNAME | aws-us-west-2.region.tmprl.cloud |

After a failover, the CNAME record will be updated to point to the failover region, for example:

| Record name | Record type | Value |
| ----------------------------------- | ----------- | -------------------------------- |
| ha-namespace.account-id.tmprl.cloud | CNAME | aws-us-east-1.region.tmprl.cloud |

The Temporal domain did not change, but the CNAME updated from us-west-2 to us-east-1.

<CaptionedImage
src="/img/cloud/high-availability/private-link.png"
title="Customer side solution example"
zoom="true"
/>

### Setting up the DNS override

To set up the DNS override, configure specific regions to target the internal VPC Endpoint IP addresses.
For example, you might set aws-us-west-1.region.tmprl.cloud to target 192.168.1.2.
In AWS, this can be done using a Route 53 private hosted zone for `region.tmprl.cloud`.
Link that private zone to the VPCs you use for Workers.

When your Workers connect to the Namespace, they first resolve the `<ns>.<acct>.<tmprl_domain>` record.
This points to `<aws-active-region>.region.tmprl.cloud`, which then resolves to your internal IP addresses.

Consider how you’ll configure Workers for this setup.
You can either have Workers run in both regions continuously or establish connectivity between regions using Transit Gateway or VPC Peering.
This way, Workers can access the newly activated region once failover occurs.
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}

Expand All @@ -248,6 +212,22 @@ For HA Namespaces, use [private DNS](#configuring-private-dns-for-aws-privatelin

:::

## 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.

You can create as many AWS PrivateLink VPC endpoints as you need to the same Temporal Cloud regional service — there is nothing to register, approve, or open a ticket for on the Temporal side.

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).
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.

## Available AWS regions, PrivateLink endpoints, and DNS record overrides

The following table lists the available Temporal regions, PrivateLink endpoints, and regional endpoints used for DNS record overrides:
Expand Down
20 changes: 12 additions & 8 deletions docs/cloud/connectivity/gcp-connectivity.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,21 +73,25 @@ Individual Namespaces do not use separate services.
- For **IP address**, click the dropdown and select **Create IP address** to create an internal IP from your subnet dedicated to the endpoint. Select this IP.
- Check **Enable global access** if you intend to connect the endpoint to virtual machines outside of the selected region. We recommend regional connectivity instead of global access, as it can be better in terms of latency for your workers. _**Note:** this requires the network routing mode to be set to **GLOBAL**._

5. Click the **Add endpoint** button at the bottom of the screen.
5. Click the **Add endpoint** button at the bottom of the screen. The endpoint will appear with status **Pending**. This is expected — the next step is what flips it to **Accepted**.

6. [Create a Temporal Cloud Connectivity Rule](/cloud/connectivity#creating-a-connectivity-rule) using the Connection ID of the newly created endpoint and the corresponding GCP Project.
6. [Create a Temporal Cloud Connectivity Rule](/cloud/connectivity#creating-a-connectivity-rule) using the Connection ID of the newly created endpoint and the corresponding GCP project. Use the **Connection ID** from the endpoint's detail page in the Google Cloud console (a numeric string such as `1234567890123456789`).

7. Once the status is "Accepted", the GCP Private Service Connect endpoint is ready for use.
7. Once the status changes from "Pending" to "Accepted", the GCP Private Service Connect endpoint is ready for use.

:::tip Connectivity Rule required
:::warning PSC stays "Pending" until you create a Connectivity Rule

If your Private Service Connect connection status is not becoming "Active", verify that you have [created a Connectivity Rule](/cloud/connectivity#creating-a-connectivity-rule).
Connectivity Rules are mandatory for GCP Private Service Connect connections.
The connection will not become active without one.
For GCP Private Service Connect, the Connectivity Rule is what tells Temporal Cloud to accept your PSC connection. Until you [create a Connectivity Rule](/cloud/connectivity#creating-a-connectivity-rule) for the connection, the endpoint will remain in **Pending**. There is no separate producer-side approval step — creating the Connectivity Rule is the approval.

If your endpoint is stuck Pending, the most common causes are:

- No Connectivity Rule exists for the connection ID. (Most common.)
- The Connectivity Rule was created with the wrong `connection-id`, `region`, or `gcp-project-id`.
- The endpoint is in a region that is not a [supported Temporal Cloud region](/cloud/regions).

:::

- Take note of the **IP address** that has been assigned to your endpoint, as it will be used to connect to Temporal Cloud.
- Take note of the **IP address** assigned to your endpoint — you will use it to connect to Temporal Cloud.

:::caution
You still need to set up private DNS or override client configuration for your clients to actually use the new Private Service Connect connection to connect to Temporal Cloud.
Expand Down
Loading
Loading