Skip to content

faq and misc updates #4402

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dspinhirne-temporal wants to merge 1 commit into
base: main
Choose a base branch
from
+74 −42
Open

faq and misc updates #4402

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
116 changes: 74 additions & 42 deletions docs/cloud/migrate/automated.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,17 +131,18 @@ Use the following template for the collected data.
Temporal Cloud Account:

<for each cluster>
Cluster Name:
Target Cloud/Region:
Type of Visibility Store:
Cluster Name: <name>
Target Cloud/Region: <region>
Type of Visibility Store: <store>
Cluster Configuration:

Namespaces:
<for each Namespace>
Namespace Name:
Translated Name:
Namespace Name: <name>
Translated Name: <name>
Metrics:
Custom Search Attributes:
Peak APS: <aps>
Custom Search Attributes: <temporal cli output>
<end>
<end>
```
Expand Down Expand Up @@ -188,8 +189,8 @@ Use the following procedure to deploy the proxy:
3. Deploy 3 replicas of the s2s-proxy (minimum 4 CPU and 512mb memory). For Kubernetes users, use this
[helm chart example](https://github.com/temporalio/s2s-proxy/blob/main/charts/s2s-proxy/README.md) as a reference.
See the [example](https://github.com/temporalio/s2s-proxy/blob/main/charts/s2s-proxy/example.yaml) configuration file
as a reference. Note that it is possible to deploy more than 1 replica. If more than 1 replica is deployed, you must
update Temporal with the number of replicas used so that an identical number may be configured on the cloud-side.
as a reference. Note that the number of replicas must match on both sides of the connection. If your replica count differs
from 3, update Temporal with the actual number of replicas so that the same count can be configured on the cloud side.
4. Test access using the command below. It should display the information of the migration server.

```
Expand Down Expand Up @@ -283,9 +284,9 @@ The sections below outline the process for initiating the migration.

### Migration start

Temporal will initiate the migration. During this process, the self-hosted Namespace remains active while the cloud
Namespace becomes passive. Workflows are replicated from the self-hosted Namespace to the cloud Namespace. Once cloud
Namespace has fully synced with self-hosted Namespace, migration is ready for handover.
Temporal will generate the endpoint-id and initiate the migration. During this process, the self-hosted Namespace remains active
while the cloud Namespace becomes passive. Workflows are replicated from the self-hosted Namespace to the cloud Namespace. Once
cloud Namespace has fully synced with self-hosted Namespace, migration is ready for handover.

