From f6049fa41cc52751b25b5ca4dcb7a566635d7ce1 Mon Sep 17 00:00:00 2001 From: Samuele Verzi Date: Thu, 30 Jul 2026 10:32:42 +0200 Subject: [PATCH 1/4] Document registry server_api_url for the Cloud UI The enterprise config's registry directive now carries two URLs (stacklok-enterprise-platform#2823): api_url stays the ToolHive- client-shaped registry endpoint, and the new server_api_url is the Registry Server API root the Cloud UI resolves against. The Cloud UI's "Registry API URL resolution" section previously named api_url as the config-server source, which is now the one value it ignores. Also documents the upgrade-ordering rule: the Enterprise Manager rejects unknown config fields, so deploy the platform version that introduces the field before setting it. --- .../enterprise-cloud-ui/configure.mdx | 17 ++++++++-- .../enterprise-manager/policies/registry.mdx | 34 +++++++++++++++++++ 2 files changed, 49 insertions(+), 2 deletions(-) diff --git a/docs/platform/enterprise-cloud-ui/configure.mdx b/docs/platform/enterprise-cloud-ui/configure.mdx index 95a52664..ac5e35a1 100644 --- a/docs/platform/enterprise-cloud-ui/configure.mdx +++ b/docs/platform/enterprise-cloud-ui/configure.mdx @@ -271,8 +271,8 @@ browser always loads them over the same protocol it uses to access the Cloud UI The Cloud UI resolves the Registry Server API URL dynamically: 1. If an [Enterprise Manager](../enterprise-manager/index.mdx) is configured and - the [registry policy](../enterprise-manager/policies/registry.mdx) has an - `api_url` value, the Cloud UI uses that URL. + the [registry policy](../enterprise-manager/policies/registry.mdx) has a + `server_api_url` value, the Cloud UI uses that URL. 2. Otherwise, the Cloud UI falls back to the `API_BASE_URL` environment variable. @@ -280,6 +280,19 @@ This means you can omit `API_BASE_URL` entirely and let the Enterprise Manager control the registry URL, or set `API_BASE_URL` as a fallback for when the Enterprise Manager is unreachable. +:::note + +The Cloud UI reads the registry policy's `server_api_url` (the Registry Server's +API root), not its `api_url`. The `api_url` value is shaped for ToolHive clients +and typically points at a single registry (for example, +`https://registry.example.com/registry/toolhive`); the Cloud UI's API routes are +relative to the server root, so pointing it at the client-shaped URL results in +`404` errors. See +[Registry URL for the Cloud UI](../enterprise-manager/policies/registry.mdx#registry-url-for-the-cloud-ui) +for details. + +::: + ## Feature flags The [Enterprise Manager](../enterprise-manager/index.mdx) controls Cloud UI diff --git a/docs/platform/enterprise-manager/policies/registry.mdx b/docs/platform/enterprise-manager/policies/registry.mdx index b19d887a..cfa32cce 100644 --- a/docs/platform/enterprise-manager/policies/registry.mdx +++ b/docs/platform/enterprise-manager/policies/registry.mdx @@ -67,6 +67,40 @@ enterpriseConfig: enforcement: 'enforced' ``` +### Registry URL for the Cloud UI + +The registry directive carries two distinct URLs because its two consumers +expect different shapes. The `api_url` value is for ToolHive clients (CLI and +Stacklok Desktop) and typically points at a single registry on your Registry +Server (for example, `https://registry.acme.com/registry/toolhive`). The +[Enterprise Cloud UI](../../enterprise-cloud-ui/configure.mdx) instead needs the +Registry Server's API root, set with `server_api_url`: + +```yaml title="values.yaml" +enterpriseConfig: + registry: + value: + # For ToolHive clients: the registry API URL (one registry) + api_url: 'https://registry.acme.com/registry/toolhive' + # For the Cloud UI: the Registry Server's API root + server_api_url: 'https://registry.acme.com' + enforcement: 'enforced' +``` + +Don't point the Cloud UI at the client-shaped `api_url` — its API routes are +relative to the server root, so requests return `404` errors. When +`server_api_url` isn't set, the Cloud UI falls back to its `API_BASE_URL` +environment variable (see +[Registry API URL resolution](../../enterprise-cloud-ui/configure.mdx#registry-api-url-resolution)). + +:::warning + +The Enterprise Manager rejects configuration fields it doesn't recognize and +refuses to start. When upgrading, deploy the platform version that introduces +`server_api_url` **before** adding the field to your configuration. + +::: + ## Next steps - [Non-registry servers policy](./non-registry-servers.mdx) to control whether From fc30779911659b103c83eb17ebb4ecc2c93041f7 Mon Sep 17 00:00:00 2001 From: Samuele Verzi Date: Thu, 30 Jul 2026 10:40:59 +0200 Subject: [PATCH 2/4] Address Copilot review: URL shapes and em dash Acknowledge both api_url shapes (registry root vs per-registry path on a Stacklok Registry Server) instead of implying one is typical, and remove the em dash per the style guide. --- docs/platform/enterprise-cloud-ui/configure.mdx | 6 +++--- docs/platform/enterprise-manager/policies/registry.mdx | 7 ++++--- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/platform/enterprise-cloud-ui/configure.mdx b/docs/platform/enterprise-cloud-ui/configure.mdx index ac5e35a1..41b54804 100644 --- a/docs/platform/enterprise-cloud-ui/configure.mdx +++ b/docs/platform/enterprise-cloud-ui/configure.mdx @@ -283,10 +283,10 @@ Enterprise Manager is unreachable. :::note The Cloud UI reads the registry policy's `server_api_url` (the Registry Server's -API root), not its `api_url`. The `api_url` value is shaped for ToolHive clients -and typically points at a single registry (for example, +API root), not its `api_url`. The `api_url` value is for ToolHive clients and +can point at a single registry (for example, `https://registry.example.com/registry/toolhive`); the Cloud UI's API routes are -relative to the server root, so pointing it at the client-shaped URL results in +relative to the server root, so pointing it at a per-registry URL results in `404` errors. See [Registry URL for the Cloud UI](../enterprise-manager/policies/registry.mdx#registry-url-for-the-cloud-ui) for details. diff --git a/docs/platform/enterprise-manager/policies/registry.mdx b/docs/platform/enterprise-manager/policies/registry.mdx index cfa32cce..575bb349 100644 --- a/docs/platform/enterprise-manager/policies/registry.mdx +++ b/docs/platform/enterprise-manager/policies/registry.mdx @@ -71,7 +71,8 @@ enterpriseConfig: The registry directive carries two distinct URLs because its two consumers expect different shapes. The `api_url` value is for ToolHive clients (CLI and -Stacklok Desktop) and typically points at a single registry on your Registry +Stacklok Desktop): depending on your registry, that's either the registry's root +URL (as in the examples above) or a per-registry path on a Stacklok Registry Server (for example, `https://registry.acme.com/registry/toolhive`). The [Enterprise Cloud UI](../../enterprise-cloud-ui/configure.mdx) instead needs the Registry Server's API root, set with `server_api_url`: @@ -87,8 +88,8 @@ enterpriseConfig: enforcement: 'enforced' ``` -Don't point the Cloud UI at the client-shaped `api_url` — its API routes are -relative to the server root, so requests return `404` errors. When +Don't point the Cloud UI at a per-registry `api_url` value. The Cloud UI's API +routes are relative to the server root, so requests return `404` errors. When `server_api_url` isn't set, the Cloud UI falls back to its `API_BASE_URL` environment variable (see [Registry API URL resolution](../../enterprise-cloud-ui/configure.mdx#registry-api-url-resolution)). From af3473bcbc2c39b9c6b2a98971cae9101bf987fb Mon Sep 17 00:00:00 2001 From: Samuele Verzi Date: Thu, 30 Jul 2026 17:19:05 +0200 Subject: [PATCH 3/4] Apply review feedback: trim over-explanation Drop the Cloud UI note restating the resolution list, take the suggested rewording of the two-URL paragraph, keep only the fallback sentence, and remove the upgrade warning (operational norm, belongs in release notes). --- .../enterprise-cloud-ui/configure.mdx | 13 --------- .../enterprise-manager/policies/registry.mdx | 27 +++++++------------ 2 files changed, 9 insertions(+), 31 deletions(-) diff --git a/docs/platform/enterprise-cloud-ui/configure.mdx b/docs/platform/enterprise-cloud-ui/configure.mdx index 41b54804..9a3f5620 100644 --- a/docs/platform/enterprise-cloud-ui/configure.mdx +++ b/docs/platform/enterprise-cloud-ui/configure.mdx @@ -280,19 +280,6 @@ This means you can omit `API_BASE_URL` entirely and let the Enterprise Manager control the registry URL, or set `API_BASE_URL` as a fallback for when the Enterprise Manager is unreachable. -:::note - -The Cloud UI reads the registry policy's `server_api_url` (the Registry Server's -API root), not its `api_url`. The `api_url` value is for ToolHive clients and -can point at a single registry (for example, -`https://registry.example.com/registry/toolhive`); the Cloud UI's API routes are -relative to the server root, so pointing it at a per-registry URL results in -`404` errors. See -[Registry URL for the Cloud UI](../enterprise-manager/policies/registry.mdx#registry-url-for-the-cloud-ui) -for details. - -::: - ## Feature flags The [Enterprise Manager](../enterprise-manager/index.mdx) controls Cloud UI diff --git a/docs/platform/enterprise-manager/policies/registry.mdx b/docs/platform/enterprise-manager/policies/registry.mdx index 575bb349..e11206e0 100644 --- a/docs/platform/enterprise-manager/policies/registry.mdx +++ b/docs/platform/enterprise-manager/policies/registry.mdx @@ -69,13 +69,14 @@ enterpriseConfig: ### Registry URL for the Cloud UI -The registry directive carries two distinct URLs because its two consumers -expect different shapes. The `api_url` value is for ToolHive clients (CLI and -Stacklok Desktop): depending on your registry, that's either the registry's root -URL (as in the examples above) or a per-registry path on a Stacklok Registry -Server (for example, `https://registry.acme.com/registry/toolhive`). The -[Enterprise Cloud UI](../../enterprise-cloud-ui/configure.mdx) instead needs the -Registry Server's API root, set with `server_api_url`: +The registry directive sets two URLs because ToolHive clients and the Cloud UI +connect to the registry differently. The `api_url` value is for ToolHive clients +(CLI and Stacklok Desktop): depending on your registry, that's either the +registry's root URL (as in the examples above) or a per-registry path on a +Stacklok Registry Server (for example, +`https://registry.acme.com/registry/`). The +[Enterprise Cloud UI](../../enterprise-cloud-ui/configure.mdx) needs the +Registry Server's API root instead, set with `server_api_url`: ```yaml title="values.yaml" enterpriseConfig: @@ -88,20 +89,10 @@ enterpriseConfig: enforcement: 'enforced' ``` -Don't point the Cloud UI at a per-registry `api_url` value. The Cloud UI's API -routes are relative to the server root, so requests return `404` errors. When -`server_api_url` isn't set, the Cloud UI falls back to its `API_BASE_URL` +When `server_api_url` isn't set, the Cloud UI falls back to its `API_BASE_URL` environment variable (see [Registry API URL resolution](../../enterprise-cloud-ui/configure.mdx#registry-api-url-resolution)). -:::warning - -The Enterprise Manager rejects configuration fields it doesn't recognize and -refuses to start. When upgrading, deploy the platform version that introduces -`server_api_url` **before** adding the field to your configuration. - -::: - ## Next steps - [Non-registry servers policy](./non-registry-servers.mdx) to control whether From 17c2b2296e2a52823378283a06171aa92a11a802 Mon Sep 17 00:00:00 2001 From: Samuele Verzi Date: Thu, 30 Jul 2026 23:04:32 +0200 Subject: [PATCH 4/4] Use example.com in new section, matching #1078 --- docs/platform/enterprise-manager/policies/registry.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/platform/enterprise-manager/policies/registry.mdx b/docs/platform/enterprise-manager/policies/registry.mdx index e11206e0..82cde165 100644 --- a/docs/platform/enterprise-manager/policies/registry.mdx +++ b/docs/platform/enterprise-manager/policies/registry.mdx @@ -74,7 +74,7 @@ connect to the registry differently. The `api_url` value is for ToolHive clients (CLI and Stacklok Desktop): depending on your registry, that's either the registry's root URL (as in the examples above) or a per-registry path on a Stacklok Registry Server (for example, -`https://registry.acme.com/registry/`). The +`https://registry.example.com/registry/`). The [Enterprise Cloud UI](../../enterprise-cloud-ui/configure.mdx) needs the Registry Server's API root instead, set with `server_api_url`: @@ -83,9 +83,9 @@ enterpriseConfig: registry: value: # For ToolHive clients: the registry API URL (one registry) - api_url: 'https://registry.acme.com/registry/toolhive' + api_url: 'https://registry.example.com/registry/toolhive' # For the Cloud UI: the Registry Server's API root - server_api_url: 'https://registry.acme.com' + server_api_url: 'https://registry.example.com' enforcement: 'enforced' ```