From f2eac7bc29431ecece911e5174f296338ff8ff11 Mon Sep 17 00:00:00 2001 From: Luke Knepper Date: Wed, 5 Aug 2026 16:30:24 -0700 Subject: [PATCH 1/3] Explain migration endpoint and S2S Proxy cardinality Document that a migration endpoint pairs exactly one self-hosted server with one migration server, and that a single migration server can hold multiple endpoints. This allows several self-hosted S2S Proxy deployments to connect to the same migration server and migrate Namespaces in parallel, provided each self-hosted server has a unique cluster name and Initial Failover Version. Replaces the partial description in Limitations with a pointer to the new section, and adds an FAQ entry for the question as customers ask it. Co-Authored-By: Claude Opus 5 --- docs/cloud/migrate/automated.mdx | 43 +++++++++++++++++++++++++++----- 1 file changed, 37 insertions(+), 6 deletions(-) diff --git a/docs/cloud/migrate/automated.mdx b/docs/cloud/migrate/automated.mdx index 7db5a690b8..25c5922978 100644 --- a/docs/cloud/migrate/automated.mdx +++ b/docs/cloud/migrate/automated.mdx @@ -175,6 +175,33 @@ Proceed only when your request has been approved by Temporal. ::: +### Plan migration endpoints + +A migration endpoint is a cloud-side resource that pairs one self-hosted server with one migration server in Temporal +Cloud. Temporal creates these endpoints and provides the `endpoint-id` values used with the `tcld migration` commands in +later phases. + +The components relate as follows: + +- Each self-hosted server connects through its own S2S Proxy deployment and its own migration endpoint. This pairing is + always one-to-one. +- A single migration server can hold multiple migration endpoints, one for each self-hosted server. Several self-hosted + S2S Proxy deployments can therefore connect to the same migration server, which allows you to migrate Namespaces from + multiple self-hosted servers in parallel. + +To connect multiple self-hosted servers to one migration server at the same time, each self-hosted server must have a +unique cluster name and a unique Initial Failover Version. Temporal uses `active` as the default cluster name, so +servers that still use the default will collide. See [Modify cluster configuration](#modify-cluster-configuration) for +setting these values. + +If your self-hosted servers cannot use unique cluster names, you have two options: + +1. Migrate one server at a time through a single migration server. +2. Ask Temporal to provision multiple migration servers, one for each self-hosted server, if you need to migrate from + all of them at the same time. + +Tell Temporal how many self-hosted servers you plan to migrate from and whether those migrations run in parallel, so +that the correct number of endpoints and migration servers can be provisioned. ### S2S Proxy configuration @@ -445,12 +472,9 @@ The following are known limitations. - OSS server versions 1.22 or newer are required. Refer to the [upgrade](/self-hosted-guide/upgrade-server#upgrade-server) procedure as needed. - History shard counts must be a power of two (eg. 512, 1024, etc...). -- If you have multiple self-hosted servers and they are all configured with the same cluster name (by default Temporal - uses 'active' as cluster name), they cannot be connected to a single migration server simultaneously due to cluster - name collision. There are 2 available options: - 1. Migrate one server at a time using a single migration server. - 2. Create multiple migration servers (one for each self-hosted server) if you need to migrate all servers - simultaneously. +- Self-hosted servers that connect to the same migration server at the same time must each have a unique cluster name + and Initial Failover Version. Servers that share a cluster name, such as the default `active`, collide. See + [Plan migration endpoints](#plan-migration-endpoints) for the available options. - If you are using multi-cluster replication in your self-hosted setup and have previously failed over Namespaces, then this may impact your eligibility for automated migration. Specifically, whenever Global Namespace has been previously enabled the following restrictions apply: @@ -495,6 +519,13 @@ The answer depends on your specific situation. However, automated migration is m In contrast, automated migration may not be the best solution if your self-hosted clusters do not meet the [minimum requirements](#limitations). +### Can I connect multiple self-hosted S2S Proxy deployments to a single migration server? + +Yes. Temporal creates one migration endpoint per self-hosted server, and a single migration server can hold multiple +endpoints. This lets you migrate Namespaces from several self-hosted servers, such as separate development and +production servers, in parallel. Each self-hosted server must have a unique cluster name and Initial Failover Version. +See [Plan migration endpoints](#plan-migration-endpoints). + ### Can I split Workflows from a single source Namespace into multiple cloud-side Namespaces? No. All Workflows will be migrated. From 555caa8a7a928ce06189863ae8398a37ae809213 Mon Sep 17 00:00:00 2001 From: Luke Knepper Date: Thu, 6 Aug 2026 14:54:03 -0700 Subject: [PATCH 2/3] Remove internal topology detail from migration endpoint docs Drop the description of multiple endpoints residing on one cloud-side migration server, which is internal configuration customers neither control nor need. Frame the guidance around what the customer does: one S2S Proxy deployment and one migration endpoint per self-hosted server, with unique cluster names and Initial Failover Versions when migrating from several servers at once. Co-Authored-By: Claude Opus 5 --- docs/cloud/migrate/automated.mdx | 47 ++++++++++++-------------------- 1 file changed, 17 insertions(+), 30 deletions(-) diff --git a/docs/cloud/migrate/automated.mdx b/docs/cloud/migrate/automated.mdx index 25c5922978..f0959dc6d5 100644 --- a/docs/cloud/migrate/automated.mdx +++ b/docs/cloud/migrate/automated.mdx @@ -177,31 +177,20 @@ Proceed only when your request has been approved by Temporal. ### Plan migration endpoints -A migration endpoint is a cloud-side resource that pairs one self-hosted server with one migration server in Temporal -Cloud. Temporal creates these endpoints and provides the `endpoint-id` values used with the `tcld migration` commands in -later phases. +A migration endpoint is a cloud-side resource that connects one of your self-hosted servers to Temporal Cloud. Temporal +creates the endpoints and provides the `endpoint-id` values used with the `tcld migration` commands in later phases. -The components relate as follows: +Each self-hosted server you migrate from needs its own S2S Proxy deployment and its own migration endpoint. You can +migrate from more than one self-hosted server at the same time, such as separate development and production servers, +provided each self-hosted server has a unique cluster name and Initial Failover Version. Temporal uses `active` as the +default cluster name, so servers that still use the default will collide. See +[Modify cluster configuration](#modify-cluster-configuration) for setting these values. -- Each self-hosted server connects through its own S2S Proxy deployment and its own migration endpoint. This pairing is - always one-to-one. -- A single migration server can hold multiple migration endpoints, one for each self-hosted server. Several self-hosted - S2S Proxy deployments can therefore connect to the same migration server, which allows you to migrate Namespaces from - multiple self-hosted servers in parallel. +If your self-hosted servers cannot use unique cluster names, migrate one server at a time, or contact Temporal to +discuss the available options. -To connect multiple self-hosted servers to one migration server at the same time, each self-hosted server must have a -unique cluster name and a unique Initial Failover Version. Temporal uses `active` as the default cluster name, so -servers that still use the default will collide. See [Modify cluster configuration](#modify-cluster-configuration) for -setting these values. - -If your self-hosted servers cannot use unique cluster names, you have two options: - -1. Migrate one server at a time through a single migration server. -2. Ask Temporal to provision multiple migration servers, one for each self-hosted server, if you need to migrate from - all of them at the same time. - -Tell Temporal how many self-hosted servers you plan to migrate from and whether those migrations run in parallel, so -that the correct number of endpoints and migration servers can be provisioned. +Tell Temporal how many self-hosted servers you plan to migrate from, and whether you intend to migrate from them in +parallel, so that the required cloud-side resources are in place. ### S2S Proxy configuration @@ -472,9 +461,9 @@ The following are known limitations. - OSS server versions 1.22 or newer are required. Refer to the [upgrade](/self-hosted-guide/upgrade-server#upgrade-server) procedure as needed. - History shard counts must be a power of two (eg. 512, 1024, etc...). -- Self-hosted servers that connect to the same migration server at the same time must each have a unique cluster name - and Initial Failover Version. Servers that share a cluster name, such as the default `active`, collide. See - [Plan migration endpoints](#plan-migration-endpoints) for the available options. +- Self-hosted servers that are migrated at the same time must each have a unique cluster name and Initial Failover + Version. Servers that share a cluster name, such as the default `active`, collide. See + [Plan migration endpoints](#plan-migration-endpoints). - If you are using multi-cluster replication in your self-hosted setup and have previously failed over Namespaces, then this may impact your eligibility for automated migration. Specifically, whenever Global Namespace has been previously enabled the following restrictions apply: @@ -519,12 +508,10 @@ The answer depends on your specific situation. However, automated migration is m In contrast, automated migration may not be the best solution if your self-hosted clusters do not meet the [minimum requirements](#limitations). -### Can I connect multiple self-hosted S2S Proxy deployments to a single migration server? +### Can I migrate from multiple self-hosted servers at the same time? -Yes. Temporal creates one migration endpoint per self-hosted server, and a single migration server can hold multiple -endpoints. This lets you migrate Namespaces from several self-hosted servers, such as separate development and -production servers, in parallel. Each self-hosted server must have a unique cluster name and Initial Failover Version. -See [Plan migration endpoints](#plan-migration-endpoints). +Yes. Each self-hosted server needs its own S2S Proxy deployment and its own migration endpoint, and each must have a +unique cluster name and Initial Failover Version. See [Plan migration endpoints](#plan-migration-endpoints). ### Can I split Workflows from a single source Namespace into multiple cloud-side Namespaces? No. All Workflows will be migrated. From 2d3619dec0c99b0e70d65a3d533a1237a01ca254 Mon Sep 17 00:00:00 2001 From: Luke Knepper Date: Fri, 7 Aug 2026 15:31:44 -0700 Subject: [PATCH 3/3] Clarify proxy test address and per-Namespace migration parallelism Readers were pointing the connectivity test at a cloud-side address, and the page only answered parallelism for multiple self-hosted servers, not for multiple Namespaces on one server. Co-Authored-By: Claude Opus 5 --- docs/cloud/migrate/automated.mdx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/cloud/migrate/automated.mdx b/docs/cloud/migrate/automated.mdx index 09625f7815..9b5371d8b7 100644 --- a/docs/cloud/migrate/automated.mdx +++ b/docs/cloud/migrate/automated.mdx @@ -196,6 +196,11 @@ default cluster name, so servers that still use the default will collide. See If your self-hosted servers cannot use unique cluster names, migrate one server at a time, or contact Temporal to discuss the available options. +Namespaces migrating from the same self-hosted server share that server's proxy and endpoint. You can migrate more than +one Namespace from a server at the same time, provided each source Namespace and its cloud-side target are listed in +the `namespaceTranslation` mappings of that server's proxy configuration. See +[S2S Proxy configuration](#s2s-proxy-configuration). + Tell Temporal how many self-hosted servers you plan to migrate from, and whether you intend to migrate from them in parallel, so that the required cloud-side resources are in place. @@ -238,6 +243,9 @@ namespaceTranslation: ``` 5. Test access using the command below. It should display the information of the migration server. + The address is your own proxy's external address, not a cloud-side address. It's the same value you set as + `replicationEndpoint` under `clusterConnections` in your proxy configuration file. + ``` temporal operator cluster describe --address {the-outbound-external-address-of-your-proxy} ``` @@ -520,6 +528,12 @@ In contrast, automated migration may not be the best solution if your self-hoste Yes. Each self-hosted server needs its own S2S Proxy deployment and its own migration endpoint, and each must have a unique cluster name and Initial Failover Version. See [Plan migration endpoints](#plan-migration-endpoints). +### Can I migrate multiple Namespaces from the same self-hosted server at the same time? + +Yes. Those Namespaces share the server's proxy and endpoint, so no additional cloud-side resources are needed. Include +each source Namespace and its cloud-side target in the `namespaceTranslation` mappings of that server's proxy +configuration. See [S2S Proxy configuration](#s2s-proxy-configuration). + ### Can I split Workflows from a single source Namespace into multiple cloud-side Namespaces? No. All Workflows will be migrated.