The following [command](https://pkg.go.dev/github.com/temporalio/tcld#readme-start-a-migration) is used to start the
migration:
Expand Down Expand Up @@ -323,6 +324,9 @@ tcld migration handover --id <migration-id> --to-replica-id <to-replica-id>
When using this command, replace `<to-replica-id>` with `cloud` when handing over to Temporal Cloud. Replace
`<to-replica-id>` with `on-prem` when handing back to the self-hosted setup.

Now is an excellent time to review the process of [transferring clients](#transfer-clients-to-cloud) to Temporal Cloud.


## Phase 5: Finalize

### Final validation
Expand Down Expand Up @@ -432,37 +436,6 @@ history.enableReplicationStream:

Enabling this configuration will require a restart of your history pods.

## Frequently asked questions

**Why does it matter if custom search attributes are used?**

Custom search attributes must be mapped to the Namespace in Temporal Cloud. This process differs depending on the type
of data store used for visibility.

**What Workflows are migrated by default?**

Open workflows are always migrated. You may specify a date range for closed Workflows. Limiting the time range for
closed Workflows will greatly reduce the amount of time it takes to migrate a Namespace. Your cloud-side Namespace must
be configured with your desired retention period prior to starting the migration.

**I have a long retention period for my Workflows. Is this compatible with Temporal Cloud?**

Occasionally, self-hosted [retention periods](/temporal-service/temporal-server#retention-period) are in excess of what
is [supported](/cloud/limits#default-retention-period) in Temporal Cloud. In these cases it is recommended to utilize
[archival](/temporal-service/archival) to store closed Workflows that cannot be migrated. In general, archival is
recommended over large retention periods since the extra data can stress the persistence layer of the system.

**I am using payload encryption in my self-hosted Temporal cluster. Is this supported in cloud?**

Yes. If payloads are already [encrypted](/payload-codec#encryption) in your self-hosted server via data converter, then
they will remain encrypted during and after migration.


**I would like to enable payload encryption as part of the migration. Is this supported?**

Enabling payload encryption as part of the migration is not currently supported. If encryption is required, then the best
approach is to enable it prior to migrating.

## How to gather self-hosted metrics

Temporal Server (version > 1.17) provides an [action](/cloud/pricing#action) metric. You may use Grafana to capture and
Expand Down Expand Up @@ -503,3 +476,62 @@ For Datadog, the following widget will calculate actions per second:
"precision": 2
}
```

## Frequently asked questions

### When should I opt for auto migration?
Copy link
Copy Markdown
Contributor

@lukeknep lukeknep Apr 9, 2026

Choose a reason for hiding this comment

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

I do not think the answer here addresses this question.


This is a complex question. The answer depends on your specific situation. The most common considerations are:

1. Risk of change - No matter what, clients must be updated to use the new cloud-side Namespace. The big difference is that
Copy link
Copy Markdown
Contributor

@lukeknep lukeknep Apr 8, 2026

Choose a reason for hiding this comment

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

This #1 is unclear to me. Are you saying "Automated Migration gives you the flexibility to migrate Workers in different orders / space it out over time, instead of 'all at once' ?"

automated migration enables replication between self-hosted and cloud during the migration process. This allows some flexibility
in transferring clients. If you are unsure of the impact to clients as a result of manual migration, then you may opt for the automated approach.
2. Effort - There are certain time-related costs involved with the setup of the components required for automated migration. Mostly, these costs
involve deployment of dedicated cloud-based components (Temporal), s2s proxy setup (customer/Temporal), and
general project management. If your self-hosted clusters do not meet the [minimum requirements](#limitations) requirements, then there may
be additional work required as a prerequisite to starting the project.

### Can I split Workflows from a single source Namespace into multiple cloud-side Namespaces?

Not directly. The migration tooling migrates all Workflows from a Namespace. If your goal is to split Workflows, then you should
manually migrate any workflows into their new cloud-side targets prior to starting an auto-migration.
Copy link
Copy Markdown
Contributor

@lukeknep lukeknep Apr 9, 2026

Choose a reason for hiding this comment

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

Can we link to a docs page about how to "manually migrate a workflow" ?


### Can I combine manual and auto migration?

It depends. Auto migration requires a "fresh" target cloud-side Namespace (e.g. one that has never had a running Workflow).
Copy link
Copy Markdown
Contributor

@lukeknep lukeknep Apr 9, 2026

Choose a reason for hiding this comment

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

I would suggest this, to make it more clear:

You can, as long as the automated migration comes first. Automated migrations require a brand new Temporal Cloud Namespace. An automated migration cannot be run against a Namespace that already has running Workflows, even if those Workflows were manually migrated from your cluster.

If Workflows were manually migrated to a cloud-side Namespace, then this Namespace would not be suitable as an auto-migration target.
However, nothing prevents you from manually migrating Workflows into a Namespace from a previously completed auto-migration.

### Why does it matter if custom search attributes are used?

Custom search attributes must be mapped to the Namespace in Temporal Cloud. This process differs depending on the type
of data store used for visibility.

### What Workflows are migrated by default?

All Workflows are migrated by default. For closed Workflows, you may specify a date range to be migrated. Limiting the time range for
closed Workflows will greatly reduce the amount of time it takes to migrate a Namespace. Your cloud-side Namespace must
Copy link
Copy Markdown
Contributor

@lukeknep lukeknep Apr 9, 2026

Choose a reason for hiding this comment

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

Suggested additional FAQ: "What affects the amount of time a migration takes?" or "How can I speed up a migration?"

be configured with your desired retention period prior to starting the migration.

### Is the migration of Schedules supported?

Yes. Under the hood, Schedules are essentially Workflows.

### I have a long retention period for my Workflows. Is this compatible with Temporal Cloud?

Occasionally, self-hosted [retention periods](/temporal-service/temporal-server#retention-period) are in excess of what
Copy link
Copy Markdown
Contributor

@lukeknep lukeknep Apr 9, 2026

Choose a reason for hiding this comment

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

Do we ever spell out the max retention period we support for migrations?

is [supported](/cloud/limits#default-retention-period) in Temporal Cloud. In these cases it is recommended to utilize
[archival](/temporal-service/archival) to store closed Workflows that cannot be migrated. In general, archival is
recommended over large retention periods since the extra data can stress the persistence layer of the system.

### I am using payload encryption in my self-hosted Temporal cluster. Is this supported in cloud?

Yes. If payloads are already [encrypted](/payload-codec#encryption) in your self-hosted server via data converter, then
they will remain encrypted during and after migration.


### I would like to enable payload encryption as part of the migration. Is this supported?

Enabling payload encryption as part of the migration is not currently supported. If encryption is required, then the best
Copy link
Copy Markdown
Contributor

@lukeknep lukeknep Apr 9, 2026

Choose a reason for hiding this comment

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

Suggested rewrite: "The automated migration tooling cannot add payload encryption. To encrypt payloads sent to Temporal Cloud, you must encrypt payloads in your cluster before starting the automated migration process."

approach is to enable it prior to migrating.

Loading