Skip to content

Commit 50e51ae

Browse files
cluddencludden
committed
Add private dns content for aws privatelink
1 parent 3bfa92a commit 50e51ae

File tree

1 file changed

+177
-16
lines changed

1 file changed

+177
-16
lines changed

‎docs/production-deployment/cloud/connectivity/aws-connectivity.mdx‎

Lines changed: 177 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -20,25 +20,10 @@ keywords:
2020
- term
2121
---
2222

23-
import { ToolTipTerm, DiscoverableDisclosure } from '@site/src/components';
23+
import { ToolTipTerm, DiscoverableDisclosure, CaptionedImage } from '@site/src/components';
2424

2525
This page covers...
2626

27-
## Creating an AWS PrivateLink connection
28-
29-
## How to configure internal DNS
30-
31-
(optional)
32-
33-
Why: simplify worker config in general (easier than SNI override) as well as potential failover/migration if using any HA capabilities
34-
35-
## Configure internal DNS for MRR
36-
37-
New cross-cloud diagram (multiple sets of workers)
38-
39-
If you’re using a single worker fleet, you can use PrivateLink.
40-
If you’re using Multi-cloud, you can’t use PrivateLink (or you need to solve cross-cloud networking)
41-
4227
[AWS PrivateLink](https://aws.amazon.com/privatelink/) allows you to open a path to Temporal without opening a public egress.
4328
It establishes a private connection between your Amazon Virtual Private Cloud (VPC) and Temporal Cloud.
4429
This one-way connection means Temporal cannot establish a connection back to your service.
@@ -55,6 +40,8 @@ If you are interested in leveraging AWS PrivateLink in your Namespaces, [create
5540

5641
:::
5742

43+
## Creating an AWS PrivateLink connection
44+
5845
Set up PrivateLink connectivity with Temporal Cloud with these steps:
5946

6047
1. Open the AWS console with the region you want to use to establish the PrivateLink.
@@ -163,3 +150,177 @@ When using [API keys for namespace authentication](/cloud/api-keys#namespace-aut
163150
<DNS ASSOCIATED WITH VPC ENDPOINT>:7233 \
164151
temporal.api.workflowservice.v1.WorkflowService/GetSystemInfo
165152
```
153+
154+
## Configuring Private DNS for AWS PrivateLink
155+
156+
### Why configure private DNS?
157+
158+
When you connect to Temporal Cloud through AWS PrivateLink you normally must:
159+
160+
1. **Point your SDKs/Workers at the PrivateLink DNS name** for the VPC Endpoint (e.g., `vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com`), **and**
161+
2. **Override the Server Name Indicator (SNI)** so that the TLS handshake still presents the public Temporal Cloud hostname (e.g., `my-namespace.my-account.tmprl.cloud`).
162+
163+
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:
164+
165+
* Keep using the standard Temporal Cloud hostnames in code and configuration.
166+
* Eliminate the need to set a custom SNI override.
167+
* Make future Endpoint rotations transparent—only the PHZ record changes.
168+
169+
This approach is **optional**; Temporal Cloud works without it. It simply streamlines configuration and operations.
170+
171+
### Prerequisites
172+
173+
| Requirement | Notes |
174+
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
175+
| AWS VPC with DNS resolution and DNS hostnames enabled | *VPC console → Edit DNS settings → enable both checkboxes.* |
176+
| Interface VPC Endpoint for Temporal Cloud | Subnets must be associated with the VPC and Security Group must allow TCP ingress traffic to port 7233 from the appropriate hosts. |
177+
| Route 53 available in your AWS account | You need permission to create Private Hosted Zones and records. |
178+
| Namespace details | Needed to choose the correct override domain pattern below. |
179+
180+
### Choose the override domain and endpoint
181+
182+
| Temporal Cloud setup | Use this PHZ domain | Example |
183+
| -------------------------------------- | ----------------------- | ----------------------------------------------- |
184+
| Single-region namespace with mTLS auth | `<account>.tmprl.cloud` | `payments.abcde.tmprl.cloud` ↔ `vpce-...` |
185+
| Multi-region namespace **or** API-key auth | `region.tmprl.cloud` | `aws-us-east-1.region.tmprl.cloud` ↔ `vpce-...` |
186+
187+
### Step-by-step instructions
188+
189+
#### 1. Collect your PrivateLink endpoint DNS name
190+
191+
```bash
192+
aws ec2 describe-vpc-endpoints \
193+
--vpc-endpoint-ids $VPC_ENDPOINT_ID \
194+
--query "VpcEndpoints[0].DnsEntries[0].DnsName" \
195+
--output text
196+
197+
# Example output:
198+
# vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com
199+
```
200+
201+
Save the **`vpce-*.amazonaws.com`** value -- you will target it in the CNAME record.
202+
203+
#### 2. Create a Route 53 Private Hosted Zone
204+
205+
1. **Open** *Route 53 → Hosted zones → Create hosted zone*.
206+
2. Enter the **domain** chosen from the table above, e.g., `payments.abcde.tmprl.cloud`.
207+
3. **Type:** *Private hosted zone for Temporal Cloud*.
208+
4. **Associate** the hosted zone with every VPC that contains Temporal Workers and/or SDK clients.
209+
5. **Create hosted zone**.
210+
211+
#### 3. Add a CNAME record
212+
213+
Inside the new PHZ:
214+
215+
| Field | Value |
216+
| --------------- | ------------------------------------------------------------------------------------- |
217+
| **Record name** | the namespace endpoint (e.g., `payments.abcde.tmprl.cloud`). |
218+
| **Record type** | `CNAME` |
219+
| **Value** | Your VPC Endpoint DNS name (`vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com`) |
220+
| **TTL** | 60s is typical; 15s for MRN namespaces; adjust as needed. |
221+
222+
#### 4. Verify DNS resolution from inside the VPC
223+
224+
```bash
225+
dig payments.abcde.tmprl.cloud
226+
```
227+
228+
If the record resolves to the VPC Endpoint, you are ready to use Temporal Cloud without SNI overrides.
229+
230+
### Updating your workers/clients
231+
232+
With private DNS in place, configure your SDKs exactly as the public-internet examples show:
233+
234+
```go
235+
clientOptions := client.Options{
236+
HostPort: "payments.abcde.tmprl.cloud:7233",
237+
Namespace: "payments",
238+
// No TLS SNI override needed
239+
}
240+
```
241+
242+
The DNS resolver inside your VPC returns the private endpoint, while TLS still validates the original hostname—simplifying both code and certificate management.
243+
244+
## Configure Private DNS for Multi-Region Namespaces
245+
246+
:::tip Namespaces with High Availability features and AWS PrivateLink
247+
248+
Proper networking configuration is required for failover to be transparent to clients and workers when using PrivateLink.
249+
This page describes how to configure routing for Namespaces with High Availability features on AWS PrivateLink.
250+
251+
:::
252+
253+
To use AWS PrivateLink with High Availability features, you may need to:
254+
255+
- Override the regional DNS zone.
256+
- Ensure network connectivity between the two regions.
257+
258+
This page provides the details you need to set this up.
259+
260+
### Customer side solutions
261+
262+
When using PrivateLink, you connect to Temporal Cloud through a VPC Endpoint, which uses addresses local to your network.
263+
Temporal treats each `region.<tmprl_domain>` as a separate zone.
264+
This setup allows you to override the default zone, ensuring that traffic is routed internally for the regions you’re using.
265+
266+
A Namespace's active region is reflected in the target of a CNAME record.
267+
For example, if the active region of a Namespace is AWS us-west-2, the DNS configuration would look like this:
268+
269+
| Record name | Record type | Value |
270+
| ----------- | ----------- | ----- |
271+
| ha-namespace.account-id.tmprl.cloud | CNAME | aws-us-west-2.region.tmprl.cloud |
272+
273+
After a failover, the CNAME record will be updated to point to the failover region, for example:
274+
275+
| Record name | Record type | Value |
276+
| ----------- | ----------- | ----- |
277+
| ha-namespace.account-id.tmprl.cloud | CNAME | aws-us-east-1.region.tmprl.cloud |
278+
279+
The Temporal domain did not change, but the CNAME updated from us-west-2 to us-east-1.
280+
281+
<CaptionedImage
282+
src="/img/cloud/high-availability/private-link.png"
283+
title="Customer side solution example"
284+
zoom="true"
285+
/>
286+
287+
### Setting up the DNS override
288+
289+
To set up the DNS override, configure specific regions to target the internal VPC Endpoint IP addresses.
290+
For example, you might set aws-us-west-1.region.tmprl.cloud to target 192.168.1.2.
291+
In AWS, this can be done using a Route 53 private hosted zone for `region.tmprl.cloud`.
292+
Link that private zone to the VPCs you use for Workers.
293+
294+
When your Workers connect to the Namespace, they first resolve the `<ns>.<acct>.<tmprl_domain>` record.
295+
This points to `<aws-active-region>.region.tmprl.cloud`, which then resolves to your internal IP addresses.
296+
297+
Consider how you’ll configure Workers for this setup.
298+
You can either have Workers run in both regions continuously or establish connectivity between regions using Transit Gateway or VPC Peering.
299+
This way, Workers can access the newly activated region once failover occurs.
300+
301+
## Available regions, PrivateLink endpoints, and DNS record overrides
302+
303+
:::caution
304+
305+
The `sa-east-1` region is not yet available for use with Multi-region Namespaces. Currently, it is the only region on the continent.
306+
307+
:::
308+
309+
The following table lists the available Temporal regions, PrivateLink endpoints, and DNS record overrides:
310+
311+
| Region | PrivateLink Service Name | DNS Record Override |
312+
| ---------------- | -------------------------------------------------------------- | --------------------------------------- |
313+
| `ap-northeast-1` | `com.amazonaws.vpce.ap-northeast-1.vpce-svc-08f34c33f9fb8a48a` | `aws-ap-northeast-1.region.tmprl.cloud` |
314+
| `ap-northeast-2` | `com.amazonaws.vpce.ap-northeast-2.vpce-svc-08c4d5445a5aad308` | `aws-ap-northeast-2.region.tmprl.cloud` |
315+
| `ap-south-1` | `com.amazonaws.vpce.ap-south-1.vpce-svc-0ad4f8ed56db15662` | `aws-ap-south-1.region.tmprl.cloud` |
316+
| `ap-south-2` | `com.amazonaws.vpce.ap-south-2.vpce-svc-08bcf602b646c69c1` | `aws-ap-south-2.region.tmprl.cloud` |
317+
| `ap-southeast-1` | `com.amazonaws.vpce.ap-southeast-1.vpce-svc-05c24096fa89b0ccd` | `aws-ap-southeast-1.region.tmprl.cloud` |
318+
| `ap-southeast-2` | `com.amazonaws.vpce.ap-southeast-2.vpce-svc-0634f9628e3c15b08` | `aws-ap-southeast-2.region.tmprl.cloud` |
319+
| `ca-central-1` | `com.amazonaws.vpce.ca-central-1.vpce-svc-080a781925d0b1d9d` | `aws-ca-central-1.region.tmprl.cloud` |
320+
| `eu-central-1` | `com.amazonaws.vpce.eu-central-1.vpce-svc-073a419b36663a0f3` | `aws-eu-central-1.region.tmprl.cloud` |
321+
| `eu-west-1` | `com.amazonaws.vpce.eu-west-1.vpce-svc-04388e89f3479b739` | `aws-eu-west-1.region.tmprl.cloud` |
322+
| `eu-west-2` | `com.amazonaws.vpce.eu-west-2.vpce-svc-0ac7f9f07e7fb5695` | `aws-eu-west-2.region.tmprl.cloud` |
323+
| `sa-east-1` | `com.amazonaws.vpce.sa-east-1.vpce-svc-0ca67a102f3ce525a` | `aws-sa-east-1.region.tmprl.cloud` |
324+
| `us-east-1` | `com.amazonaws.vpce.us-east-1.vpce-svc-0822256b6575ea37f` | `aws-us-east-1.region.tmprl.cloud` |
325+
| `us-east-2` | `com.amazonaws.vpce.us-east-2.vpce-svc-01b8dccfc6660d9d4` | `aws-us-east-2.region.tmprl.cloud` |
326+
| `us-west-2` | `com.amazonaws.vpce.us-west-2.vpce-svc-0f44b3d7302816b94` | `aws-us-west-2.region.tmprl.cloud` |

0 commit comments

Comments
 (0)