From ce9f22e0362ebbdbc244cc81be2b92f97682c0d3 Mon Sep 17 00:00:00 2001 From: Ben Echols Date: Thu, 19 Feb 2026 17:34:07 -0800 Subject: [PATCH 1/4] Add Cloud Ops API tab to manual failovers section Adds HTTP and gRPC instructions for triggering a namespace failover via the Cloud Ops API, alongside the existing Web UI and tcld tabs. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/cloud/high-availability/failovers.mdx | 47 +++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/docs/cloud/high-availability/failovers.mdx b/docs/cloud/high-availability/failovers.mdx index b12484297a..56e6fb7e9a 100644 --- a/docs/cloud/high-availability/failovers.mdx +++ b/docs/cloud/high-availability/failovers.mdx @@ -192,7 +192,7 @@ A forced failover when there is a significant replication lag has a higher likel ### Trigger the failover {#manual-failovers} -You can trigger a failover manually using the Temporal Cloud
Web UI or the tcld CLI, depending on your preference and setup. +You can trigger a failover manually using the Temporal Cloud Web UI, the tcld CLI, or the Cloud Ops API, depending on your preference and setup. The following instructions outline the steps for each method: @@ -220,6 +220,51 @@ If using API key authentication with the `--api-key` flag, you must add it direc + + +You can trigger a failover programmatically using the [Cloud Ops API](/ops). +The API is available via both HTTP and gRPC. + +**Using HTTP** + +Send a POST request to the [`FailoverNamespaceRegion`](https://saas-api.tmprl.cloud/docs/httpapi.html#tag/high-availability/POST/cloud/namespaces/{namespace}/failover-region) endpoint: + +``` +POST https://saas-api.tmprl.cloud/cloud/namespaces//failover-region +``` + +Request body: + +```json +{ + "region": "", + "asyncOperationId": "" +} +``` + +- `region` (required): The ID of the region to failover to. Must be a region the Namespace is currently available in. +- `asyncOperationId` (optional): A user-defined ID for tracking the async operation. + +**Using gRPC** + +Use the [`FailoverNamespaceRegion`](https://buf.build/temporalio/cloud-api/docs/main:temporal.api.cloud.cloudservice.v1#temporal.api.cloud.cloudservice.v1.CloudService.FailoverNamespaceRegion) RPC with a [`FailoverNamespaceRegionRequest`](https://buf.build/temporalio/cloud-api/docs/main:temporal.api.cloud.cloudservice.v1#temporal.api.cloud.cloudservice.v1.FailoverNamespaceRegionRequest): + +```protobuf +message FailoverNamespaceRegionRequest { + // The namespace to failover. + string namespace = 1; + // The id of the region to failover to. + // Must be a region that the namespace is currently available in. + string region = 2; + // The id to use for this async operation - optional. + string async_operation_id = 3; +} +``` + +Both methods return a [`FailoverNamespaceRegionResponse`](https://buf.build/temporalio/cloud-api/docs/main:temporal.api.cloud.cloudservice.v1#temporal.api.cloud.cloudservice.v1.FailoverNamespaceRegionResponse) containing an async operation that you can use to track the failover status. + + + Temporal fails over the primary to the replica. From f3e3d009d9f5f65cb6048f1808260c05eaa9e1ed Mon Sep 17 00:00:00 2001 From: Luke Knepper Date: Fri, 20 Feb 2026 14:45:17 -0800 Subject: [PATCH 2/4] Apply suggestions from code review --- docs/cloud/high-availability/failovers.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/cloud/high-availability/failovers.mdx b/docs/cloud/high-availability/failovers.mdx index 56e6fb7e9a..d510eae1d8 100644 --- a/docs/cloud/high-availability/failovers.mdx +++ b/docs/cloud/high-availability/failovers.mdx @@ -242,8 +242,8 @@ Request body: } ``` -- `region` (required): The ID of the region to failover to. Must be a region the Namespace is currently available in. -- `asyncOperationId` (optional): A user-defined ID for tracking the async operation. +- `region` (required): The ID of the region to failover to. Must be a region the Namespace is currently available in. Example: `us-east-1` +- `asyncOperationId` (optional): A user-defined ID for tracking the async operation. If not set, the server will assign one. **Using gRPC** From 02c25401364d5e7f349ed3f3f5c78ff993430650 Mon Sep 17 00:00:00 2001 From: Luke Knepper Date: Fri, 20 Feb 2026 15:05:47 -0800 Subject: [PATCH 3/4] Apply suggestion from @lukeknep --- docs/cloud/high-availability/failovers.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud/high-availability/failovers.mdx b/docs/cloud/high-availability/failovers.mdx index d510eae1d8..5ccc3238fb 100644 --- a/docs/cloud/high-availability/failovers.mdx +++ b/docs/cloud/high-availability/failovers.mdx @@ -242,7 +242,7 @@ Request body: } ``` -- `region` (required): The ID of the region to failover to. Must be a region the Namespace is currently available in. Example: `us-east-1` +- `region` (required): The [region code](/cloud/regions) of the region to failover to. Must be a region where the Namespace has a replica in `Activated` replica state, indicating the replica is ready to be failed over to. Example: `aws-us-east-1` - `asyncOperationId` (optional): A user-defined ID for tracking the async operation. If not set, the server will assign one. **Using gRPC** From 6cc4ac2d8d1477b2d5b756e6fdfbd46de817280e Mon Sep 17 00:00:00 2001 From: Luke Knepper Date: Fri, 20 Feb 2026 15:07:25 -0800 Subject: [PATCH 4/4] Apply suggestions from code review --- docs/cloud/high-availability/failovers.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/cloud/high-availability/failovers.mdx b/docs/cloud/high-availability/failovers.mdx index 5ccc3238fb..9fd3428546 100644 --- a/docs/cloud/high-availability/failovers.mdx +++ b/docs/cloud/high-availability/failovers.mdx @@ -216,6 +216,8 @@ tcld namespace failover \ --region ``` +The `` must be the name of a region (example: `us-east-1`) where the Namespace has a replica that is ready to be failed over to (replica state is `Activated`). + If using API key authentication with the `--api-key` flag, you must add it directly after the tcld command and before `namespace failover`.