diff --git a/docs/apis-tools/migration-manuals/saas-orchestration-architecture.md b/docs/apis-tools/migration-manuals/saas-orchestration-architecture.md new file mode 100644 index 00000000000..3f1cf032258 --- /dev/null +++ b/docs/apis-tools/migration-manuals/saas-orchestration-architecture.md @@ -0,0 +1,87 @@ +--- +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'; + + + +## 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 and will remain accessible until 8.10. +- [New client credentials use new API URLs.](#client-credentials-and-legacy-hostnames) +- [Cluster Metrics endpoint: `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. + +## 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://.api./` | +| Operate UI | `https://.api.//operate` | +| Tasklist UI | `https://.api.//tasklist` | +| Admin (Identity) UI | `https://.api.//admin` | + +Legacy hostnames (`*.zeebe.`, `*.operate.`, `*.tasklist.`, and `*.identity.`) 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 + +Breaking change + +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. diff --git a/docs/apis-tools/operate-api/overview.md b/docs/apis-tools/operate-api/overview.md index 3f8e1358d19..f78bb93662a 100644 --- 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 index c507da0d291..5a0d989e437 100644 --- 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:///mcp/cluster` | @@ -140,13 +140,13 @@ Add the following to your MCP client configuration (for example, `.vscode/mcp.js } ``` -| Variable | Description | -| :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `CAMUNDA_BASE_URL` | Base URL of your Orchestration Cluster, **without** the `/mcp/cluster` path (for example, the public `zeebe.camunda.io` URL or the private `privateconnectivity.camunda.io` URL when using Secure connectivity). | -| `CAMUNDA_CLIENT_ID` | OAuth client ID from your API client credentials. | -| `CAMUNDA_CLIENT_SECRET` | OAuth client secret from your API client credentials. | -| `CAMUNDA_OAUTH_URL` | OAuth token endpoint URL. | -| `CAMUNDA_TOKEN_AUDIENCE` | Token audience for the Orchestration Cluster API. | +| Variable | Description | +| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `CAMUNDA_BASE_URL` | Base URL of your Orchestration Cluster, **without** the `/mcp/cluster` path (for example, the public `api.camunda.io` URL or the private `privateconnectivity.camunda.io` URL when using Secure connectivity). | +| `CAMUNDA_CLIENT_ID` | OAuth client ID from your API client credentials. | +| `CAMUNDA_CLIENT_SECRET` | OAuth client secret from your API client credentials. | +| `CAMUNDA_OAUTH_URL` | OAuth token endpoint URL. | +| `CAMUNDA_TOKEN_AUDIENCE` | Token audience for the Orchestration Cluster API. | :::tip Where to find these values When you [create API client credentials](/components/console/manage-clusters/manage-api-clients.md#create-a-client) in the Camunda Console, all required connection details — including the base URL, OAuth endpoint, client ID, and audience — are displayed on the credentials page. You can also copy a ready-to-use `c8ctl` configuration snippet directly from the **MCP** tab on the credentials screen. @@ -198,7 +198,7 @@ camunda: camunda-mcp: type: http http: - url: https://${REGION_ID}.zeebe.camunda.io/${CLUSTER_ID}/mcp/cluster + url: https://${REGION_ID}.api.camunda.io/${CLUSTER_ID}/mcp/cluster authentication: type: oauth oauth: 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 index b729acca6e0..dfa5a1a0efb 100644 --- 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 index 3de660f8f9f..807d590d7d1 100644 --- 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}/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/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 index 312d8877f6f..3bb9f4c385a 100644 --- 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}/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}/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 index a99cac9db94..cc220acbba3 100644 --- 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/camunda-integrations/servicenow/setup-and-configuration.md b/docs/components/camunda-integrations/servicenow/setup-and-configuration.md index 4048bf058ba..af9b4841722 100644 --- a/docs/components/camunda-integrations/servicenow/setup-and-configuration.md +++ b/docs/components/camunda-integrations/servicenow/setup-and-configuration.md @@ -79,7 +79,7 @@ Ensure the following prerequisites are in place: | Domain | `Global` | | Connection alias ID | `x_camun_camunda.Camunda` | | URL Builder | Enabled | -| Host | Camunda cluster Region ID (e.g., `lhr-1.zeebe.camunda.io`) | +| Host | Camunda cluster Region ID (e.g., `lhr-1.api.camunda.io`) | | Protocol | `https` | | Base path | Camunda Cluster ID (e.g., `/6b6b3969-a65c-4bdd-905e-c29102eebded`) | diff --git a/docs/components/connectors/custom-built-connectors/host-custom-connector.md b/docs/components/connectors/custom-built-connectors/host-custom-connector.md index 6ed8f937afd..35dcfa12747 100644 --- 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='' \ -e CAMUNDA_CLIENT_CLOUD_CLIENT-SECRET='' \ -e CAMUNDA_CLIENT_CLOUD_REGION='' \ - -e CAMUNDA_OPERATE_CLIENT_URL='https://.operate.camunda.io/' \ + -e CAMUNDA_OPERATE_CLIENT_URL='https://.api.camunda.io/' \ camunda/connectors-bundle: ``` 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 index 1d975bb0903..9604797125f 100644 --- 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://.tasklist.camunda.io//new/` +`https://.api.camunda.io//new/` ### Are public links indexed by search engines? diff --git a/sidebars.js b/sidebars.js index e0583460106..764fe1b2cee 100644 --- 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", ], }, ],