Merge branch 'main' into update-cli-docs-v1.7.1-standalone-nexus-operations

Author: brianmacdonald-temporal

docs/best-practices/cost-optimization.mdx

@@ -62,7 +62,7 @@ See [Spooky Stories: Chilling Temporal Anti-Patterns](https://temporal.io/blog/s
 ### Large payloads in Workflow History
 
 Passing multi-megabyte payloads through Workflows when external storage (S3, blob storage) is more appropriate.
-Use [compression](/troubleshooting/blob-size-limit-error#why-does-this-error-occur) or the [claim check pattern](https://dataengineering.wiki/Concepts/Software+Engineering/Claim+Check+Pattern) for large data.
+Use [compression](/troubleshooting/blob-size-limit-error#payload-size-limit) or the [claim check pattern](https://dataengineering.wiki/Concepts/Software+Engineering/Claim+Check+Pattern) for large data.
 
 ### Over-optimization at the expense of observability
 

docs/cloud/audit-logs.mdx

@@ -83,34 +83,24 @@ Instead, explore the [Export](/cloud/export) feature, which does let you send cl
 
 :::info DEPRECATION NOTICE
 
-The following fields are deprecated and are planned for removal on or after April 1 2026. 
-
-- `user_email`.  This field is duplicated by `principal.name` for principals of type `user`. Other principal types do not have associated emails.
-- `level`.  This field is duplicated by `status`.
-- `caller_ip_address`.  This field is replaced by `x_forwarded_for`.
-- `details`.  This field is replaced by `raw_details` that includes request details.
-- `category`.  This field is no longer used.
+The `request_id` field is deprecated and is planned for removal on or after November 1 2026. Use `async_operation_id` instead.
 
 :::
 
 Audit Logs use the following JSON format:
 
 ```json
 {
-  "operation":  // Operation that was performed
-  "principal": // Information about who initiated the operation
-  "details":  // DEPRECATED, see raw_details
-  "raw_details": // details about the request
-  "user_email":  // DEPRECATED, use principal.user where applicable
-  "x_forwarded_for": // the IP address making the call
-  "caller_ip_address": // DEPRECATED, use x_forwarded_for
-  "category":  // DEPRECATED, no longer used
-  "emit_time": // Time the operation was recorded
-  "level": // DEPRECATED, use status
-  "log_id": // Unique ID of the log entry
-  "request_id": // Optional async request id set by the user when sending a request
-  "status": // Status, such as OK or ERROR
-  "version": // Version of the log entry
+  "operation":          // Operation that was performed
+  "principal":          // Information about who initiated the operation
+  "raw_details":        // Details about the request
+  "x_forwarded_for":    // The IP address(es) making the call
+  "emit_time":          // Time the operation was recorded
+  "log_id":             // Unique ID of the log entry
+  "async_operation_id": // Optional async operation id set by the user when sending a request
+  "request_id":         // DEPRECATED, use async_operation_id
+  "status":             // Status, such as OK or ERROR
+  "version":            // Version of the log entry
 }
 ```
 

docs/cloud/connectivity/aws-connectivity.mdx

@@ -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
@@ -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
@@ -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}
 
@@ -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:

docs/cloud/connectivity/gcp-connectivity.mdx

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