Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
6 changes: 3 additions & 3 deletions docs/best-practices/cloud-access-control.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -58,8 +58,8 @@ One convention is to give certificates a common name that matches the namespace.

Teams should standardize on either [mTLS certificates](/cloud/certificates) or
[API keys](/cloud/api-keys) for the following operations:
- Connect Temporal clients to Temporal Cloud (e.g. Worker processes)
- Automation (e.g. Temporal Cloud [Operations API](/ops), [Terraform provider](/cloud/terraform-provider), [Temporal CLI](/cli/setup-cli))
- Connect Temporal clients to Temporal Cloud (for example, Worker processes)
- Automation (for example, Temporal Cloud [Operations API](/ops), [Terraform provider](/cloud/terraform-provider), [Temporal CLI](/cli/setup-cli))

By default, teams should use API keys with [service accounts](/cloud/manage-access/service-accounts) for both operations. API keys
are generally easier to set up and rotate than mTLS certificates, and service accounts let you assign account-level and
Expand Down Expand Up @@ -108,7 +108,7 @@ Use the following sequence when rotating credentials:
4. Validate connectivity and normal Workflow execution using the new credential.
5. Remove the old credential only after all clients and Workers have switched.

### Use Certificate Filters to restrict access when using shared CAs (e.g., `dev` vs `prod`)
### Use Certificate Filters to restrict access when using shared CAs (for example, `dev` vs `prod`)

Certificate Filters are an additional way of validating using the client certificate presented during client authentication. Give certificates a common name that matches the namespace. This is not a requirement.

Expand Down
2 changes: 1 addition & 1 deletion docs/best-practices/cost-optimization.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -266,7 +266,7 @@ Alternatively, if you are looking to do analysis on closed Workflow Executions,

- Temporal Cloud Usage dashboard for Actions and Storage metrics
- Event History for per-Workflow billable Actions estimates
- Export metrics to observability platforms (Datadog, Grafana, etc.) for custom monitoring
- Export metrics to observability platforms such as Datadog or Grafana for custom monitoring

## When to get help

Expand Down
2 changes: 1 addition & 1 deletion docs/best-practices/managing-namespace.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ Use a pattern like `<use-case>-<domain>-<environment>` to name Namespaces:

