docs(saas): Migration guide for orchestration arch

alexronquillo · alexronquillo · commit 98e2a11f2ac9 · 2026-03-27T12:33:33.000+01:00
diff --git a/docs/apis-tools/migration-manuals/saas-orchestration-architecture.md b/docs/apis-tools/migration-manuals/saas-orchestration-architecture.md
@@ -0,0 +1,143 @@
+---
+id: saas-orchestration-architecture
+title: "SaaS orchestration architecture"
+description: "Learn about the new streamlined SaaS orchestration architecture in Camunda 8.9."
+---
+
+import PageDescription from '@site/src/components/PageDescription';
+
+<PageDescription />
+
+## About
+
+Camunda 8.9 introduces a streamlined SaaS orchestration architecture. The runtime for Operate, Tasklist, Identity (Admin), and the Zeebe REST API is unified into a single orchestration service. Zeebe brokers continue to run separately and execute workflows as before.
+
+This is a topology change in SaaS only and does not affect Self-Managed deployments.
+
+What's new:
+
+- [Unified API domain for Orchestration Clusters](#unified-api-domain-for-orchestration-clusters). Legacy hostnames are deprecated.
+- [New client credentials use new API URLs.](#client-credentials-and-legacy-hostnames)
+- [`service` labels have changed on Orchestration Cluster metrics.](#service-label-changes)
+
+What didn't change:
+
+- The same UIs for Operate, Tasklist, and Admin/Identity and the REST API remain available as before.
+- The Zeebe gRPC endpoint is unchanged.
+
+:::info
+
+The new architecture has been validated against Camunda's documented sizing and performance expectations to prevent regressions when upgrading from 8.8.latest to 8.9.
+
+:::
+
+## Unified API domain for Orchestration Clusters
+
+Camunda 8.9 introduces a unified API domain for Orchestration Clusters. All services are now accessible under a single base URL:
+
+| Service             | Unified URL (8.9)                                            |
+| :------------------ | :----------------------------------------------------------- |
+| Base / REST API     | `https://<region>.api.<camunda-domain>/<clusterId>`          |
+| Operate UI          | `https://<region>.api.<camunda-domain>/<clusterId>/operate`  |
+| Tasklist UI         | `https://<region>.api.<camunda-domain>/<clusterId>/tasklist` |
+| Admin (Identity) UI | `https://<region>.api.<camunda-domain>/<clusterId>/admin`    |
+
+Legacy hostnames (`*.zeebe.<camunda-domain>`, `*.operate.<camunda-domain>`, `*.tasklist.<camunda-domain>`, and `*.identity.<camunda-domain>`) continue to work in 8.9 and are internally routed to the unified service, but are deprecated and scheduled for removal in 8.10.
+
+After the 8.10 release, only the Zeebe gRPC endpoint and the unified `*.api.*` ingress will remain.
+
+### Deprecation
+
+Legacy hostnames are deprecated as of 8.9 and will be removed in 8.10. Migrate any hard-coded URLs for Operate, Tasklist, or Identity to the new unified `*.api.*` URLs during the 8.9 lifecycle to ensure readiness before the 8.10 release.
+
+## Client credentials and legacy hostnames
+
+Existing client credentials downloaded from Console for pre-8.9 clusters may reference legacy hostnames. Because those hostnames remain available in 8.9, existing credentials continue to work after a cluster is upgraded to 8.9. No immediate action is required.
+
+### Recommended action
+
+For long-lived automation and CI/CD systems, Camunda recommends updating credentials to use the new unified `*.api.*` URLs and corresponding token audience values before 8.10. You have two options:
+
+- **Update existing credentials manually:** Edit the hostnames and token audience values in your existing credential configuration to reference the new unified URLs.
+- **Create new credentials:** Create a fresh set of client credentials in Camunda Console, which will be generated with the unified API URLs and correct audience values by default.
+
+## Service label changes
+
+<span className="badge badge--breaking-change">Breaking change</span>
+
+Due to the streamlined orchestration architecture introduced in 8.9, metrics previously emitted by the individual Operate, Tasklist, and Identity services are now emitted by the unified orchestration service. As a result, the `service` label on affected metrics will change to reflect the new source service.
+
+This applies to Camunda 8 SaaS clusters using the [Cluster Metrics endpoint](/components/saas/monitoring/cluster-metrics-endpoint/set-up-cluster-metrics-endpoint.md).
+
+### Impact
+
+Monitoring dashboards, alerting rules, or queries that filter or group by the `service` label on Orchestration Cluster metrics may stop matching expected values after upgrading to 8.9, as some metrics will now be emitted by a different source service.
+
+### Action required
+
+After your cluster is upgraded to 8.9, review your dashboards and alerting rules and verify the `service` label values metrics are returning. Update any Prometheus queries or alert definitions that no longer match.
+
+## Upgrade behavior and expected downtime
+
+When a Camunda 8 SaaS Orchestration Cluster is upgraded from 8.8 to 8.9:
+
+1. The existing Operate and Tasklist components are shut down.
+2. The unified orchestration service starts in their place.
+3. Ingress routes are updated so legacy hostnames continue to resolve while the new `*.api.*` endpoints become active.
+
+### Impact during upgrade
+
+- **Web UIs and REST API:** You should expect a short interruption while the old services are removed and the unified service becomes ready.
+- **Workflow execution (Zeebe brokers):** Designed to remain running throughout the upgrade. The primary impact is limited to UI and API availability, not to engine execution state.
+
+To upgrade, initiate the cluster upgrade to 8.9 from Camunda Console. No additional steps are required beyond the URL and credential recommendations above.
+
+## SaaS: Streamlined orchestration architecture
+
+Camunda 8.9 introduces a streamlined SaaS orchestration architecture. The runtime for Operate, Tasklist, Identity (Admin), and the Zeebe REST API is unified into a single orchestration service. Zeebe brokers continue to run separately and execute workflows as before.
+
+This is a topology change in SaaS only and does not affect Self-Managed deployments.
+
+What changed:
+
+- Unified API domain for Orchestration Clusters. Legacy hostnames are deprecated.
+- New client credentials use new API URLs.
+- Service labels have changed on Orchestration Cluster metrics.
+
+What didn't change:
+
+- The same UIs (Operate, Tasklist, Admin/Identity) and REST API remain available as before.
+- The Zeebe gRPC endpoint is unchanged.
+
+:::info
+
+The new architecture has been validated against Camunda's documented sizing and performance expectations to prevent regressions when upgrading from 8.8.latest to 8.9.
+
+:::
+
+### Unified API domain for Orchestration Clusters
+
+Camunda 8.9 introduces a unified API domain for Orchestration Clusters. All services are now accessible under a single base URL:
+
+| Service             | Unified URL (8.9)                                            |
+| :------------------ | :----------------------------------------------------------- |
+| Base / REST API     | `https://<region>.api.<camunda-domain>/<clusterId>`          |
+| Operate UI          | `https://<region>.api.<camunda-domain>/<clusterId>/operate`  |
+| Tasklist UI         | `https://<region>.api.<camunda-domain>/<clusterId>/tasklist` |
+| Admin (Identity) UI | `https://<region>.api.<camunda-domain>/<clusterId>/admin`    |
+
+Legacy hostnames (`*.zeebe.<camunda-domain>`, `*.operate.<camunda-domain>`, `*.tasklist.<camunda-domain>`, and `*.identity.<camunda-domain>`) continue to work in 8.9 and are internally routed to the unified service, but are deprecated and scheduled for removal in 8.10.
+
+After the 8.10 release, only the Zeebe gRPC endpoint and the unified `*.api.*` ingress will remain.
+
+#### Deprecation
+
+Legacy hostnames are deprecated as of 8.9 and will be removed in 8.10. Migrate any hard-coded URLs for Operate, Tasklist, or Identity to the new unified _.api._ URLs during the 8.9 lifecycle to ensure readiness before the 8.10 release.
+
+#### Are you affected?
+
+This change applies to you if you are using the Orchestration Cluster APIs with Camunda 8 Saas.
+
+### Client credentials
+
+Existing client credentials downloaded from Console for pre-8.9 clusters may reference legacy hostnames. Because those hostnames remain available in 8.9, existing credentials continue to work after a cluster is upgraded to 8.9. No immediate action is required.
diff --git a/docs/apis-tools/operate-api/overview.md b/docs/apis-tools/operate-api/overview.md
@@ -20,7 +20,7 @@ Work with this API in our [Postman collection](https://www.postman.com/camundate
 
 ## Context paths
 
-For SaaS: `https://${REGION}.operate.camunda.io:443/${CLUSTER_ID}/v1/`, and for Self-Managed installations: `http://localhost:8080/v1/`.
+For SaaS: `https://${REGION}.api.camunda.io:443/${CLUSTER_ID}/operate/v1/`, and for Self-Managed installations: `http://localhost:8080/v1/`.
 
 :::note
 Find your **region Id** and **cluster Id** under **Connection information** in your client credentials (revealed when you click on your client under the **API** tab within your cluster).
@@ -36,7 +36,7 @@ See [the interactive Operate API Explorer][operate-api-explorer] for specificati
 
 A Swagger UI is also available within a running instance of Operate, at `https://${base-url}/swagger-ui/index.html`.
 
-For SaaS: `https://${REGION}.operate.camunda.io/${CLUSTER_ID}/swagger-ui.html`, and for Self-Managed installations: `http://localhost:8080/swagger-ui.html`.
+For SaaS: `https://${REGION}.api.camunda.io/${CLUSTER_ID}/operate/swagger-ui.html`, and for Self-Managed installations: `http://localhost:8080/swagger-ui.html`.
 
 :::note
 Find your **region Id** and **cluster Id** under **Connection information** in your client credentials (revealed when you click on your client under the **API** tab within your cluster).
diff --git a/docs/apis-tools/orchestration-cluster-api-mcp/orchestration-cluster-api-mcp-setup.md b/docs/apis-tools/orchestration-cluster-api-mcp/orchestration-cluster-api-mcp-setup.md
@@ -83,7 +83,7 @@ The MCP server is served at `/mcp/cluster` on the Orchestration Cluster. The ful
 | :------------------------- | :------------------------------------------------------------------------------ |
 | Camunda 8 Run              | `http://localhost:8080/mcp/cluster`                                             |
 | Docker Compose             | `http://localhost:8080/mcp/cluster`                                             |
-| SaaS – public connectivity | `https://${REGION_ID}.zeebe.camunda.io/${CLUSTER_ID}/mcp/cluster`               |
+| SaaS – public connectivity | `https://${REGION_ID}.api.camunda.io/${CLUSTER_ID}/mcp/cluster`                 |
 | SaaS – secure connectivity | `https://${CLUSTER_ID}.${REGION_ID}.privateconnectivity.camunda.io/mcp/cluster` |
 | Self-Managed (custom)      | `https://<your-host>/mcp/cluster`                                               |
 
diff --git a/docs/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview.md b/docs/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview.md
@@ -80,7 +80,7 @@ curl http://localhost:8080/v2/topology
 SaaS, public connectivity:
 
 ```bash
-curl https://${REGION_ID}.zeebe.camunda.io/${CLUSTER_ID}/v2/topology
+curl https://${REGION_ID}.api.camunda.io/${CLUSTER_ID}/v2/topology
 ```
 
 SaaS, secure connectivity (AWS PrivateLink):
@@ -123,7 +123,7 @@ This section covers the technical details and conventions you need to understand
 
 In the Camunda Console, go to your cluster, and in the Cluster Details, find your **Region Id** and **Cluster Id**.
 
-- For public connectivity (default), use this pattern as your `${BASE_URL}`: `https://${REGION_ID}.zeebe.camunda.io/${CLUSTER_ID}/v2/`
+- For public connectivity (default), use this pattern as your `${BASE_URL}`: `https://${REGION_ID}.api.camunda.io/${CLUSTER_ID}/v2/`
 
 - For secure connectivity (AWS PrivateLink), use the private base URL shown in Console. For the Orchestration Cluster REST API, the pattern is:
 
diff --git a/docs/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-swagger.md b/docs/apis-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-swagger.md
@@ -30,15 +30,15 @@ For SaaS clusters, Swagger UI is accessible through your cluster's dedicated end
 
 1. In the Camunda Console, go to your cluster
 2. In **Cluster Details**, find your **Region ID** and **Cluster ID**
-3. Use this URL format: `https://${REGION_ID}.operate.camunda.io/${CLUSTER_ID}/swagger`
+3. Use this URL format: `https://${REGION_ID}.api.camunda.io/${CLUSTER_ID}/operate/swagger`
 
 :::note
 Swagger UI is protected with CSRF. If you are logged into the Camunda Console, you can access Swagger UI directly. If not, you may need to log in first.
 :::
 
-**Example:**  
+**Example:**
 If your Region ID is `bru-2` and Cluster ID is `abc123-def456-ghi789`, your Swagger UI URL would be:
-`https://bru-2.operate.camunda.io/abc123-def456-ghi789/swagger`
+`https://bru-2.api.camunda.io/abc123-def456-ghi789/operate/swagger`
 
 ### Self-Managed
 
diff --git a/docs/apis-tools/tasklist-api-rest/tasklist-api-rest-overview.md b/docs/apis-tools/tasklist-api-rest/tasklist-api-rest-overview.md
@@ -17,7 +17,7 @@ Ensure you [authenticate](./tasklist-api-rest-authentication.md) before accessin
 
 ## Context paths
 
-For SaaS: `https://${REGION}.tasklist.camunda.io:443/${CLUSTER_ID}/v1/`, and for Self-Managed installations: `http://localhost:8080/v1/`.
+For SaaS: `https://${REGION}.api.camunda.io:443/${CLUSTER_ID}/tasklist/v1/`, and for Self-Managed installations: `http://localhost:8080/v1/`.
 
 :::note
 Find your **region Id** and **cluster Id** under **Connection information** in your client credentials (revealed when you click on your client under the **API** tab within your cluster).
@@ -33,7 +33,7 @@ See [the interactive Tasklist REST API Explorer][tasklist-api-explorer] for spec
 
 A detailed API description is also available as a Swagger UI at `https://${base-url}/swagger-ui/index.html`.
 
-For SaaS: `https://${REGION}.tasklist.camunda.io:443/${CLUSTER_ID}/swagger-ui/index.html`, and for Self-Managed installations: [`http://localhost:8080/swagger-ui/index.html`](http://localhost:8080/swagger-ui/index.html).
+For SaaS: `https://${REGION}.api.camunda.io:443/${CLUSTER_ID}/tasklist/swagger-ui/index.html`, and for Self-Managed installations: [`http://localhost:8080/swagger-ui/index.html`](http://localhost:8080/swagger-ui/index.html).
 
 :::note
 Find your **region Id** and **cluster Id** under **Connection information** in your client credentials (revealed when you click on your client under the **API** tab within your cluster).
diff --git a/docs/apis-tools/zeebe-api-rest/zeebe-api-rest-overview.md b/docs/apis-tools/zeebe-api-rest/zeebe-api-rest-overview.md
@@ -18,7 +18,7 @@ Ensure you [authenticate](./zeebe-api-rest-authentication.md) before accessing t
 
 Find your **region Id** and **cluster Id** under **Connection information** in your client credentials (revealed when you click on your client under the **API** tab within your cluster).
 
-Example path: `https://${REGION}.zeebe.camunda.io:443/${CLUSTER_ID}/v1/`
+Example path: `https://${REGION}.api.camunda.io:443/${CLUSTER_ID}/v1/`
 
 ### Self-Managed
 
diff --git a/docs/components/connectors/custom-built-connectors/host-custom-connector.md b/docs/components/connectors/custom-built-connectors/host-custom-connector.md
@@ -33,7 +33,7 @@ docker run --rm --name=CustomConnectorInSaaS \
     -e CAMUNDA_CLIENT_CLOUD_CLIENT-ID='<YOUR_CLIENT_ID>' \
     -e CAMUNDA_CLIENT_CLOUD_CLIENT-SECRET='<YOUR_CLIENT_SECRET>' \
     -e CAMUNDA_CLIENT_CLOUD_REGION='<YOUR_CLUSTER_REGION>' \
-    -e CAMUNDA_OPERATE_CLIENT_URL='https://<region>.operate.camunda.io/<cluster-id>' \
+    -e CAMUNDA_OPERATE_CLIENT_URL='https://<region>.api.camunda.io/<cluster-id>/operate' \
         camunda/connectors-bundle:<desired-version>
 ```
 
diff --git a/docs/components/modeler/web-modeler/modeling/advanced-modeling/publish-public-processes.md b/docs/components/modeler/web-modeler/modeling/advanced-modeling/publish-public-processes.md
@@ -102,7 +102,7 @@ Unfortunately, currently you can not define granular permissions for shared proc
 
 Check the link URL. It should follow this pattern:
 
-`https://<region-identifier>.tasklist.camunda.io/<cluster-uuid>/new/<process-ID>`
+`https://<region-identifier>.api.camunda.io/<cluster-uuid>/tasklist/new/<process-ID>`
 
 ### Are public links indexed by search engines?
 
diff --git a/sidebars.js b/sidebars.js
@@ -1406,6 +1406,7 @@ module.exports = {
         "apis-tools/migration-manuals/migrate-to-camunda-spring-boot-starter",
         "apis-tools/migration-manuals/migrate-to-camunda-process-test",
         "apis-tools/migration-manuals/migrate-from-grpc-to-orchestration-cluster-api",
+        "apis-tools/migration-manuals/saas-orchestration-architecture",
       ],
     },
   ],
