From 90c7d514e2c09b10f208f1029e0732919de7fae6 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 22 Mar 2026 06:24:06 +0000 Subject: [PATCH 1/2] Initial plan From ec44ad9d366758ec0daa4ef341a303689c62f6f3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 22 Mar 2026 06:27:18 +0000 Subject: [PATCH 2/2] Fix typos in docs/best-practices Co-authored-by: jsundai <36107423+jsundai@users.noreply.github.com> Agent-Logs-Url: https://github.com/jsundai/temporal-documentation/sessions/34ec6c69-cb4c-41d7-896a-8afa9d4f2552 --- docs/best-practices/cloud-access-control.mdx | 4 ++-- docs/best-practices/index.mdx | 4 ++-- docs/best-practices/knowledge-hub.mdx | 2 +- docs/best-practices/managing-aps-limits.mdx | 6 +++--- docs/best-practices/security-controls.mdx | 22 ++++++++++---------- 5 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/best-practices/cloud-access-control.mdx b/docs/best-practices/cloud-access-control.mdx index a103067183..fba1622afb 100644 --- a/docs/best-practices/cloud-access-control.mdx +++ b/docs/best-practices/cloud-access-control.mdx @@ -30,7 +30,7 @@ The high-level end-to-end rotation process is: 4. **Validate connectivity**: Confirm all Workers can authenticate, and business processes operate normally with new credentials 5. **Remove old credentials**: Remove old certificates and API keys from your secrets provider after confirming successful migration -This approach ensures near-zero-downtime rotation and prevents authentication failures that could impact running workflows. For specific guidance to rotate mTLS certificates and API keys, see: +This approach ensures near-zero-downtime rotation and prevents authentication failures that could impact running Workflows. For specific guidance to rotate mTLS certificates and API keys, see: - https://docs.temporal.io/cloud/certificates#manage-certificates - https://docs.temporal.io/cloud/api-keys#rotate-an-api-key - https://github.com/temporal-sa/temporal-Worker-cert-rotation @@ -52,7 +52,7 @@ One convention is to give certificates a common name that matches the namespace. By default, it is recommended for teams to use API keys and [service accounts](https://docs.temporal.io/cloud/service-accounts) for both operations because API keys are easier to manage and rotate for most teams. In addition, you can control account-level and namespace-level roles for service accounts. - If your organization requires mutual authentication and stronger cryptographic guarantees, then it is encouraged for your teams to use mTLS certificates to authenticate Temporal clients to Temporal Cloud and use API keys for automation (because Temporal Cloud [Operations API](https://docs.temporal.io/ops) and [Terraform provider](https://docs.temporal.io/cloud/terraform-provider) only supports API key for authentication) + If your organization requires mutual authentication and stronger cryptographic guarantees, then it is encouraged for your teams to use mTLS certificates to authenticate Temporal clients to Temporal Cloud and use API keys for automation (because Temporal Cloud [Operations API](https://docs.temporal.io/ops) and [Terraform provider](https://docs.temporal.io/cloud/terraform-provider) only supports API keys for authentication) #### 2. Use Certificate Filters to restrict access when using shared CAs (e.g., `dev` vs `prod`): diff --git a/docs/best-practices/index.mdx b/docs/best-practices/index.mdx index 4987cc8403..1001903b7d 100644 --- a/docs/best-practices/index.mdx +++ b/docs/best-practices/index.mdx @@ -30,7 +30,7 @@ establish robust Temporal standards by providing: - **Standardized implementation patterns** for teams to adopt consistently across projects - **Confidence in alignment** with Temporal's architectural principles and recommended practices -By following this guidance, developers can define comprehensive Temporal standards that ensure their workflow +By following this guidance, developers can define comprehensive Temporal standards that ensure their Workflow orchestration implementations are maintainable, scalable, and aligned with platform best practices from the start. ## Target audience @@ -38,7 +38,7 @@ orchestration implementations are maintainable, scalable, and aligned with platf This section is intended for: - Developers responsible for building a Temporal Cloud practice within their organization. -- Anyone building tutorials, courses, onboarding paths, or documentation +- Anyone building tutorials, courses, onboarding paths, or documentation. - Partners or vendors creating Temporal-related learning materials ## Available guides diff --git a/docs/best-practices/knowledge-hub.mdx b/docs/best-practices/knowledge-hub.mdx index a1ff1f5af9..4fedb7ab56 100644 --- a/docs/best-practices/knowledge-hub.mdx +++ b/docs/best-practices/knowledge-hub.mdx @@ -115,7 +115,7 @@ application teams. ### Make it discoverable -A knowledge hub that developers can not find is the same as not having one. +A knowledge hub that developers cannot find is the same as not having one. - Register a short URL (for example, `go/temporal`) that redirects to the knowledge hub. - Pin the link in your Temporal-related communication channels (Slack, Microsoft Teams). diff --git a/docs/best-practices/managing-aps-limits.mdx b/docs/best-practices/managing-aps-limits.mdx index 2bb42674ba..a8df454bab 100644 --- a/docs/best-practices/managing-aps-limits.mdx +++ b/docs/best-practices/managing-aps-limits.mdx @@ -108,7 +108,7 @@ Consider an order fulfillment Workflow that spawns Child Workflows for payment p Each Child Workflow goes through its full action lifecycle (start, tasks, activities, completion), and all of those actions count toward the APS limits on your Namespace. This pattern appears frequently in: -- Batch processing: A parent workflow processes a file with 1,000 records, spawning a Child Workflow for each record. Batch processing is also often bursty whenever the batch begins. +- Batch processing: A parent Workflow processes a file with 1,000 records, spawning a Child Workflow for each record. Batch processing is also often bursty whenever the batch begins. - Map-reduce patterns: Data processing Workflows that fan out to process partitions in parallel, then aggregate results. This challenge additionally compounds when you have multiple levels of nesting--parent Workflows that create children, which create their own children. @@ -154,8 +154,8 @@ There are some design patterns that can lead to high APS that are consistent acr Consider two approaches to processing 1,000 records: -- Approach A: Create a Workflow that spawns 1,000 separate activities, one per record. -- Approach B: Create a Workflow that spawns 10 activities, each processing 100 records in a batch. +- Approach A: Create a Workflow that spawns 1,000 separate Activities, one per record. +- Approach B: Create a Workflow that spawns 10 Activities, each processing 100 records in a batch. Approach B will clearly result in less APS. This is a simple example, but this pattern shows up everywhere: processing individual transactions versus batches, sending individual notifications versus bulk operations, or making separate API calls versus batch endpoints. diff --git a/docs/best-practices/security-controls.mdx b/docs/best-practices/security-controls.mdx index feaceddfa2..b75d3c8f8d 100644 --- a/docs/best-practices/security-controls.mdx +++ b/docs/best-practices/security-controls.mdx @@ -37,11 +37,11 @@ Strong identity management in Temporal Cloud is crucial for ensuring secure acce #### 1. Enable [SAML Single Sign-on](https://docs.temporal.io/cloud/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 (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. #### 2. Use Least-Privilege Roles for Temporal Cloud Users -Temporal Cloud provides [preconfigured account-level roles](https://docs.temporal.io/cloud/users) (Account Owner, Finance Admin, Global Admin, Developer, Read-Only) and Namespace-level permissions. Assign users the lowest level of access they need. For example, give developers access only to the Namespaces they work on, and use read-only roles for auditors or reviewers. Regularly review user roles and remove or downgrade accounts that are no longer needed +Temporal Cloud provides [preconfigured account-level roles](https://docs.temporal.io/cloud/users) (Account Owner, Finance Admin, Global Admin, Developer, Read-Only) and Namespace-level permissions. Assign users the lowest level of access they need. For example, give developers access only to the Namespaces they work on, and use read-only roles for auditors or reviewers. Regularly review user roles and remove or downgrade accounts that are no longer needed. #### 3. Leverage SCIM or Automated User Provisioning @@ -80,7 +80,7 @@ Temporal Cloud API keys are an alternative to mTLS for authentication of SDKs, C ## Network Configuration and Isolation -Although Temporal Cloud is a SaaS offering, you retain control over its networking configurations, allowing for tailored security measures. By minimizing public internet exposure and segmenting Temporal workflows into suitable network zones, you can significantly bolster security and reduce potential vulnerabilities. This approach ensures that your workflows are isolated and protected within your defined network boundaries, even while leveraging the benefits of a cloud-based service. +Although Temporal Cloud is a SaaS offering, you retain control over its networking configurations, allowing for tailored security measures. By minimizing public internet exposure and segmenting Temporal Workflows into suitable network zones, you can significantly bolster security and reduce potential vulnerabilities. This approach ensures that your Workflows are isolated and protected within your defined network boundaries, even while leveraging the benefits of a cloud-based service. ### Best Practices: @@ -90,9 +90,9 @@ Temporal Cloud supports private connectivity options such as [AWS PrivateLink](h #### 2. Separate environments by Namespace -Use [Temporal Namespaces](https://learn.temporal.io/best_practice_guides/managing_a_namespace/#2-use-domain-service-and-environment-to-name-namespaces) 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](https://learn.temporal.io/best_practice_guides/managing_a_namespace/#2-use-domain-service-and-environment-to-name-namespaces) 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. -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 (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. ## Data Protection and Encryption @@ -123,22 +123,22 @@ Temporal Cloud’s platform is engineered for fault-tolerance out of the box, bu | Namespace scope | Use Case | Uptime SLA | Recovery Time Objective (RTO) | Recovery Point Objective (RPO) | |-----------------|----------|------------|--------------------------------|--------------------------------| | **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) | +| **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) | ### Best Practices: #### 1. Identify Availability-sensitive Namespaces -Run a business-impact analysis to flag workflows where a regional outage would cause significant customer, revenue, or safety impact. Identify Namespaces that are availability-sensitive where a regional outage may have outsized business impacts such as revenue loss, poor customer experience, or inability to meet legal obligations. +Run a business-impact analysis to flag Workflows where a regional outage would cause significant customer, revenue, or safety impact. Identify Namespaces that are availability-sensitive where a regional outage may have outsized business impacts such as revenue loss, poor customer experience, or inability to meet legal obligations. #### 2. Enable High Availability for business critical use cases For many organizations, ensuring High Availability (HA) is required because of strict uptime requirements, compliance, and regulatory needs. -For these critical use cases, enable High Availability features for specific namespaces for a [99.99% contractual SLA](https://docs.temporal.io/cloud/high-availability#high-availability-features). When choosing between [same-region, multi-region, and multi-cloud replication](https://docs.temporal.io/cloud/high-availability), it is recommended to use multi-region/multi-cloud replication to distribute your dependencies across regions. Using physically separated regions improves the fault tolerance of your application. +For these critical use cases, enable High Availability features for specific Namespaces for a [99.99% contractual SLA](https://docs.temporal.io/cloud/high-availability#high-availability-features). When choosing between [same-region, multi-region, and multi-cloud replication](https://docs.temporal.io/cloud/high-availability), it is recommended to use multi-region/multi-cloud replication to distribute your dependencies across regions. Using physically separated regions improves the fault tolerance of your application. -By default, Temporal Cloud provides a [99.9% contractual SLA guarantee](https://docs.temporal.io/cloud/high-availability) against service errors for all namespaces. +By default, Temporal Cloud provides a [99.9% contractual SLA guarantee](https://docs.temporal.io/cloud/high-availability) against service errors for all Namespaces. -Note: [enabling HA features for namespaces will 2x the consumption cost.](https://docs.temporal.io/cloud/pricing#high-availability-features) +Note: [enabling HA features for Namespaces will 2x the consumption cost.](https://docs.temporal.io/cloud/pricing#high-availability-features)