:::tip Temporal Cloud
Cloud Namespace names are limited to [39 characters](/cloud/namespaces#temporal-cloud-namespace-name).
If you need to include region, use short codes (e.g., `aps1`, `use1`).
If you need to include region, use short codes (for example, `aps1`, `use1`).
:::

## Organizational Patterns

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 [vale] reported by reviewdog 🐶
[Temporal.Headings] 'Organizational Patterns' should use sentence-style capitalization.

Expand Down
2 changes: 1 addition & 1 deletion docs/best-practices/pre-production-testing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ Depending on execution environment:

**What to test**

Periodically restart a fixed or random percentage (e.g. 20-30%) of your Worker fleet every few minutes.
Periodically restart a fixed or random percentage (for example, 20-30%) of your Worker fleet every few minutes.

**Why it matters**

Expand Down
12 changes: 6 additions & 6 deletions docs/best-practices/security-controls.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ Strong identity management in Temporal Cloud is crucial for ensuring secure acce

#### 1. Enable [SAML Single Sign-on](/cloud/manage-access/saml) (SSO) for User Access

Integrate Temporal Cloud with your organization's identity provider via SAML 2.0 for centralized authentication. SSO allows you to enforce your corporate login policies (MFA, password complexity, etc.). When you configure SAML with Temporal Cloud, you can disable social logins (i.e. Microsoft, Google) by opening a support ticket.
Integrate Temporal Cloud with your organization's identity provider via SAML 2.0 for centralized authentication. SSO allows you to enforce your corporate login policies (such as MFA and password complexity). When you configure SAML with Temporal Cloud, you can disable social logins (that is, Microsoft, Google) by opening a support ticket.

#### 2. Use Least-Privilege Roles for Temporal Cloud Users

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 [vale] reported by reviewdog 🐶
[Temporal.Headings] '2. Use Least-Privilege Roles for Temporal Cloud Users' should use sentence-style capitalization.


Expand All @@ -49,7 +49,7 @@ When applicable, use [SCIM](/cloud/manage-access/scim) or the Temporal Cloud use

#### Use Service Accounts for Automation

For non-human access (CI/CD pipelines, backend services), use [Temporal Cloud Service Accounts](/cloud/manage-access/service-accounts) instead of shared user logins. Service Accounts are machine identities that can be granted specific permissions without ties to an individual. Create separate Service Accounts with unique API keys for different applications or microservices, and apply least privilege to each (e.g. a service account that only has access to one Namespace).
For non-human access (CI/CD pipelines, backend services), use [Temporal Cloud Service Accounts](/cloud/manage-access/service-accounts) instead of shared user logins. Service Accounts are machine identities that can be granted specific permissions without ties to an individual. Create separate Service Accounts with unique API keys for different applications or microservices, and apply least privilege to each (for example, a service account that only has access to one Namespace).

## Secure Application Authentication and API Access

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 [vale] reported by reviewdog 🐶
[Temporal.Headings] 'Secure Application Authentication and API Access' should use sentence-style capitalization.


Expand All @@ -67,7 +67,7 @@ We recommend you enable mTLS for strong identity assurance of clients; it ensure

#### 2. Proactively manage and rotate certificates

Track the expiration dates of your client and [Certificate Authority certificates](/cloud/certificates). Temporal Cloud trusts the uploaded CA; if it expires, all client authorizations will fail. Establish and automate a certificate rotation schedule (e.g. rotate client certificates quarterly and CA certificates annually, well before expiry). Temporal supports uploading a new CA certificate alongside the old one to allow seamless rollover. Always test new certificates in a staging environment if possible.
Track the expiration dates of your client and [Certificate Authority certificates](/cloud/certificates). Temporal Cloud trusts the uploaded CA; if it expires, all client authorizations will fail. Establish and automate a certificate rotation schedule (for example, rotate client certificates quarterly and CA certificates annually, well before expiry). Temporal supports uploading a new CA certificate alongside the old one to allow seamless rollover. Always test new certificates in a staging environment if possible.

#### 3. If you’re using API Keys, handle them with strict care

Expand All @@ -90,9 +90,9 @@ Temporal Cloud supports private connectivity options such as [AWS PrivateLink](/

#### 2. Separate environments by Namespace

Use [Temporal Namespaces](/best-practices/managing-namespace#naming-conventions) to isolate workflows for different environments or teams (e.g. development, staging, production). Each Namespace is logically segregated and cannot interact with others by default, providing a security boundary.
Use [Temporal Namespaces](/best-practices/managing-namespace#naming-conventions) to isolate workflows for different environments or teams (for example, development, staging, production). Each Namespace is logically segregated and cannot interact with others by default, providing a security boundary.

Ensure that your production Namespace uses stricter network controls (e.g. only accessible from the prod network) and that credentials for it are separate from non-prod Namespaces. This limits the impact of any compromise in a lower environment, and as workflow data is only visible to users with access to that Namespace, separating environments by Namespace also enforces data-visibility boundaries.
Ensure that your production Namespace uses stricter network controls (for example, only accessible from the prod network) and that credentials for it are separate from non-prod Namespaces. This limits the impact of any compromise in a lower environment, and as workflow data is only visible to users with access to that Namespace, separating environments by Namespace also enforces data-visibility boundaries.

## Data Protection and Encryption

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 [vale] reported by reviewdog 🐶
[Temporal.Headings] 'Data Protection and Encryption' should use sentence-style capitalization.


Expand Down Expand Up @@ -125,7 +125,7 @@ Temporal Cloud’s platform is engineered for fault-tolerance out of the box, bu
| **Single-Region** | **If your application is built for one region and does not have stringent high-availability or disaster recovery requirements.** | 99.9% | ≤ 8 hours | ≤ 8 hours |
| **Same-Region Replication** | **If you want higher availability but your application is designed for a single region or if cross region latency doesn’t meet SLAs for application** | 99.99% | ≤ 20 minutes | Near-zero (≈ seconds) |
| **Multi-Region Replication** | **If a disruption of your workflow will cause loss of revenue, poor end-user experience, or issues with regulatory compliance.** | 99.99% | ≤ 20 minutes | Near-zero (≈ seconds) |
| **Multi-Cloud Replication** | **If you need the highest level of disaster tolerance, protecting against outages of an entire cloud provider (e.g., AWS or GCP)** | 99.99% | ≤ 20 minutes | Near-zero (≈ seconds) |
| **Multi-Cloud Replication** | **If you need the highest level of disaster tolerance, protecting against outages of an entire cloud provider (for example, AWS or GCP)** | 99.99% | ≤ 20 minutes | Near-zero (≈ seconds) |

### Best Practices:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 [vale] reported by reviewdog 🐶
[Temporal.Headings] 'Best Practices:' should use sentence-style capitalization.


Expand Down
12 changes: 6 additions & 6 deletions docs/cloud/connectivity/aws-connectivity.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -94,8 +94,8 @@ The next step is to [configure private DNS](#configuring-private-dns-for-aws-pri

When you connect to Temporal Cloud through AWS PrivateLink you normally must:

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**
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`).
1. **Point your SDKs/Workers at the PrivateLink DNS name** for the VPC Endpoint (for example, `vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com`), **and**
2. **Override the Server Name Indicator (SNI)** so that the TLS handshake still presents the public Temporal Cloud hostname (for example, `my-namespace.my-account.tmprl.cloud`).

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:

Expand Down Expand Up @@ -154,7 +154,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)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 [vale] reported by reviewdog 🐶
[Temporal.Headings] '2. Create a Route 53 Private Hosted Zone (do not yet attach Worker VPCs)' should use sentence-style capitalization.


a. Open _Route 53 → Hosted zones → Create hosted zone_.
b. Enter the domain chosen from the table above, e.g., `payments.abcde.tmprl.cloud`.
b. Enter the domain chosen from the table above, for example, `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.
Expand All @@ -165,7 +165,7 @@ Inside the new PHZ:

| Field | Value |
| --------------- | ------------------------------------------------------------------------------------- |
| **Record name** | the Namespace Endpoint (e.g., `payments.abcde.tmprl.cloud`). |
| **Record name** | the Namespace Endpoint (for example, `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 Namespaces with High Availability (to minimize recovery time after failover). |
Expand Down Expand Up @@ -214,8 +214,8 @@ You can avoid creating DNS records for each Namespace by pointing Workers direct

1. Create the PrivateLink VPC Endpoint (one per region — all Namespaces in that region share it).
2. Configure each Worker with:
- **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`)
- **Endpoint**: the DNS name of the VPC Endpoint in the region where the Worker runs (for example, `vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com:7233`)
- **Server name** (SNI override): the Namespace Endpoint value (for example, `my-namespace.my-account.tmprl.cloud`)

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.

Expand Down
10 changes: 5 additions & 5 deletions docs/cloud/connectivity/gcp-connectivity.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ See [configuring private DNS for GCP Private Service Connect](#configuring-priva
When you connect to Temporal Cloud through GCP Private Service Connect you normally must:

1. **Point your SDKs/Workers at the Private Service Connect endpoint IP address** _and_
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`).
2. **Override the Server Name Indicator (SNI)** so that the TLS handshake still presents the public Temporal Cloud hostname (for example, `my-namespace.my-account.tmprl.cloud`).

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:

Expand Down Expand Up @@ -155,8 +155,8 @@ 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** (e.g., `temporal-cloud`).
4. Enter a **DNS name** based on the table above (e.g., `payments.abcde.tmprl.cloud` or `us-east-1.aws.api.temporal.io`).
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`).
5. Select **Add networks** and choose the Project and Network that contains your PSC endpoint.
6. Click **Create**.

Expand All @@ -166,10 +166,10 @@ Inside the new zone, add a _standard A record_:

| Field | Value |
| -------------------- | -------------------------------------------------------------- |
| DNS name | the namespace endpoint (e.g. `payments.abcde.tmprl.cloud`) |
| DNS name | the namespace endpoint (for example, `payments.abcde.tmprl.cloud`) |
| Resource record type | A |
| TTL | 60s is typical, but you can adjust as needed. |
| IPv4 Address | the internal IP address of your PSC endpoint (e.g. `10.1.2.3`) |
| IPv4 Address | the internal IP address of your PSC endpoint (for example, `10.1.2.3`) |

#### 4. Verify DNS resolution from inside the Network

Expand Down
10 changes: 5 additions & 5 deletions docs/cloud/connectivity/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -223,16 +223,16 @@ We strongly recommend using private DNS instead of updating client server and TL

If you are unable to configure private DNS, you must update two settings in your Temporal clients:

1. Set the endpoint server address to the PrivateLink or Private Service Connect endpoint (e.g. `vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com:7233` or `<GCP PSC IP address>:7233`).
2. Set TLS configuration to override the TLS server name (the Namespace Endpoint, e.g., `my-namespace.my-account.tmprl.cloud`).
1. Set the endpoint server address to the PrivateLink or Private Service Connect endpoint (for example, `vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com:7233` or `<GCP PSC IP address>:7233`).
2. Set TLS configuration to override the TLS server name (the Namespace Endpoint, for example, `my-namespace.my-account.tmprl.cloud`).

The TLS server name override depends on your authentication method:

| Authentication | TLS server name to use |
| -------------- | ---------------------- |
| mTLS (single-region Namespace) | The Namespace Endpoint, e.g. `my-namespace.my-account.tmprl.cloud` |
| API key (single-region Namespace) | The regional API endpoint, e.g. `us-east-1.aws.api.temporal.io` or `us-central1.gcp.api.temporal.io` |
| Multi-region Namespace (mTLS or API key) | The active region endpoint, e.g. `us-east-1.aws.api.temporal.io` |
| mTLS (single-region Namespace) | The Namespace Endpoint, for example `my-namespace.my-account.tmprl.cloud` |
| API key (single-region Namespace) | The regional API endpoint, for example `us-east-1.aws.api.temporal.io` or `us-central1.gcp.api.temporal.io` |
| Multi-region Namespace (mTLS or API key) | The active region endpoint, for example `us-east-1.aws.api.temporal.io` |

If you authenticate with an API key over PrivateLink/PSC and use the wrong server name, the TLS handshake will fail with errors such as `connection reset by peer` even though `nc` reports the port as open.

Expand Down
2 changes: 1 addition & 1 deletion docs/cloud/get-started/namespaces.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -424,7 +424,7 @@ track, and manage namespaces more easily.
### Tag Structure and Limits

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 [vale] reported by reviewdog 🐶
[Temporal.Headings] 'Tag Structure and Limits' should use sentence-style capitalization.


- Each namespace can have a maximum of 10 tags
- Each key must be unique for a given namespace (e.g., a namespace cannot have both `team:foo` and `team:bar` tags)
- Each key must be unique for a given namespace (for example, a namespace cannot have both `team:foo` and `team:bar` tags)
- Keys and values must be 1-63 characters in length
- Allowed characters: lowercase letters (`a-z`), numbers (`0-9`), periods (`.`), underscores (`_`), hyphens (`-`), and
at signs (`@`)
Expand Down
4 changes: 2 additions & 2 deletions docs/cloud/high-availability/failovers/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ list, and it may change over time.
You can also [manually trigger a failover](/cloud/high-availability/failovers/manage#trigger-failover) based on your own
monitoring or for failover testing.

Most Namespaces with High Availability are well-served by automatic failovers. The cases where a manual failover (i.e.,
Most Namespaces with High Availability are well-served by automatic failovers. The cases where a manual failover (that is,
a failover triggered by a user) is warranted are:

- **Testing failover or migrating to a new region.** A manual failover is the standard way to exercise your failover
Expand Down Expand Up @@ -158,7 +158,7 @@ non-graceful failover, replication lag causes a temporary setback in Workflow pr
failover:

- Operations that had already replicated remain durable in the replica.
- Operations that had not yet replicated (i.e., that are still in the replication backlog) are reconciled when the
- Operations that had not yet replicated (that is, that are still in the replication backlog) are reconciled when the
region recovers, according to the conflict resolution process.

:::caution Conflict resolution requires a recoverable region
Expand Down
Loading