Skip to content
Open
Changes from 5 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
38 changes: 34 additions & 4 deletions docs/production-deployment/cloud/migrate/automated.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ Submit a support ticket with the following details:

- A list of your Temporal accounts
- Target Temporal Cloud service regions
- For each cluster, provide the server configuration by running `temporal operator cluster describe --address <frontend:7233>`
- For each cluster, provide the server configuration by running `temporal operator cluster describe --address <frontend:7233> --output json` (see [notes](#alternative-commands-for-versions-1281-and-prior) for Temporal server version 1.28.1 and prior).
- Metrics for the namespaces to be migrated:
- number of open/closed workflows
- storage used
Expand Down Expand Up @@ -192,14 +192,30 @@ There are two options for switching Temporal clients to the cloud:
automatically forward from your server to the cloud.
4. Complete migration. Your self-hosted Temporal clients will no longer receive any tasks from your server, allowing you to stop these clients.

- Option 2 (not recommended)- Deploy one set of Temporal clients and switch the namespace endpoint during migration. With this option, your workflows will stop making progress.
- Option 2 - Deploy one set of Temporal clients and switch the namespace endpoint during migration. With this option, if your workers are misconfigured during the switch, then it is
possible that workflows can stop making progress. It is important to ensure that all workers maintain connectivity to cloud to avoid this scenario.
The process is as follows:
1. Start migration.
2. Switch your Temporal clients to point to the cloud namespace endpoint. Requests from your Temporal clients will automatically forward from the cloud to your server.
3. Hand over namespace to the cloud. Requests from your Temporal clients will now be served by the cloud and will not be forwarded to your server. Alternatively, you may
2. Switch your Temporal clients to point to the cloud namespace endpoint. Requests from your Temporal clients will automatically forward from the cloud to your server. Alternatively, you may
switch Temporal clients to the cloud namespace endpoint after handover.
3. Hand over namespace to the cloud. Requests from your Temporal clients will now be served by the cloud and will not be forwarded to your server.
4. Confirm migration completion.

##### Optional Process - Maximize your availability by deploying a second set of Temporal clients
Deploy two sets of Temporal clients: one pointing to your Temporal server and one to the Cloud namespace endpoint. This helps diagnose misconfiguration issues while leaving your
original workers completely untouched. If you're confident in your existing deployment strategy for updating your workers to point at Temporal Cloud, you can skip this step.

##### Handover behavior
These are the steps that your namespace will go through as it migrates from your cluster to Temporal Cloud.

1. Your workers are connected to your local cluster, and your cluster is not connected to Temporal Cloud. If you created workers for your Cloud namespace, they will poll for actions, but won't see any traffic.
2. Start migration. Your self-hosted namespace is active while your cloud namespace is passive (or standby). Your cloud Temporal clients can begin receiving tasks, and all requests
from cloud clients to the Cloud namespace will automatically forward from the cloud to your self-hosted server.
3. Hand over namespace to the cloud. Your cloud namespace becomes active and your self-hosted namespace becomes passive. All requests from your self-hosted Temporal clients will
automatically forward from your server to the cloud.
4. Complete migration. Your self-hosted Temporal clients will no longer receive any tasks from your server, allowing you to stop these clients.


#### Final Validation

Before failing over your namespace to Temporal Cloud, review the following production readiness checklist. These steps help ensure a smooth transition and minimize surprises in production.
Expand All @@ -209,3 +225,17 @@ Before failing over your namespace to Temporal Cloud, review the following produ
- Learn how capacity management works in Temporal Cloud, including how to request capacity increases.
- Plan for a worker tuning session - performance change between Temporal Cloud v.s. self-hosted cluster, which could lead to unexpected symptoms and optimizations.
- Know how to reach out to your Temporal Solutions Architect (SA) and Account Executive (AE) for assistance.


### Additional Notes

#### Alternative Commands for Versions 1.28.1 and Prior
Version 1.28.1 and older do not provide the details necessary for setting up migration. If you are running an older version of Temporal, then substitute the below
commands for the "temporal operator cluster describe" command cited in this document.

If you are using tctl, then substitute the following command: `tctl --address <frontend:7233> admin cluster describe`

If you are not a tctl user, then use the following alternative:
`grpcurl -v -plaintext <your temporal address and port> temporal.server.api.adminservice.v1.AdminService.DescribeCluster`