From 2b1c547bdc9e3fd4c370769b34103e9aef309889 Mon Sep 17 00:00:00 2001 From: Daryl White Date: Thu, 25 Jun 2026 12:48:32 -0400 Subject: [PATCH 1/5] docs(doc-1574,doc-1575): align secrets and connect-cluster docs with current platform ui - secrets: nav routes updated to Access & Secrets > Global Secrets - secrets: project secrets tab renamed from "Project Secrets" to "Secrets" - secrets: "Management Access" replaces stale "Access"/"Permissions" tab labels - secrets: global-sync form labels match current radio/select UI text - secrets: fix garbled duplicate namespace step in global create flow - secrets: fix vcluster cli commands in retrieve page (get secret / list secrets) - connect-cluster: nav updated to Infrastructure > Control Plane Clusters - connect-cluster: button renamed from "Connect Cluster via CLI" to "Connect Cluster" - vale: fix all pre-existing warnings in touched files Closes DOC-1574 Closes DOC-1575 Co-Authored-By: Claude Sonnet 4.6 --- platform/_partials/cluster/connect-ui.mdx | 12 ++++++------ platform/administer/secrets/global/create.mdx | 17 +++++++++-------- platform/administer/secrets/global/delete.mdx | 6 +++--- platform/administer/secrets/project/create.mdx | 15 +++++++-------- platform/administer/secrets/project/delete.mdx | 7 +++---- .../administer/secrets/project/retrieve.mdx | 16 +++++++++++----- 6 files changed, 39 insertions(+), 34 deletions(-) diff --git a/platform/_partials/cluster/connect-ui.mdx b/platform/_partials/cluster/connect-ui.mdx index dac001aba8..94ada80c5b 100644 --- a/platform/_partials/cluster/connect-ui.mdx +++ b/platform/_partials/cluster/connect-ui.mdx @@ -7,26 +7,26 @@ import Expander from '@site/src/components/Expander' - Go to the Clusters view using the menu on the left. + Go to the Infrastructure > Control Plane Clusters using the menu on the left. - Click on the button on the right. + Click on the button on the right. In the drawer that appears from the right, give your cluster a name in the field. Optionally give a name for the underlying kubernetes resource in the , or leave it empty to have it autogenerated for you. - Then click on the button. + Then click the button. - In the section "Cluster Connection", please copy & execute the displayed vCluster CLI or Helm command + In the section "Cluster Connection", copy & execute the displayed vCluster CLI or Helm command - Please wait until vCluster Platform installs the agent in your connected cluster. + Wait until vCluster Platform installs the agent in your connected cluster. Once successful, you may create a space / virtual cluster in the newly connected cluster by using the displayed vCluster CLI command. - Click on the button to go to the Clusters view. + Click on the button to go to the Control Plane Clusters view. diff --git a/platform/administer/secrets/global/create.mdx b/platform/administer/secrets/global/create.mdx index c93d572475..9a6abc03ce 100644 --- a/platform/administer/secrets/global/create.mdx +++ b/platform/administer/secrets/global/create.mdx @@ -15,14 +15,18 @@ Global Secrets allow you to define and share secrets for tenant clusters and spa Global secrets are not synchronized to secrets created within tenant clusters, however project secrets are. To use a global secret to manage secret data in tenant clusters, you can first create a project secret that is synchronized by a global secret. ::: -## Create a Global Secret +## Create a global secret + +:::note Required permissions +The **Global Secrets** menu item is only visible when you have `create` permission on the SharedSecret resource and the `Secrets` feature flag is enabled on your platform instance. If the menu item is missing, ask your platform administrator to verify both. +::: To create a global secret follow these steps: - Navigate to the Global Secrets view using the menu on the - left + Navigate to Access & Secrets > Global Secrets using the + menu on the left Click on the button @@ -31,7 +35,7 @@ To create a global secret follow these steps: Enter a name for the secret by clicking on - Enter a decritpion for the secret by clicking on{" "} + Enter a description for the secret by clicking on{" "} @@ -41,10 +45,7 @@ To create a global secret follow these steps: Enter the secret data in the input - Enter the namespace for the secret in the input - - - Click on the Access + Click on the Management Access Use the to add new access rules for the shared diff --git a/platform/administer/secrets/global/delete.mdx b/platform/administer/secrets/global/delete.mdx index 2b291c2e1c..505f6923a4 100644 --- a/platform/administer/secrets/global/delete.mdx +++ b/platform/administer/secrets/global/delete.mdx @@ -9,14 +9,14 @@ import Button from "@site/src/components/Button"; import Label from "@site/src/components/Label"; import NavStep from "@site/src/components/NavStep"; -## Delete Global Secret +## Delete global secret To delete a global secret follow these steps: - Navigate to the Global Secrets view using the menu on the - left + Navigate to Access & Secrets > Global Secrets using the + menu on the left Click on the button near in the drop-down list right diff --git a/platform/administer/secrets/project/create.mdx b/platform/administer/secrets/project/create.mdx index faf82515db..3cc5f0e563 100644 --- a/platform/administer/secrets/project/create.mdx +++ b/platform/administer/secrets/project/create.mdx @@ -22,7 +22,7 @@ will handle synchronizing the project secret data to your secret. It is not possible to define data custom in a project secret and synchronize a shared secret. If you need to define additional secret data that is specific to your project, it is best to create a separate secret, and combine them in your pod specifications. ::: -## Create a Project Secret with Custom Data +## Create a project secret with custom data To create a project secret with its own data follow these steps: @@ -34,7 +34,7 @@ To create a project secret with its own data follow these steps: Select the project you'd like to configure using the drop down menu - Click on Project Secrets + Click on Secrets Click on the button @@ -48,7 +48,7 @@ To create a project secret with its own data follow these steps: In the input, add your secret key/value pairs - Click on the button to save your changes + Click on the button to save your changes @@ -56,7 +56,7 @@ Once the project secret has been created, head over to the [Secret Sync](../../. Global secrets can be used in projects by creating a project secret that is synchronized by a global secret. This provides a way to manage secret data across many projects. -## Creating Project Secrets synced from a Global Secret +## Create project secrets synced from a global secret When you have a global secret defined in the platform and wish to use it inside your project, you can create a project secret to be synced from the global secret. @@ -79,14 +79,13 @@ the request will be denied. `my-secret`. If you wish to change this name you may edit the YAML directly. - In the Data, select the - global secret that you wish to sync to the project secret in the section. + In the Data, enable the option, then select the global secret in the dropdown. - Click on Permissions. Add which users and teams have access and permissions to modify the project secret. + Click on Management Access. Add which users and teams have access and permissions to modify the project secret. - Click on the button to save your changes. + Click on the button to save your changes. diff --git a/platform/administer/secrets/project/delete.mdx b/platform/administer/secrets/project/delete.mdx index 159079a0f5..71e0739770 100644 --- a/platform/administer/secrets/project/delete.mdx +++ b/platform/administer/secrets/project/delete.mdx @@ -9,7 +9,7 @@ import Button from "@site/src/components/Button"; import Label from "@site/src/components/Label"; import NavStep from "@site/src/components/NavStep"; -## Delete Project Secret +## Delete project secret To delete a project secret follow these steps: @@ -21,11 +21,10 @@ To delete a project secret follow these steps: Select the project you'd like to configure using the drop down menu - Click on Project Secrets + Click on Secrets - Click on the button near in the drop-down list right - to the name of your secret + Click the option in the drop-down menu next to the name of your secret Click on the button in the modal window to confirm the diff --git a/platform/administer/secrets/project/retrieve.mdx b/platform/administer/secrets/project/retrieve.mdx index efa45397e9..8bdd12225f 100644 --- a/platform/administer/secrets/project/retrieve.mdx +++ b/platform/administer/secrets/project/retrieve.mdx @@ -4,17 +4,23 @@ sidebar_label: Retrieve sidebar_position: 3 --- -Project Secrets can be retrieved either via the vCluster CLI or using `kubectl`. +Project secrets can be retrieved either using the vCluster CLI or using `kubectl`. -## Retrieve via vCluster CLI +## Retrieve using vCluster CLI -To get a list of project secrets using the vCluster CLI, run the following command: +To retrieve a specific project secret, run: ```sh -vcluster platform secret get --project default +vcluster platform get secret SECRET_NAME [flags] ``` -## Retrieve via `kubectl` +To list all secrets in a project, run: + +```sh +vcluster platform list secrets --project default +``` + +## Retrieve using `kubectl` To get a list of project secrets using `kubectl`, run the following command: From c3a959385dea17e0582c4723e89c7c55c0b3e13a Mon Sep 17 00:00:00 2001 From: Daryl White Date: Thu, 25 Jun 2026 13:06:09 -0400 Subject: [PATCH 2/5] docs(doc-1574,doc-1575): simplify flow step wording to match connect-ui style Co-Authored-By: Claude Sonnet 4.6 --- platform/_partials/cluster/connect-ui.mdx | 16 +++++----- platform/administer/secrets/global/create.mdx | 28 +++++++---------- platform/administer/secrets/global/delete.mdx | 9 ++---- .../administer/secrets/project/create.mdx | 31 +++++++------------ .../administer/secrets/project/delete.mdx | 12 +++---- 5 files changed, 38 insertions(+), 58 deletions(-) diff --git a/platform/_partials/cluster/connect-ui.mdx b/platform/_partials/cluster/connect-ui.mdx index 94ada80c5b..891335d5fb 100644 --- a/platform/_partials/cluster/connect-ui.mdx +++ b/platform/_partials/cluster/connect-ui.mdx @@ -7,26 +7,26 @@ import Expander from '@site/src/components/Expander' - Go to the Infrastructure > Control Plane Clusters using the menu on the left. + Go to Infrastructure > Control Plane Clusters. - Click on the button on the right. + Click . - In the drawer that appears from the right, give your cluster a name in the field. - Optionally give a name for the underlying kubernetes resource in the , or leave it empty to have it autogenerated for you. - Then click the button. + Give your cluster a name in . + Optionally, give a name for the underlying kubernetes resource in the , or leave it empty to autogenerate one. + Then click . - In the section "Cluster Connection", copy & execute the displayed vCluster CLI or Helm command + Copy & execute the displayed vCluster CLI or Helm command. Wait until vCluster Platform installs the agent in your connected cluster. - Once successful, you may create a space / virtual cluster in the newly connected cluster by using the displayed vCluster CLI command. + Once successful, use the displayed CLI command to create a space / virtual cluster in the newly connected cluster. - Click on the button to go to the Control Plane Clusters view. + Click to go to the Control Plane Clusters view. diff --git a/platform/administer/secrets/global/create.mdx b/platform/administer/secrets/global/create.mdx index 9a6abc03ce..8b7a29f78c 100644 --- a/platform/administer/secrets/global/create.mdx +++ b/platform/administer/secrets/global/create.mdx @@ -25,43 +25,37 @@ To create a global secret follow these steps: - Navigate to Access & Secrets > Global Secrets using the - menu on the left + Go to Access & Secrets > Global Secrets. - Click on the button + Click . - Enter a name for the secret by clicking on + Enter a name in . - Enter a description for the secret by clicking on{" "} - + Enter a description in . - Click on the Data + Click Data. - Enter the secret data in the input + Add your secret key/value pairs in . - Click on the Management Access + Click Management Access. - Use the to add new access rules for the shared - secret + Click to add an access rule. - Under the column, select the user or team you'd - like to grant access to the shared secret + In , select the user or team to grant access. - Under the column, select the verb to enable for - the user or team + In , select the verb to enable. - Click on the button once your changes are - complete + Click . diff --git a/platform/administer/secrets/global/delete.mdx b/platform/administer/secrets/global/delete.mdx index 505f6923a4..bf2dafcbad 100644 --- a/platform/administer/secrets/global/delete.mdx +++ b/platform/administer/secrets/global/delete.mdx @@ -15,15 +15,12 @@ To delete a global secret follow these steps: - Navigate to Access & Secrets > Global Secrets using the - menu on the left + Go to Access & Secrets > Global Secrets. - Click on the button near in the drop-down list right - to the name of your secret + Click in the drop-down menu next to your secret. - Click on the button in the modal window to confirm the - deletion + Click in the confirmation dialog. diff --git a/platform/administer/secrets/project/create.mdx b/platform/administer/secrets/project/create.mdx index 3cc5f0e563..2c3179ac5c 100644 --- a/platform/administer/secrets/project/create.mdx +++ b/platform/administer/secrets/project/create.mdx @@ -28,27 +28,22 @@ To create a project secret with its own data follow these steps: - Navigate to the Projects view using the menu on the left + Go to Projects and select your project. - Select the project you'd like to configure using the drop down menu + Click Secrets. - Click on Secrets + Click . - Click on the button + Enter a display name such as "My Secret" and an optional description. The UI fills in `.metadata.name` automatically; edit the YAML directly to override it. - Add a display name, such as "My Secret" and optional description for the - project secret. The UI will automatically fill in the `.metadata.name` with - `my-secret`. If you wish to change this name you may edit the YAML directly + Add your secret key/value pairs in . - In the input, add your secret key/value pairs - - - Click on the button to save your changes + Click . @@ -68,24 +63,22 @@ the request will be denied. - Select the project you'd like to configure using the drop down menu. Click on . + Go to Projects, select your project, then click Secrets. - Click on the button. + Click . - Add a display name, such as "My Secret" and optional description for the - project secret. The UI will automatically fill in the `.metadata.name` with - `my-secret`. If you wish to change this name you may edit the YAML directly. + Enter a display name such as "My Secret" and an optional description. The UI fills in `.metadata.name` automatically; edit the YAML directly to override it. - In the Data, enable the option, then select the global secret in the dropdown. + In Data, enable , then select the global secret in . - Click on Management Access. Add which users and teams have access and permissions to modify the project secret. + In Management Access, add which users and teams can access and modify the project secret. - Click on the button to save your changes. + Click . diff --git a/platform/administer/secrets/project/delete.mdx b/platform/administer/secrets/project/delete.mdx index 71e0739770..c76688c715 100644 --- a/platform/administer/secrets/project/delete.mdx +++ b/platform/administer/secrets/project/delete.mdx @@ -15,19 +15,15 @@ To delete a project secret follow these steps: - Navigate to the Projects view using the menu on the left + Go to Projects and select your project. - Select the project you'd like to configure using the drop down menu + Click Secrets. - Click on Secrets + Click in the drop-down menu next to your secret. - Click the option in the drop-down menu next to the name of your secret - - - Click on the button in the modal window to confirm the - deletion + Click in the confirmation dialog. From 546e953b14c858dd205e80574ab2c802a50086d7 Mon Sep 17 00:00:00 2001 From: Daryl White Date: Thu, 25 Jun 2026 13:37:34 -0400 Subject: [PATCH 3/5] docs(doc-1574,doc-1575): polish prose, headings, and structure across secrets pages - fold admonitions into prose throughout - rename section headings to lead with the distinguishing action - add when-to-use context to retrieve page - link global create page to project create page - tighten intro copy on project create page Co-Authored-By: Claude Sonnet 4.6 --- platform/administer/secrets/global/create.mdx | 12 +----- platform/administer/secrets/global/delete.mdx | 2 - .../administer/secrets/project/create.mdx | 37 +++++-------------- .../administer/secrets/project/delete.mdx | 7 +--- .../administer/secrets/project/retrieve.mdx | 2 +- 5 files changed, 14 insertions(+), 46 deletions(-) diff --git a/platform/administer/secrets/global/create.mdx b/platform/administer/secrets/global/create.mdx index 8b7a29f78c..1c48c5543a 100644 --- a/platform/administer/secrets/global/create.mdx +++ b/platform/administer/secrets/global/create.mdx @@ -9,17 +9,9 @@ import Button from "@site/src/components/Button"; import Label from "@site/src/components/Label"; import NavStep from "@site/src/components/NavStep"; -Global Secrets allow you to define and share secrets for tenant clusters and spaces across all registered clusters. Native Kubernetes secrets that reference these global secrets can then be created and vCluster Platform will synchronize the secret's data with the global secret. +Global secrets let you define and share secrets across all registered clusters. vCluster Platform synchronizes the secret data into any native Kubernetes secret that references it. Synchronization applies only to secrets in spaces, not to secrets inside tenant clusters. To make global secret data available inside a tenant cluster, [create a project secret](../project/create.mdx) that references the global secret. -:::note Space secrets, but not Tenant Cluster secrets -Global secrets are not synchronized to secrets created within tenant clusters, however project secrets are. To use a global secret to manage secret data in tenant clusters, you can first create a project secret that is synchronized by a global secret. -::: - -## Create a global secret - -:::note Required permissions -The **Global Secrets** menu item is only visible when you have `create` permission on the SharedSecret resource and the `Secrets` feature flag is enabled on your platform instance. If the menu item is missing, ask your platform administrator to verify both. -::: +The **Global Secrets** menu item is only visible when you have `create` permission on the SharedSecret resource and the `Secrets` feature flag is enabled. If the menu item is missing, ask your platform administrator to verify both. To create a global secret follow these steps: diff --git a/platform/administer/secrets/global/delete.mdx b/platform/administer/secrets/global/delete.mdx index bf2dafcbad..cc95dc7513 100644 --- a/platform/administer/secrets/global/delete.mdx +++ b/platform/administer/secrets/global/delete.mdx @@ -9,8 +9,6 @@ import Button from "@site/src/components/Button"; import Label from "@site/src/components/Label"; import NavStep from "@site/src/components/NavStep"; -## Delete global secret - To delete a global secret follow these steps: diff --git a/platform/administer/secrets/project/create.mdx b/platform/administer/secrets/project/create.mdx index 2c3179ac5c..1958086f89 100644 --- a/platform/administer/secrets/project/create.mdx +++ b/platform/administer/secrets/project/create.mdx @@ -9,29 +9,22 @@ import Button from "@site/src/components/Button"; import Label from "@site/src/components/Label"; import NavStep from "@site/src/components/NavStep"; -Project secrets allow you to define and share secrets across the allowed clusters -where namespace and tenant cluster instances of the project are deployed. There are two ways to utilize project secrets: +Project secrets let you define and share secrets across the clusters where your project's namespaces and tenant clusters run. There are two ways to populate a project secret: -1. Create project secrets and populate it with its own secret data. -2. Create a project secret that syncs with a shared secret. +1. Enter secret data directly in the project secret. +2. Sync from a global secret, which lets you propagate the same secret data across many projects from one place. -In both cases, to utilize the secret data, you will create a regular Kubernetes secret with labels referring to the project secret. Once created, vCluster Platform -will handle synchronizing the project secret data to your secret. +In both cases you consume the secret by creating a regular Kubernetes secret with labels that reference the project secret. vCluster Platform then synchronizes the data into that secret automatically. :::note Data or Shared Secrets, but not both It is not possible to define data custom in a project secret and synchronize a shared secret. If you need to define additional secret data that is specific to your project, it is best to create a separate secret, and combine them in your pod specifications. ::: -## Create a project secret with custom data - -To create a project secret with its own data follow these steps: +## Enter secret data directly - Go to Projects and select your project. - - - Click Secrets. + Go to Projects, select your project, then click Secrets. Click . @@ -47,19 +40,11 @@ To create a project secret with its own data follow these steps: -Once the project secret has been created, head over to the [Secret Sync](../../../use-platform/secrets/secret-sync.mdx) page to learn how to use the project secret data from a Pod. +See [Secret Sync](../../../use-platform/secrets/secret-sync.mdx) to learn how to use project secret data from a Pod. -Global secrets can be used in projects by creating a project secret that is synchronized by a global secret. This provides a way to manage secret data across many projects. +## Sync from a global secret -## Create project secrets synced from a global secret - -When you have a global secret defined in the platform and wish to use it inside your project, you can create a project secret to be synced -from the global secret. - -:::note Global Secret Permissions -When creating a project secret that refers to a global secret you must have permissions to read the shared secret or -the request will be denied. -::: +You must have read permission on the global secret, otherwise the request will be denied. @@ -83,6 +68,4 @@ the request will be denied. -The global secret's data will be synchronized with the project secret momentarily. Using this configuration, updates to the shared secret will automatically propagate down to the project secret. - -Once the project secret has been created, head over to the [Secret Sync](../../../use-platform/secrets/secret-sync.mdx) page to learn how to use the project secret data from a Pod. \ No newline at end of file +See [Secret Sync](../../../use-platform/secrets/secret-sync.mdx) to learn how to use project secret data from a Pod. \ No newline at end of file diff --git a/platform/administer/secrets/project/delete.mdx b/platform/administer/secrets/project/delete.mdx index c76688c715..b9e1a94e3d 100644 --- a/platform/administer/secrets/project/delete.mdx +++ b/platform/administer/secrets/project/delete.mdx @@ -9,16 +9,11 @@ import Button from "@site/src/components/Button"; import Label from "@site/src/components/Label"; import NavStep from "@site/src/components/NavStep"; -## Delete project secret - To delete a project secret follow these steps: - Go to Projects and select your project. - - - Click Secrets. + Go to Projects, select your project, then click Secrets. Click in the drop-down menu next to your secret. diff --git a/platform/administer/secrets/project/retrieve.mdx b/platform/administer/secrets/project/retrieve.mdx index 8bdd12225f..2ecc90ae34 100644 --- a/platform/administer/secrets/project/retrieve.mdx +++ b/platform/administer/secrets/project/retrieve.mdx @@ -4,7 +4,7 @@ sidebar_label: Retrieve sidebar_position: 3 --- -Project secrets can be retrieved either using the vCluster CLI or using `kubectl`. +Use the vCluster CLI when working within the platform's project abstraction, as it lets you refer to secrets by name and project without knowing the underlying namespace. Use `kubectl` when you need the raw Kubernetes secret object, work in a CI/CD pipeline that already has a kube context, or are in an environment where the vCluster CLI is not available. ## Retrieve using vCluster CLI From 63718cac8613b352969d1631778bc1bc37835b2c Mon Sep 17 00:00:00 2001 From: Daryl White Date: Fri, 26 Jun 2026 12:52:46 -0400 Subject: [PATCH 4/5] docs(doc-1574): fix platform ui drift across 55 files corrects button labels, field labels, nav steps, and ui instruction phrases to match current loft-enterprise ui source. adds report-platform-ui-drift.js script and platform-ui-drift skill to detect future drift. reduces unmatched tokens from 32 to 4 (the 4 remaining require live ui access to verify) and clears all 130 instruction phrase findings. Closes DOC-1574 Co-Authored-By: Claude Sonnet 4.6 --- .claude/skills/platform-ui-drift/SKILL.md | 202 ++++++++ package.json | 1 + platform/_partials/access-key/create-ui.mdx | 4 +- platform/_partials/cluster/connect-ui.mdx | 2 +- platform/_partials/cluster/create-ui.mdx | 7 +- .../namespace-template/create-ui.mdx | 11 +- platform/_partials/namespace/add-app-ui.mdx | 14 +- platform/_partials/namespace/share-ui.mdx | 8 +- .../_partials/space-constraints/create-ui.mdx | 10 +- platform/_partials/vcluster/add-app-ui.mdx | 24 +- platform/_partials/vcluster/share-ui.mdx | 9 +- .../administer/authentication/access-keys.mdx | 26 +- .../clusters/_partials/quotas/enforce-ui.mdx | 13 +- .../clusters/advanced/agent-config.mdx | 47 +- .../clusters/advanced/ingress-suffix.mdx | 13 +- .../administer/clusters/cluster-roles.mdx | 12 +- .../administer/projects/allowed/clusters.mdx | 4 +- .../administer/projects/allowed/templates.mdx | 12 +- platform/administer/projects/create.mdx | 10 +- platform/administer/projects/quotas.mdx | 37 +- platform/administer/secrets/global/create.mdx | 2 +- .../administer/templates/create-templates.mdx | 28 +- platform/administer/templates/versioning.mdx | 30 +- .../managing-teams/create.mdx | 13 +- .../_partials/user/impersonate-ui.mdx | 2 +- .../managing-users/create.mdx | 10 +- .../managing-users/impersonate.mdx | 48 +- .../managing-users/suspend.mdx | 9 +- .../users-permissions/permissions/cluster.mdx | 16 +- .../permissions/namespace.mdx | 2 +- .../users-permissions/permissions/project.mdx | 28 +- .../agent-settings/agent-upgrade.mdx | 11 +- .../agent-settings/customization.mdx | 14 +- .../platform-configs/single-sign-on.mdx | 15 +- platform/how-to/disable-local-admin.mdx | 10 +- .../integrations/argocd/connect-akuity.mdx | 19 +- .../integrations/argocd/connect-argocd.mdx | 15 +- .../argocd/deploy-applications.mdx | 27 +- platform/integrations/argocd/legacy.mdx | 66 ++- .../monitoring/aggregating-metrics.mdx | 20 +- .../monitoring/fleet-monitoring-otel.mdx | 23 +- platform/use-platform/apps/updating.mdx | 38 +- .../use-platform/apps/use-in-templates.mdx | 21 +- platform/use-platform/apps/use-on-demand.mdx | 21 +- platform/use-platform/apps/use-parameters.mdx | 9 +- .../_partials/auto-delete/configure-ui.mdx | 6 +- .../_partials/namespace/add-app-ui.mdx | 18 +- .../_partials/namespace/delete-ui.mdx | 2 +- .../_partials/namespace/share-ui.mdx | 12 +- .../_partials/sleep/configure-ui.mdx | 8 +- .../_partials/sleep/schedule-ui.mdx | 10 +- .../_partials/space-constraints/create-ui.mdx | 10 +- .../space-constraints/enforce-ui.mdx | 22 +- .../namespaces/key-features/custom-links.mdx | 4 +- .../key-features/prevent-deletion.mdx | 12 +- .../key-features/custom-links.mdx | 10 +- .../key-features/prevent-deletion.mdx | 8 +- scripts/report-platform-ui-drift.js | 431 ++++++++++++++++++ 58 files changed, 1015 insertions(+), 501 deletions(-) create mode 100644 .claude/skills/platform-ui-drift/SKILL.md create mode 100644 scripts/report-platform-ui-drift.js diff --git a/.claude/skills/platform-ui-drift/SKILL.md b/.claude/skills/platform-ui-drift/SKILL.md new file mode 100644 index 0000000000..b8029066f3 --- /dev/null +++ b/.claude/skills/platform-ui-drift/SKILL.md @@ -0,0 +1,202 @@ +--- +name: platform-ui-drift +description: Audit and fix drift between Platform docs UI tokens and the loft-enterprise UI source. Use when running the drift report, interpreting its output, verifying findings against loft-enterprise, or fixing stale nav paths, labels, and informal prose in platform docs. +context: fork +--- + +# Platform UI Drift + +The `report-platform-ui-drift` script compares UI tokens in platform docs (text wrapped in `` | +| `drawer` | Replace with "configuration sheet" | +| `configuration pane` | Replace with "tab" (e.g. "click the `` tab") | +| `textarea` | Replace with "field" | +| `checkbox` | Replace with "enable ``" | + +## Verify a finding against loft-enterprise + +Before fixing, confirm what the UI actually says. The UI source is at `../loft-enterprise/ui/src`. + +### Nav paths + +```bash +# Section labels and item names +cat ../loft-enterprise/ui/src/Layout/Sidebar/config/sections.tsx + +# Sub-nav tabs for a given view (e.g. clusters) +cat ../loft-enterprise/ui/src/views/Clusters/hooks/useClusterTabs.tsx +``` + +**Current sidebar structure (as of 2026-06):** + +| Section label | Key items | +|---|---| +| Infrastructure | Infra Providers, Control Plane Clusters, Connectors, Bare Metal Servers | +| Tenant Management | Cluster Templates, Namespace Templates, Argo CD Templates, Apps | +| Access & Secrets | Users & Roles, SSH Keys, Global Secrets | +| Platform | Logs & Activity, Cost Control, Platform Config | + +Control Plane Clusters sub-tabs: Host Clusters, Cluster Access, Cluster Roles, VPN. + +### Button and label text + +```bash +# Text in JSX children (most reliable) +grep -r "Button text or label" ../loft-enterprise/ui/src --include="*.tsx" | grep -v "spec\|test\|//" + +# Text in JSX props (label=, title=, placeholder=, submitLabel=) +grep -r 'label="Button text"' ../loft-enterprise/ui/src --include="*.tsx" | grep -v "spec\|test" +``` + +The script now extracts both — but grepping directly is faster for spot-checking. + +### Cluster/form sheet tabs + +```bash +# Cluster edit sheet tabs +grep -n "label" ../loft-enterprise/ui/src/views/Clusters/ClusterDrawer/ClusterDrawer.tsx +# Current tabs: Agent, Direct Access, Argo CD, Management Access + +# Project form section titles +grep -rn "title=" ../loft-enterprise/ui/src/views/Projects/ProjectForm/Sections --include="*.tsx" +# Current: Members and Roles, Control Plane Clusters, Template Options, Quotas, Advanced, Argo CD Integration +``` + +### Role sheet sections + +```bash +grep -n "title=" ../loft-enterprise/ui/src/views/Roles/RoleForm/RoleForm.tsx +# Sections: Rules (tabs: RBAC Rules, Aggregation Rule), Management Access +``` + +## Fix patterns + +### Navigation steps + +Replace the old `` path with the current one. Always use `Infrastructure > Control Plane Clusters` for the clusters section. + +```mdx + +Go to the Clusters view using the menu on the left. + + +Go to Infrastructure > Control Plane Clusters. +``` + +Remove trailing "using the menu on the left" — the `` component conveys location. + +### Cluster actions menu (Edit) + +The cluster list has a per-row actions menu (gear icon). Reference the action text directly: + +```mdx + +Click the drop down arrow next to the cluster name you wish to modify. In +the drop down menu click the button. + + +Click the option for the cluster you want to modify. +``` + +### Configuration sheet (formerly "drawer") + +```mdx + +In the drawer that appears from the right, click on the +configuration pane. + + +In the configuration sheet that opens, click the tab. +``` + +### Section names in forms + +| Old | Current | +|---|---| +| `Access` (cluster role form) | `Management Access` | +| `Allowed Templates` (project) | `Template Options` | +| `Allowed Clusters` (project) | `Control Plane Clusters` | +| `Configure Project Quotas` | `Quotas` | +| `Cluster Role` tab | `Cluster Roles` | + +### Argo CD + +The UI uses a space: "Argo CD" not "ArgoCD". The script normalizes this so it matches, but fix prose spelling when you touch the file. + +## After fixing: Vale + +Run Vale on every file you touch and fix all warnings — not just the drift-related lines. + +```bash +vale platform/path/to/file.mdx +``` + +Common warnings triggered by drift fixes: +- `click on` → `click` +- Headings ending in `-ing` (Finding, Setting, Troubleshooting) → use imperative (Find, Set, Troubleshoot) +- Title-case headings → sentence case +- `via` → `using` + +## Files with known drift clusters + +These files contain multiple unmatched tokens or instruction phrases and are good candidates for a batch fix pass: + +- `administer/clusters/advanced/ingress-suffix.mdx` — same nav/drawer/dropdown pattern as agent-config +- `configure/agent-settings/agent-upgrade.mdx` — same pattern +- `configure/agent-settings/customization.mdx` — same pattern +- `administer/clusters/cluster-roles.mdx` — fixed 2026-06-26 +- `administer/clusters/advanced/agent-config.mdx` — fixed 2026-06-26 +- `administer/projects/` — Allowed Templates / Allowed Clusters / Configure Project Quotas all stale +- `administer/templates/` — "left menu" throughout, dropdown references +- All files with `left sidebar` in `integrations/argocd/` — two occurrences + +## Release checklist use + +Run the report as part of platform release prep: + +1. `npm run report-platform-ui-drift > .user/ui-drift-$(date +%Y%m%d).txt` +2. Review unmatched tokens — focus on ` button to create a new access key - In the drawer that appears on the right, use the field to specify a Name for your access key + In the configuration sheet that opens, use the field to specify a Name for your access key OPTIONAL: Expand the Limit Access Key Scope section to specify which clusters, namespaces and virtual clusters this access key can be used for diff --git a/platform/_partials/cluster/connect-ui.mdx b/platform/_partials/cluster/connect-ui.mdx index 891335d5fb..97a96dc451 100644 --- a/platform/_partials/cluster/connect-ui.mdx +++ b/platform/_partials/cluster/connect-ui.mdx @@ -14,7 +14,7 @@ import Expander from '@site/src/components/Expander' Give your cluster a name in . - Optionally, give a name for the underlying kubernetes resource in the , or leave it empty to autogenerate one. + Optionally, give a name for the underlying kubernetes resource in the field, or leave it empty to autogenerate one. Then click . diff --git a/platform/_partials/cluster/create-ui.mdx b/platform/_partials/cluster/create-ui.mdx index d274ecdbf0..16bab59c80 100644 --- a/platform/_partials/cluster/create-ui.mdx +++ b/platform/_partials/cluster/create-ui.mdx @@ -9,7 +9,7 @@ import Flow, { Step } from "@site/src/components/Flow"; If you are still impersonating, click - Go to the Clusters view using the main menu on the left + Go to Infrastructure > Control Plane Clusters. Switch to the tab Cluster Access @@ -27,8 +27,7 @@ import Flow, { Step } from "@site/src/components/Flow"; individual user access to a cluster - Use the field and select the{" "} - User(s) you want to create this cluster access for + Select the users you want to give this cluster access to. In the section, either select{" "} @@ -36,6 +35,6 @@ import Flow, { Step } from "@site/src/components/Flow"; accessible for the users you selected in the previous step - Click the button at the bottom of the drawer + Click at the bottom of the configuration sheet. diff --git a/platform/_partials/namespace-template/create-ui.mdx b/platform/_partials/namespace-template/create-ui.mdx index 293c2c10e0..f97bc9682b 100644 --- a/platform/_partials/namespace-template/create-ui.mdx +++ b/platform/_partials/namespace-template/create-ui.mdx @@ -11,16 +11,13 @@ import CreateSpaceStep2 from '@site/static/media/ui/screenshots/spaces/create-sp - Go to the Spaces view using the menu on the left + Go to Tenant Management > Namespace Templates. - Switch to the tab + Click . - Click the button to create a new space template - - - In the drawer that appears on the right, use the field to specify a Name for your space template + In the configuration sheet that opens, use the field to specify a Name for your namespace template. Specify sleep mode settings as well as enforced labels and annotations for the spaces that will be created from this template @@ -29,6 +26,6 @@ import CreateSpaceStep2 from '@site/static/media/ui/screenshots/spaces/create-sp Expand the Deploy Apps section to specify which apps should be deployed as part of this template - On the very bottom, click on the button to create this space template + Click to create this namespace template. \ No newline at end of file diff --git a/platform/_partials/namespace/add-app-ui.mdx b/platform/_partials/namespace/add-app-ui.mdx index cf8e86010b..a1ea1a0da4 100644 --- a/platform/_partials/namespace/add-app-ui.mdx +++ b/platform/_partials/namespace/add-app-ui.mdx @@ -4,26 +4,20 @@ import Button from '@site/src/components/Button' import Label from '@site/src/components/Label' - Select the Projects field on the left menu bar. + Select the project containing the namespace from the project selector at the top left. - Select the project containing the namespace that you'd like to install - the App in from the Project drop down menu. + Click Namespaces. - From the Projects sub-menu, select the Namespaces option. - - - Find the namespace you would like to deploy an App to in the list of namespaces, and click on that + Find the namespace you would like to deploy an App to in the list of namespaces, and click that namespace. In the Namespace Management view, click the button. - Select the App you would like to install from the App thumbnails, or, if there - are no recommend Apps, click the and find the - desired App in the drop down menu. + Select the App you would like to install from the App thumbnails, or click and select the desired App. Enter any other required parameters for your App -- this may vary depending on diff --git a/platform/_partials/namespace/share-ui.mdx b/platform/_partials/namespace/share-ui.mdx index a0ac3ea87f..c16d004c32 100644 --- a/platform/_partials/namespace/share-ui.mdx +++ b/platform/_partials/namespace/share-ui.mdx @@ -7,13 +7,13 @@ import Expander from '@site/src/components/Expander' - Go to the Projects view using the menu on the left + Select the project from the project selector at the top left, then click Namespaces. - Click on Namespaces and click on the Edit link on a namespace. + Click on the namespace you want to share. - In the drawer select the 'Permissions' section. + In the configuration sheet that opens, click the tab. Select the user or team you want to grant permissions in the 'User or Team' select. If you don't see the user or team you want to grant access in there, make sure they have project access. @@ -22,6 +22,6 @@ import Expander from '@site/src/components/Expander' Specify the cluster-role you want to assign the user or team within the namespace. - Click on the button at the very bottom + Click the button. \ No newline at end of file diff --git a/platform/_partials/space-constraints/create-ui.mdx b/platform/_partials/space-constraints/create-ui.mdx index cc25369460..32fd25ba4f 100644 --- a/platform/_partials/space-constraints/create-ui.mdx +++ b/platform/_partials/space-constraints/create-ui.mdx @@ -11,16 +11,16 @@ import CreateNamespaceStep2 from '@site/static/media/ui/screenshots/spaces/creat - Go to the Clusters view using the menu on the left + Go to Infrastructure > Control Plane Clusters. - Switch to the tab + Switch to the tab. - Click the button to create a new namespace constraints object + Click . - In the drawer that appears on the right, use the field to specify a Name for your namespace constraints object + In the configuration sheet that opens, use the field to specify a Name for your namespace constraints object. Expand the Enforce Resources section to specify manifests that should be deployed to and enforced in each namespace that is affected by these namespace constraints @@ -29,6 +29,6 @@ import CreateNamespaceStep2 from '@site/static/media/ui/screenshots/spaces/creat Expand the Enforce Namespace Settings section to specify other namespace settings such as sleep mode, auto-delete, labels and annotations that should be enforced for each namespace that is affected by these namespace constraints - On the very bottom, click on the button to create this namespace constraints object + Click to create this namespace constraints object. \ No newline at end of file diff --git a/platform/_partials/vcluster/add-app-ui.mdx b/platform/_partials/vcluster/add-app-ui.mdx index bf77226533..76f11a7de1 100644 --- a/platform/_partials/vcluster/add-app-ui.mdx +++ b/platform/_partials/vcluster/add-app-ui.mdx @@ -6,18 +6,16 @@ import Flow from "@site/src/components/Flow"; - From the project drop-down menu (top left corner), select the project that has the - virtual cluster that you want to deploy the App in. + Select the project from the project selector at the top left. - Click on Virtual Clusters. + Click Tenant Clusters. - Find the virtual cluster you would like to deploy an App to in the list of - virtual clusters and hover over that virtual cluster. + Find the tenant cluster you would like to deploy an App to and hover over it. - Click on . + Click . Click the configuration tab.

@@ -27,12 +25,9 @@ import Flow from "@site/src/components/Flow"; be deployed *in* the virtual cluster. - From the drop down menu , select an - application that you would like to be deployed. You can - select as many as you would like by simply selecting another - application from the drop down menu. If you accidentally add one, or add one you - do not want, click the trash icon next to the names of the applications to remove it - from the configuration. + Select an application from the selector. You can + add as many as you like by selecting another application. To remove one, + click the trash icon next to the application name. For each application that you added to the template, you can configure the default @@ -40,8 +35,7 @@ import Flow from "@site/src/components/Flow"; can also configure the Helm release-name. - Finish configuring anything else you'd like on your virtual cluster, - then click the - button. + Finish configuring anything else you'd like on your tenant cluster, + then click . diff --git a/platform/_partials/vcluster/share-ui.mdx b/platform/_partials/vcluster/share-ui.mdx index 49dd98f47e..19c0f590c9 100644 --- a/platform/_partials/vcluster/share-ui.mdx +++ b/platform/_partials/vcluster/share-ui.mdx @@ -13,10 +13,10 @@ import PartialVirtualClusterCreateOptionalUI from "./create-ui-optional-fields.m - From the project drop-down menu (top left corner), select the project to find your virtual cluster. + Select the project from the project selector at the top left. - Click Virtual Clusters. + Click Tenant Clusters. Click on the virtual cluster that you want to edit. @@ -25,14 +25,13 @@ import PartialVirtualClusterCreateOptionalUI from "./create-ui-optional-fields.m Click Permissions. - Click to input and select the user or team to add. If the user or team you want to grant access to is not listed, verify that they have access to the project. + Click to select the user or team to add. If the user or team you want to grant access to is not listed, verify that they have access to the project. Specify the you want to assign the user or team. - After specifying all virtual options, click {" "} - . + After specifying all options, click . diff --git a/platform/administer/authentication/access-keys.mdx b/platform/administer/authentication/access-keys.mdx index f5895cc979..1c31fe8a83 100644 --- a/platform/administer/authentication/access-keys.mdx +++ b/platform/administer/authentication/access-keys.mdx @@ -63,10 +63,7 @@ Apply the principle of least privilege by using the most restrictive scope possi - Select the Users field on the left menu bar. - - - Click the Users button on the User Management screen. + Go to Access & Secrets > Users & Roles. Find the user you would like to generate an Access Key for from the list of @@ -78,33 +75,28 @@ Apply the principle of least privilege by using the most restrictive scope possi button. - In the drawer that appears from the right, give the Access Key a display - name in the - box. + In the configuration sheet that opens, give the Access Key a display name + in the field. - Optional If you'd like to limit the scope of the Access Key, expand - the - configuration section. In this section - you can select the clusters, namespaces, and tenant clusters of which to - limit the Access Key scope to. + Optional: Expand the section to select the clusters, + namespaces, and tenant clusters you want to limit the access key scope to. - Click the button. + Click . - In the pop up window, make sure to copy the generated Access Key from the - prompt as you are not able to fetch this key again. + In the pop-up window, copy the generated access key. You cannot retrieve it again after closing this dialog. - Click the button. + Click . ## Use access keys ### Log in using CLI -You can use an access key to login to vCluster Platform via the vCluster CLI: +You can use an access key to login to vCluster Platform using the vCluster CLI: ``` vcluster platform login my-vcluster-platform-url.com --access-key ACCESS_KEY diff --git a/platform/administer/clusters/_partials/quotas/enforce-ui.mdx b/platform/administer/clusters/_partials/quotas/enforce-ui.mdx index 50c2a45e48..bb19700a6c 100644 --- a/platform/administer/clusters/_partials/quotas/enforce-ui.mdx +++ b/platform/administer/clusters/_partials/quotas/enforce-ui.mdx @@ -10,7 +10,7 @@ import CreateSpaceStep2 from "@site/static/media/ui/screenshots/spaces/create-sp - Go to the Clusters view using the menu on the left + Go to Infrastructure > Control Plane Clusters. Switch to the tab @@ -35,17 +35,14 @@ import CreateSpaceStep2 from "@site/static/media/ui/screenshots/spaces/create-sp button to the cluster access - In the drawer that appears on the right, expand the{" "} - Restrictions section + In the configuration sheet that opens, expand the{" "} + Restrictions section. - Use the field to specify quotas, e.g. you can - limit the number of spaces by adding the line spaces: 3 to - this quota specification + Use the field to specify quotas. For example, limit the number of namespaces by adding the line `spaces: 3`. - On the very bottom, click on the button to save the - changes + Click to save the changes. diff --git a/platform/administer/clusters/advanced/agent-config.mdx b/platform/administer/clusters/advanced/agent-config.mdx index 8a44ca7988..3a5d67fcdf 100644 --- a/platform/administer/clusters/advanced/agent-config.mdx +++ b/platform/administer/clusters/advanced/agent-config.mdx @@ -15,7 +15,7 @@ import InterpolatedCodeBlock from "@site/src/components/InterpolatedCodeBlock"; As outlined in the 'What are Clusters' section, during the initial setup, vCluster Platform tries to install a vCluster Platform Agent on the connected cluster to handle further communication with the cluster. vCluster Platform allows certain level of control over the installation and upgradation of the vCluster Platform Agent release. -## Finding Agent Pods +## Find agent pods The platform agent runs as a pod in each connected cluster. Locate agent pods to verify connectivity and troubleshoot issues: @@ -31,31 +31,29 @@ NAME READY STATUS RESTARTS AGE loft-d6c6d5576-7kqwx 1/1 Running 0 9d ``` -## Agent Values +## Agent values The vCluster Platform Agent is installed on the connected cluster as a Helm Release. Provide additional values for the release by setting the `loft.sh/agent-values` annotation on the Cluster object. These values are merged with the default configuration values of the Agent's chart and subsequently applied to the Agent release. -### Setting Agent Values via UI +### Set agent values using the UI - Go to the Clusters view using the menu on the left. + Go to Infrastructure > Control Plane Clusters. - Click the drop down arrow next to the cluster name you wish to modify. In - the drop down menu click the button. + Click the option for the cluster you want to modify. - In the drawer that appears from the right, click on the {" "} - configuration pane. Provide the values in the textarea under{" "} - in the YAML format. + In the configuration sheet that opens, click the tab + and enter your values in using YAML format. - Click on the button. + Click . -### Setting Agent Values via CLI +### Set agent values using the CLI Export the current Cluster resource (this is a platform CRD, not vcluster.yaml): @@ -97,13 +95,13 @@ Apply the updated configuration: title="Apply updated configuration" /> -### Security Context Configuration +### Security context configuration Security context is one of the common agent configurations. Agent pods support multiple levels of security context configuration. :::info Security Context Precedence When multiple security contexts are configured, the agent uses this precedence order (highest to lowest): -1. Cluster-specific `agentValues` (via `loft.sh/agent-values` annotation) +1. Cluster-specific `agentValues` (using `loft.sh/agent-values` annotation) 2. Platform-wide `agentValues` (in platform values.yaml) 3. Platform default `securityContext` and `podSecurityContext` @@ -136,7 +134,7 @@ securityContext: Both Agent Pod and Agent Proxy Pod (deployed during upgrades) follow the same precedence order. ::: -#### Example: Platform-wide Security Context +#### Example: Platform-wide security context Configure security contexts in your `vcluster-platform` values file during platform installation: @@ -168,12 +166,12 @@ agentValues: runAsGroup: 3001 ``` -#### Example: Cluster-specific Security Context +#### Example: Cluster-specific security context Override security contexts for specific clusters using the `loft.sh/agent-values` annotation: ```yaml title="cluster-specific-agent-values.yaml" -# Applied via loft.sh/agent-values annotation on the Cluster resource +# Applied using loft.sh/agent-values annotation on the Cluster resource securityContext: allowPrivilegeEscalation: false runAsNonRoot: true @@ -192,26 +190,25 @@ podSecurityContext: - 5000 ``` -To apply cluster-specific security context through the UI, follow the steps in [Setting Agent Values via UI](#setting-agent-values-via-ui) and add your security context configuration in the Extra Agent Values textarea. +To apply cluster-specific security context using the UI, follow the steps in [Set agent values using the UI](#set-agent-values-using-the-ui) and add your security context configuration in the Extra Agent Values field. -## Disable vCluster Platform Agent +## Disable the vCluster Platform agent There might be cases where you don't want vCluster Platform to automatically handle vCluster Platform agent updates. This can be achieved either by setting the environment variable `DISABLE_AGENT` to `true` in the vCluster Platform container or by setting the annotation `loft.sh/cluster-ignore-agent: 'true'` on a connected cluster. - Go to the Clusters view using the menu on the left. + Go to Infrastructure > Control Plane Clusters. - Click the drop down arrow next to the cluster name you wish to modify. In - the drop down menu click the button. + Click the option for the cluster you want to modify. - In the drawer that appears from the right, click on the {" "} - configuration pane and select the 'Ignore Agent' checkbox. + In the configuration sheet that opens, click the tab + and enable . - Click on the button. + Click . @@ -219,6 +216,6 @@ There might be cases where you don't want vCluster Platform to automatically han If you do not install vCluster Platform agent into a connected cluster at all, certain features, such as Spaces, Auto Sleep, Apps, Accounts, Account Quotas & Security Templates will not be available in the cluster ::: -## Troubleshooting +## Troubleshoot For issues configuring agent values or manual deployment, see the [Cluster troubleshooting](cluster-troubleshooting.mdx) guide. diff --git a/platform/administer/clusters/advanced/ingress-suffix.mdx b/platform/administer/clusters/advanced/ingress-suffix.mdx index e03d824771..b0c4f481dd 100644 --- a/platform/administer/clusters/advanced/ingress-suffix.mdx +++ b/platform/administer/clusters/advanced/ingress-suffix.mdx @@ -25,19 +25,18 @@ You can set the required ingress suffix in the vCluster Platform UI: - Go to the Clusters view using the menu on the left. + Go to Infrastructure > Control Plane Clusters. - Click the drop down arrow next to the cluster name you wish to modify. In - the drop down menu click the button. + Click the option for the cluster you want to modify. - In the drawer that appears from the right, click the{" "} - configuration pane. Provide the desired domain - under the field. + In the configuration sheet that opens, click the{" "} + tab. Provide the desired domain under the{" "} + field. - Click on the button. + Click the button. diff --git a/platform/administer/clusters/cluster-roles.mdx b/platform/administer/clusters/cluster-roles.mdx index 684070708d..1941567d77 100644 --- a/platform/administer/clusters/cluster-roles.mdx +++ b/platform/administer/clusters/cluster-roles.mdx @@ -26,21 +26,21 @@ The vCluster Platform comes with some predefined cluster roles out-of-the-box. Y - Go to the Clusters view using the menu on the left. + Go to Infrastructure > Control Plane Clusters. - Click the Cluster Role option on the Clusters pane and then Click on the button at the very right. + Click the Cluster Roles tab, then click . - In the drawer that appears from the right, give the role a name by replacing the 'my-role' placeholder name, or by updating the manifest YAML 'metadata.name' field. + In the configuration sheet that opens, give the role a name by replacing the 'my-role' placeholder, or by editing the manifest YAML 'metadata.name' field. - In the configuration pane, specify the RBAC rules for the current role in the 'RBAC Rules' Tab. Alternatively, you can also specify an aggregation rule for a cluster role of that type in the 'aggregation' tab. Finally, select the cluster in which you want the cluster role to be synced. + In the section, specify RBAC rules in the tab, or specify an aggregation rule in the tab. Select the cluster to sync the role to. - In the configuration pane, Select the User or Team that should have access to the underlying cluster role object, from the drop down menu. Choose what actions they are allowed to perform on the object, from the drop down menu. + In the section, select the users or teams that should have access to this role object and set their allowed permissions. - Click on the button to create the role. + Click to create the role. diff --git a/platform/administer/projects/allowed/clusters.mdx b/platform/administer/projects/allowed/clusters.mdx index fb9c2be9f6..cb9932bcea 100644 --- a/platform/administer/projects/allowed/clusters.mdx +++ b/platform/administer/projects/allowed/clusters.mdx @@ -15,10 +15,10 @@ Allowed clusters control the clusters which project members are granted access. - Select the project you'd like to configure using the drop down menu. Click on . + Select the project you'd like to configure using the project selector dropdown. Click on . - Click on Allowed Clusters. + Click on Control Plane Clusters. Click on the input and select the cluster names to allow. If you wish to change this manually, you may edit the YAML directly. diff --git a/platform/administer/projects/allowed/templates.mdx b/platform/administer/projects/allowed/templates.mdx index 4f929dc798..4011024030 100644 --- a/platform/administer/projects/allowed/templates.mdx +++ b/platform/administer/projects/allowed/templates.mdx @@ -42,10 +42,10 @@ Only project admins or global admins can add more templates to a project. - Select the project you'd like to configure using the drop down menu. Click on . + Select the project you'd like to configure using the project selector dropdown. Click on . - Click on Allowed Templates. + Click on Template Options. Select which resource you want to add more templates to. @@ -71,10 +71,10 @@ template is automatically selected when creating the resource. The default templ - Select the project you'd like to configure using the drop down menu. Click on . + Select the project you'd like to configure using the project selector dropdown. Click on . - Click on Allowed Templates. + Click on Template Options. Select which resource you want to set a default template. @@ -99,10 +99,10 @@ name `my-project-space-1` being created for the space instance named `space-1` f - Select the project you'd like to configure using the drop down menu. Click on . + Select the project you'd like to configure using the project selector dropdown. Click on . - Click on Allowed Templates. + Click on Template Options. Expand the section. diff --git a/platform/administer/projects/create.mdx b/platform/administer/projects/create.mdx index 14f5abc69f..0e78517dcc 100644 --- a/platform/administer/projects/create.mdx +++ b/platform/administer/projects/create.mdx @@ -18,7 +18,7 @@ Keep templates required for projects where non-admin users create tenant cluster - All available projects are in the top left dropdown. Click the toggle to find the option. + All available projects are in the top left dropdown. Click the toggle to find the option. Click on Members and add your users or teams and @@ -26,18 +26,18 @@ Keep templates required for projects where non-admin users create tenant cluster section for more information. - Click on Allowed Templates to set the templates + Click on Template Options to set the templates allowed for the project. By default, templates are required and can be changed in this step. See{" "} Manage Allowed Templates for more information. - Click on Allowed Clusters to set the clusters that + Click on Control Plane Clusters to set the clusters that members should have access to. See the Manage Allowed Clusters{" "} section for further information. - Click on the Configure Project Quotas to set the quotas - for the project or specific user/team. See the Quotas{" "} + Click on Quotas to set the quotas for the project or + specific user/team. See the Quotas{" "} section for further information. diff --git a/platform/administer/projects/quotas.mdx b/platform/administer/projects/quotas.mdx index 98ff5818c2..e063bb8945 100644 --- a/platform/administer/projects/quotas.mdx +++ b/platform/administer/projects/quotas.mdx @@ -22,24 +22,24 @@ defined across the whole project or on a per-user/per-team basis. When you create multiple tenant cluster instances, the individually used resources count toward the shared project quota. ::: -## Quotas on Active Resources +## Active resource quotas -You can restrict the number of active instances for our custom instance types. These quotas are suffixed with `.active`. These are enforced during instance creation, but also when a request is received to wake up a sleeping instance. +You can restrict the number of active instances for custom instance types. These quotas are suffixed with `.active`. They are enforced during instance creation, and also when a request is received to wake up a sleeping instance. -## Quotas on Template Quotas +## Template quotas -You can restrict the number of instances that are using a given template at the same time. By selecting the instance (e.g. `virtualclusterinstances`), a template dropdown will automatically appear to select what template to restrict. These are enforced during instance creation. +You can restrict the number of instances using a given template at the same time. By selecting the instance (for example, `virtualclusterinstances`), a template dropdown appears to select what template to restrict. These are enforced during instance creation. -## Quotas on Generic Resources +## Generic resource quotas -Quotas can also specify limits on generic resources such as `count/pods` and `limits.cpu` in a similar way to a normal Kubernetes `ResourceQuota` object, but the limits apply to the scope of the project. +Quotas can also specify limits on generic resources such as `count/pods` and `limits.cpu`, similar to a standard Kubernetes ResourceQuota, but the limits apply to the scope of the project. -:::info On Cluster Resource limits +:::info On cluster resource limits Custom resources such as `virtualclusterinstances` can be instantly enforced as soon as consumption exceeds the limit, but on-cluster resources such as `limits.cpu` cannot be immediately enforced to avoid blocking requests for a long time. Users may be able to exceed the quota by small amounts by simultaneously creating resources on multiple clusters. ::: -## Quotas on Machines +## Machine quotas You can limit the number of Machines (`NodeClaim` resources) a project can provision. Use the `nodeclaims` resource for a project-wide limit, and the per-user/team bucket to cap how many Machines a single user or team can own. @@ -47,20 +47,20 @@ To restrict Machines from a specific node provider, suffix the resource with the Machine quotas are enforced when a Machine is created. As with the instance quotas above, a Machine owned by a user or team counts against both the project quota and that owner's per-user/team quota. -## Adding Quotas for the Project +## Add quotas for the project - Select the project you'd like to configure using the drop down menu. Click on . + Select the project you'd like to configure using the project selector dropdown. Click . - Click on Quotas. + Click Quotas. Select the tab. - Click on the . An entry in the quota table will + Click . An entry in the quota table will appear. @@ -76,7 +76,7 @@ Machine quotas are enforced when a Machine is created. As with the instance quot -## Adding Quotas for a User/Team +## Add quotas for a user or team When using a quota for a user or team, it applies to **all** users or teams in the project and cannot be applied to specific users and teams. For example, this project defines a total tenant cluster instance quota of 20, but @@ -85,16 +85,16 @@ team uses more than their fair share of cluster resources. - Select the project you'd like to configure using the drop down menu. Click on . + Select the project you'd like to configure using the project selector dropdown. Click . - Click on Quotas. + Click Quotas. Select the tab. - Click on the . An entry in the quota table will + Click . An entry in the quota table will appear. @@ -115,10 +115,9 @@ If a team is the owner of a space or tenant cluster, the usage will be counted b each member of the team, nor will the usage of a team member count towards the team's quota. ::: -## Exceeding Quotas +## Quota exceeded behavior -Once quotas are defined, users and teams are free to create resources up to the defined limits. However, once the usage meets the limit, attempts to create new resources will be rejected with an error message indicating the resource type and limit -that would be exceeded. Here are examples of possible error messages: +Once quotas are defined, users, and teams can create resources up to the defined limits. When usage meets the limit, attempts to create new resources are rejected with an error message indicating the resource type and limit that would be exceeded. Examples of possible error messages: ``` Error: metadata.name: Forbidden: cannot create spaceinstance, because project spaceinstances limit of 5 would be exceeded diff --git a/platform/administer/secrets/global/create.mdx b/platform/administer/secrets/global/create.mdx index 1c48c5543a..e7356b5038 100644 --- a/platform/administer/secrets/global/create.mdx +++ b/platform/administer/secrets/global/create.mdx @@ -38,7 +38,7 @@ To create a global secret follow these steps: Click Management Access. - Click to add an access rule. + Click to add an access rule. In , select the user or team to grant access. diff --git a/platform/administer/templates/create-templates.mdx b/platform/administer/templates/create-templates.mdx index 9639571886..476d38c453 100644 --- a/platform/administer/templates/create-templates.mdx +++ b/platform/administer/templates/create-templates.mdx @@ -28,12 +28,9 @@ You can create templates directly in the UI: - In the vCluster Platform, select Templates from the left menu. - - From the **Templates** menu, select the Tenant Clusters option. - - Click **Add Tenant Cluster Template**. + Go to Tenant Management > Cluster Templates. + Click . Provide your tenant cluster template with a name by replacing the `my-template` placeholder name, or by updating the manifest YAML `metadata.name` field. @@ -57,9 +54,8 @@ App templates can be created through the UI. - Select Templates in the left menu. + Go to Tenant Management > Apps. - Click the **Apps** option. Click . @@ -68,13 +64,13 @@ App templates can be created through the UI. updating the manifest YAML `metadata.name` field. - On the pane, select the type of app (`kubectl`, Helm, or bash), and provide the necessary details. These vary depending on your application type and environment. + On the tab, select the type of app (`kubectl`, Helm, or bash), and provide the necessary details. These vary depending on your application type and environment. [Optional] Use the tab to upload an app icon, which appears in the UI. - [Optional] Use the drop-down list to choose whether the app appears as recommended in the UI. + [Optional] Use the list to choose whether the app appears as recommended in the UI. Click . @@ -88,13 +84,10 @@ Namespace templates can be created directly in the UI to define default labels, - Select Templates in the left menu. - - - From the Templates menu, select the **Namespaces**. + Go to Tenant Management > Namespace Templates. - Click **Add Namespace Template** . + Click **Add Namespace Template**. Provide your tenant cluster template with a name by replacing the `my-template` placeholder name, or by @@ -116,7 +109,7 @@ Namespace templates can be created directly in the UI to define default labels, Alternatively, you can create a manifest and apply it to your cluster using `kubectl`, Helm, or ArgoCD. -For example, to create a `VirtualClusterTemplate` manifest: +For example, to create a VirtualClusterTemplate manifest: @@ -267,10 +260,7 @@ To make changes, you must manually update the corresponding custom resource, by - Navigate to **Templates** in the left menu. - - - Select the template type from the **Templates** menu. + Go to Tenant Management and select the template type (Cluster Templates, Namespace Templates, or Apps). Find the template you want to delete. diff --git a/platform/administer/templates/versioning.mdx b/platform/administer/templates/versioning.mdx index 78194bf318..6305bcba12 100644 --- a/platform/administer/templates/versioning.mdx +++ b/platform/administer/templates/versioning.mdx @@ -39,7 +39,7 @@ Avoid using `X.X.X` unless necessary. Use the `X` placeholder only in the minor You can add new versions to your templates using the UI. The steps are the same for all resources. :::note -Alternatively, you can use a GitOps workflow by applying an updated `VirtualClusterInstance` resource to the vCluster Platform cluster using tools such as `kubectl` or Argo CD. +Alternatively, you can use a GitOps workflow by applying an updated VirtualClusterInstance resource to the vCluster Platform cluster using tools such as `kubectl` or Argo CD. ::: :::info Semantic versioning @@ -50,14 +50,11 @@ whether to indicate if a template has a newer version available. - Select the Templates field on the left menu bar. + Go to Tenant Management and select the template type you want to version. - Click the option for the resource you want to version on the templates pane. Find the template you want to add a new version to in - the list of templates. Click the dropdown list next - to the name of your desired template. From the dropdown - menu, click . + the list. Click the actions menu next to its name and click . In the pop-up window, enter the new version string for your App. Then, @@ -81,29 +78,20 @@ You can change the template and/or template version in the UI. - Select the Projects field on the left menu. + Select the project containing the resource using the project selector dropdown. + Click the resource type on the project page. - From the project dropdown menu, select the project containing the resource you want to update. + Click the actions menu next to the resource you want to modify and select . - Click the option on the project pane. - Click the dropdown arrow next to the name of the resource you want - to modify. - - - In the dropdown menu, select . - - - In the pop-up window, select the name of the template from the drop-down - list. The applied template is already selected, so if you + In the pop-up window, select the name of the template from the list. The applied template is already selected, so if you are changing the template version, you don't need to do anything for this step. - If the template you are selecting has multiple versions, you might see an - additional version dropdown menu next to the template selector dropdown. - Select your desired template version from this menu. + If the template has multiple versions, a version selector appears next to the template selector. + Select your desired template version. Click . diff --git a/platform/administer/users-permissions/managing-teams/create.mdx b/platform/administer/users-permissions/managing-teams/create.mdx index 9db880cbe2..66c59e82e1 100644 --- a/platform/administer/users-permissions/managing-teams/create.mdx +++ b/platform/administer/users-permissions/managing-teams/create.mdx @@ -18,16 +18,13 @@ Teams provide the foundation for a scalable permission model in vCluster platfor - Select the Users field on the left menu bar. - - - Click the Teams button on the User Management screen. + Go to Access & Secrets > Users & Roles and select the Teams tab. Click the button. - In the drawer that appears from the right, give your new team a name by + In the configuration sheet that opens, give your new team a name by replacing the 'my-team' placeholder name, or by updating the manifest YAML 'metadata.name' field. @@ -38,16 +35,16 @@ Teams provide the foundation for a scalable permission model in vCluster platfor The tab contains settings that govern which users or groups are members of this team. The{" "} - selector allows you to include + selector allows you to include individual users directly into the team, while the - allows you to include users whose standard + field allows you to include users whose standard kubernetes groups (clusterroles) match the provided values set here. allow for configuring cluster roles that apply to this team, as well as Image Pull Secrets, that allow users in this team to automatically receive the provided image pull secrets upon - logging into vCluster Platform (via the vCluster CLI). + logging into vCluster Platform (using the vCluster CLI). allows you to define which users and teams have diff --git a/platform/administer/users-permissions/managing-users/_partials/user/impersonate-ui.mdx b/platform/administer/users-permissions/managing-users/_partials/user/impersonate-ui.mdx index 26b297a208..6b1a212025 100644 --- a/platform/administer/users-permissions/managing-users/_partials/user/impersonate-ui.mdx +++ b/platform/administer/users-permissions/managing-users/_partials/user/impersonate-ui.mdx @@ -37,7 +37,7 @@ import CreateSpaceStep2 from '@site/static/media/ui/screenshots/spaces/create-sp button to the user - In the popup, click on the button to confirm + In the popup, click the button to confirm that you want to start impersonation diff --git a/platform/administer/users-permissions/managing-users/create.mdx b/platform/administer/users-permissions/managing-users/create.mdx index fc8d88519c..315ae438aa 100644 --- a/platform/administer/users-permissions/managing-users/create.mdx +++ b/platform/administer/users-permissions/managing-users/create.mdx @@ -19,13 +19,13 @@ To create a new user in the platform: - Select the Users field on the left menu bar. + Go to Access & Secrets > Users & Roles. Click the button. - In the drawer that appears from the right, give your new user a name by + In the configuration sheet that opens, give your new user a name by replacing the 'my-user' placeholder name, or by updating the manifest YAML 'metadata.name' field. @@ -49,7 +49,7 @@ To create a new user in the platform: allow for configuring cluster roles that apply to this team, as well as Image Pull Secrets, that allow users in this team to automatically receive the provided image pull secrets upon - logging into vCluster Platform (via the vCluster CLI). + logging into vCluster Platform (using the vCluster CLI). allows you to define which users and teams have @@ -58,7 +58,7 @@ To create a new user in the platform: - Click on the button. + Click the button. @@ -87,7 +87,7 @@ The **Team Memberships** tab manages which teams this user belongs to: The **Advanced Options** section controls low-level permissions and access: - **Cluster Roles**: Define specific Kubernetes cluster roles that apply directly to this user -- **Image Pull Secrets**: Configure registry credentials that the user automatically receives when logging into vCluster Platform via the CLI +- **Image Pull Secrets**: Configure registry credentials that the user automatically receives when logging into vCluster Platform using the CLI The cluster roles defined here are combined with any roles inherited from team memberships, giving you fine-grained permission control. diff --git a/platform/administer/users-permissions/managing-users/impersonate.mdx b/platform/administer/users-permissions/managing-users/impersonate.mdx index 96c498a1ff..1cf583b26b 100644 --- a/platform/administer/users-permissions/managing-users/impersonate.mdx +++ b/platform/administer/users-permissions/managing-users/impersonate.mdx @@ -23,13 +23,13 @@ admins and users that have the management role `Impersonator` assigned, can impe - Select the Users field on the left menu bar. + Go to Access & Secrets > Users & Roles. In the user row you want to impersonate, select - To stop impersonation, either press or click on the{" "} + To stop impersonation, either press or click the{" "} button at the top. @@ -43,23 +43,23 @@ sure you are taking advantage of Projects when considering your RBAC strategy. ### 1. Create test user vCluster Platform lets you connect a variety of SSO providers for authentication but for the sake of -simplicity, let's just manually create a user to learn more about vCluster Platform's cluster access features: +simplicity, manually create a user to learn more about vCluster Platform's cluster access features: - Select the Users field on the left menu bar. + Go to Access & Secrets > Users & Roles. Click the button. - In the drawer that appears from the right, give your new user a name of{" "} + In the configuration sheet that opens, give your new user a name of{" "} Anna by replacing the 'my-user' placeholder name, or by updating the manifest YAML 'metadata. name' field. - Click on the button. + Click the button. Close the popup using the button @@ -69,21 +69,20 @@ simplicity, let's just manually create a user to learn more about vCluster Platf :::tip 100% Kubernetes Native Remember: Everything you do in vCluster Platform UI, including creating a user, is effectively a kubectl command under the hood. So, everything you do in this guide creates or changes objects in your -cluster and you could also manage these actions via kubectl or any kind of GitOps tool. +cluster and you could also manage these actions using kubectl or any kind of GitOps tool. ::: ### 2. Impersonate user -vCluster Platform allows admins with appropriate RBAC permissions to impersonate users. Let's try this to see -how vCluster Platform UI would look like for our newly created user: +vCluster Platform allows admins with appropriate RBAC permissions to impersonate users. This demonstrates +how vCluster Platform UI appears for the newly created user: - Select the Users field on the left menu bar. + Go to Access & Secrets > Users & Roles. - Find the user `Anna` in the list of users. Hover over the blue drop down - arrow in the Display Name column and click on the{" "} + Find the user `Anna` in the list of users and click the{" "} and configure a Helm chart with the following settings. + Click and configure a Helm chart with the following settings. @@ -91,22 +91,22 @@ Click to deploy Prometheus. Deploy the built-in OpenTelemetry App on each connected cluster. This OpenTelemetry App accepts the Prometheus connection information and deploys [opentelemetry-collector](https://opentelemetry.io/docs/collector/) -as a DaemonSet via Helm. +as a DaemonSet using Helm. The OpenTelemetry Collector Agent on each node pushes metrics about the workloads running on that node to the Prometheus instance. The metrics include vCluster, vCluster Platform, and Kubernetes metadata as labels. - Go to the Clusters dropdown using the menu on the left, and select the Clusters view. + Go to Infrastructure > Control Plane Clusters. - Click on the cluster where you are installing the OpenTelemetry Collector App. + Click the cluster where you are installing the OpenTelemetry Collector App. Navigate to the Apps tab. - Click on the OpenTelemetry Collector App. + Find and click the OpenTelemetry Collector App. Enter the Prometheus connection endpoint: http://prometheus-server.observability.svc.cluster.local:80 @@ -128,16 +128,16 @@ Deploy Grafana with a pre-configured Prometheus datasource and dashboard using t - Go to the Clusters dropdown using the menu on the left, and select the Clusters view. + Go to Infrastructure > Control Plane Clusters. - Click on the cluster where you deployed Prometheus. + Click the cluster where you deployed Prometheus. Navigate to the Apps tab. - Click and configure a Helm chart with the following settings. + Click and configure a Helm chart with the following settings. diff --git a/platform/maintenance/monitoring/fleet-monitoring-otel.mdx b/platform/maintenance/monitoring/fleet-monitoring-otel.mdx index 3260eaa070..07ae77d6eb 100644 --- a/platform/maintenance/monitoring/fleet-monitoring-otel.mdx +++ b/platform/maintenance/monitoring/fleet-monitoring-otel.mdx @@ -16,7 +16,7 @@ visibility into resource consumption and API health without deploying monitoring inside each tenant cluster. This guide explains how to configure OpenTelemetry Collectors to collect workload and control plane metrics from across multiple tenant clusters. All metrics are enriched with vCluster identity labels at -ingest time and pushed to a central Prometheus via `remote_write`. +enrichment time and pushed to a central Prometheus using `remote_write`. :::note For a simpler setup using the built-in OpenTelemetry DaemonSet App, see @@ -121,8 +121,8 @@ The architecture comprises the following: - Collector architecture: - A central Prometheus with the remote write receiver enabled. - - One OTel Collector Deployment with Target Allocator per Control Plane Cluster (scrapes shared-nodes tenant clusters and their control planes via ServiceMonitors). - - One OTel Collector DaemonSet per private-nodes vCluster (scrapes local kubelet, cAdvisor, and API server metrics from inside the vCluster). + - One OTel Collector Deployment with Target Allocator per Control Plane Cluster (scrapes shared-nodes tenant clusters and their control planes using ServiceMonitors). + - One OTel Collector DaemonSet per private-nodes tenant cluster (scrapes local kubelet, cAdvisor, and API server metrics from inside the tenant cluster). ## How it works @@ -160,7 +160,7 @@ node. The `groupbyattrs` processor splits the batch into per-pod resource scopes (by `namespace`, `pod`, `node`) so each pod is matched correctly. The `k8sattributes` processor resolves vCluster identity from Platform-managed -namespace labels (`loft.sh/project`, `loft.sh/vcluster-instance-name`, etc.) and +namespace labels (`loft.sh/project`, `loft.sh/vcluster-instance-name`, and others) and pod labels/annotations set by the vCluster syncer (`vcluster.loft.sh/namespace`, `vcluster.loft.sh/name`). @@ -613,17 +613,16 @@ kubectl apply -f otel-collector-shared-nodes-app.yaml - Go to the Infra section using the menu on the left, and - select the Clusters view. + Go to Infrastructure > Control Plane Clusters. - Click on the cluster where you want to deploy the collector. + Click the cluster where you want to deploy the collector. Navigate to the Apps tab. - Click and select the + Click and select the **OTEL Collector - Shared Nodes** app. @@ -647,7 +646,7 @@ Repeat these steps for each Control Plane Cluster. Deploy one private-nodes collector into each private-nodes vCluster. All -vCluster identity labels are injected automatically by the Platform via +vCluster identity labels are injected automatically by the Platform using `{{ .Values.loft.* }}`. @@ -888,7 +887,7 @@ spec: :::info Key configuration details - **DaemonSet mode**: Private-nodes tenant clusters have dedicated nodes. A DaemonSet ensures one collector per node, scraping only the local kubelet and cAdvisor - via `${env:K8S_NODE_NAME}` filtering. No Target Allocator is needed. + using `${env:K8S_NODE_NAME}` filtering. No Target Allocator is needed. - **`external_labels` instead of `k8sattributes` for identity**: The collector runs inside the vCluster, so it can't access Control Plane Cluster namespace labels. The Platform injects `{{ .Values.loft.* }}` template variables at deploy time. @@ -953,7 +952,7 @@ organized around the [Four Golden Signals](https://sre.google/sre-book/monitoring-distributed-systems/) of monitoring: latency, traffic, errors, and saturation. -Because identity labels are enriched at ingest time, every query can filter and +Because identity labels are enriched at collection time, every query can filter and aggregate by `cluster`, `vcluster_project`, and `vcluster_name` directly. ### Latency @@ -1220,7 +1219,7 @@ This section assumes Grafana is already deployed. For setup instructions, see ::: Two Grafana dashboards are provided for visualizing metrics collected by the -OTel Collectors. Both dashboards use the identity labels enriched at ingest +OTel Collectors. Both dashboards use the identity labels enriched at collection time, so all panels use straightforward PromQL queries without joins. ### Import a dashboard diff --git a/platform/use-platform/apps/updating.mdx b/platform/use-platform/apps/updating.mdx index e8b6a92597..086e57a9c0 100644 --- a/platform/use-platform/apps/updating.mdx +++ b/platform/use-platform/apps/updating.mdx @@ -16,7 +16,7 @@ while retaining the current version/iteration. Apps that are deployed from a tem updated versions will show up with a warning indicating that a newer App version is available. -### Updating An Installed App's Version +### Update an installed app version You can change the version of an installed App in a space, cluster, or tenant cluster to a newer (or older!) version in the vCluster Platform UI. @@ -31,11 +31,10 @@ newer (or older!) version in the vCluster Platform UI. - Select the Clusters field on the left menu bar. + Go to Infrastructure > Control Plane Clusters. - From the Clusters sub-menu, select the Clusters option. - Find the cluster containing the App you would like ot upgrade, and click + Find the cluster containing the App you would like to upgrade and click on that cluster. @@ -48,13 +47,12 @@ newer (or older!) version in the vCluster Platform UI. in the status column. - Either click on the button in the status column - of your target App (if the App is outdated), or click on the small drop - down button next to the App name and click on the {" "} - button. + Either click the button in the status column + of your target App (if the App is outdated), or click the {" "} + option for the App you want to modify. - From the drop down box, select the desired + From the selector, select the desired target App Version. @@ -65,18 +63,11 @@ newer (or older!) version in the vCluster Platform UI. - Select the Projects field on the left menu bar. - - - Select the project containing the tenant cluster that you'd like to - install the App in from the Project drop down menu. + Select the project containing the tenant cluster using the project selector (top left), then click Tenant Clusters. - From the Projects sub-menu, select the Tenant Clusters option. - - - Find the tenant cluster containing the App you would like to upgrade, - click on that tenant cluster. + Find the tenant cluster containing the App you would like to upgrade and + click that tenant cluster. In the Tenant Cluster Management view, click the {" "} @@ -89,13 +80,12 @@ newer (or older!) version in the vCluster Platform UI. in the status column. - Either click on the button in the status column - of your target App (if the App is outdated), or click on the small drop - down button next to the App name and click on the {" "} - button. + Either click the button in the status column + of your target App (if the App is outdated), or click the {" "} + option for the App you want to modify. - From the drop down box, select the desired + From the selector, select the desired target App Version. diff --git a/platform/use-platform/apps/use-in-templates.mdx b/platform/use-platform/apps/use-in-templates.mdx index c03c48e859..dc45eaed81 100644 --- a/platform/use-platform/apps/use-in-templates.mdx +++ b/platform/use-platform/apps/use-in-templates.mdx @@ -27,10 +27,7 @@ a template, that app will be deployed in the given resource upon creation. - Select the Templates field on the left menu bar. - - - From the Templates sub-menu, select the Tenant Clusters option. + Go to Tenant Management > Cluster Templates. Edit an existing template, or create a new tenant cluster template. @@ -43,12 +40,8 @@ a template, that app will be deployed in the given resource upon creation. be deployed *in* the tenant cluster! - From the drop down menu select an App - that you would like to be included as part of the template. You can - select as many Apps as you would like here by simply selecting another - App from the drop down menu. If you accidentally add one, or add one you - do not want, click the trash icon next to the Apps name to remove it - from the template. + Select an App from the selector to include it in the template. You can + add as many Apps as you like by selecting another. To remove one, click the trash icon next to the App name. For each App you added to the template, you can configure the default @@ -67,12 +60,8 @@ a template, that app will be deployed in the given resource upon creation. in (not inside the tenant cluster itself). - From the drop down menu select an App - that you would like to be included as part of the template. You can - select as many Apps as you would like here by simply selecting another - App from the drop down menu. If you accidentally add one, or add one you - do not want, click the trash icon next to the Apps name to remove it - from the template. + Select an App from the selector to include it in the template. You can + add as many Apps as you like by selecting another. To remove one, click the trash icon next to the App name. For each App you added to the template, you can any App parameters diff --git a/platform/use-platform/apps/use-on-demand.mdx b/platform/use-platform/apps/use-on-demand.mdx index 86a9d3efcc..e4360a0182 100644 --- a/platform/use-platform/apps/use-on-demand.mdx +++ b/platform/use-platform/apps/use-on-demand.mdx @@ -40,7 +40,7 @@ development, test, or even production, environments in a single easy to manage p tenant cluster in. - Click on Tenant Clusters. + Click Tenant Clusters. Click the button. Do not select a template. @@ -60,12 +60,9 @@ development, test, or even production, environments in a single easy to manage p be deployed *in* the tenant cluster. - From the drop down menu , select an - application that you would like to be deployed. You can - select as many as you would like by simply selecting another - application from the drop down menu. If you accidentally add one, or add one you - do not want, click the trash icon next to the names of the applications to remove it - from the configuration. + Select an application from the selector. You can + add as many as you like by selecting another. To remove one, click the trash icon + next to the application name. For each application that you added to the template, you can configure the default @@ -88,16 +85,14 @@ development, test, or even production, environments in a single easy to manage p -## Installing Apps on a Cluster +## Install apps on a cluster - Select the Clusters field on the left menu bar. + Go to Infrastructure > Control Plane Clusters. - From the Clusters sub-menu, select the Clusters option. - Find the cluster you would like to deploy an App to in the list of - connected clusters and click on that cluster. + Find the cluster you would like to deploy an App to and click it. In the Cluster Management view, click the button. @@ -105,7 +100,7 @@ development, test, or even production, environments in a single easy to manage p Select the App you would like to install from the App thumbnails, or, if there are no recommend Apps, click the and - find the desired App in the drop down menu. + select the desired App from the selector. In the Install App screen enter the namespace to install the App to in diff --git a/platform/use-platform/apps/use-parameters.mdx b/platform/use-platform/apps/use-parameters.mdx index 6166a31070..df2179f34f 100644 --- a/platform/use-platform/apps/use-parameters.mdx +++ b/platform/use-platform/apps/use-parameters.mdx @@ -9,20 +9,19 @@ import NavStep from "@site/src/components/NavStep"; import Button from "@site/src/components/Button"; import Label from "@site/src/components/Label"; -## Creating an App with Parameters +## Create an app with parameters -Creating an App with Parameters can be achieved via the vCluster Platform UI. +Apps with parameters can be created through the vCluster Platform UI. - Select the Templates field on the left menu bar. + Go to Tenant Management > Apps. - Click the Apps option on the templates pane. Click . - In the drawer that appears from the right, give your new app a name by + In the configuration sheet that opens, give your new app a name by replacing the 'my-app' placeholder name, or by updating the manifest YAML 'metadata.name' field. diff --git a/platform/use-platform/namespaces/_partials/auto-delete/configure-ui.mdx b/platform/use-platform/namespaces/_partials/auto-delete/configure-ui.mdx index 261978b969..0a80d1c0ec 100644 --- a/platform/use-platform/namespaces/_partials/auto-delete/configure-ui.mdx +++ b/platform/use-platform/namespaces/_partials/auto-delete/configure-ui.mdx @@ -10,15 +10,15 @@ import Expander from '@site/src/components/Expander' In the Projects > {props.name === "tenant cluster" ? "Tenant Clusters" : "Namespaces"} view, hover over the {props.name} that you want to configure auto-delete for - Click on the button to the {props.name} + Click the option for the {props.name} you want to modify. - In the drawer that appears on the right, expand the Sleep Mode section. This only works for {props.name}s without a template, if you want to change the auto delete configuration for a {props.name} created by a template, please do the changes in the Templates view + In the configuration sheet that opens, expand the Sleep Mode section. This only works for {props.name}s without a template. To change auto-delete for a {props.name} created by a template, make the changes in the Templates view. Use the field to specify the time to wait before deleting the {props.name} if there was no more user activity within this {props.name} - On the very bottom, click on the button to save the changes + Click . \ No newline at end of file diff --git a/platform/use-platform/namespaces/_partials/namespace/add-app-ui.mdx b/platform/use-platform/namespaces/_partials/namespace/add-app-ui.mdx index cf8e86010b..107f2a9461 100644 --- a/platform/use-platform/namespaces/_partials/namespace/add-app-ui.mdx +++ b/platform/use-platform/namespaces/_partials/namespace/add-app-ui.mdx @@ -4,26 +4,16 @@ import Button from '@site/src/components/Button' import Label from '@site/src/components/Label' - Select the Projects field on the left menu bar. + Select the project containing the namespace using the project selector (top left), then click Namespaces. - Select the project containing the namespace that you'd like to install - the App in from the Project drop down menu. + Find the namespace you would like to deploy an App to and click it. - From the Projects sub-menu, select the Namespaces option. + In the Namespace Management view, click . - Find the namespace you would like to deploy an App to in the list of namespaces, and click on that - namespace. - - - In the Namespace Management view, click the button. - - - Select the App you would like to install from the App thumbnails, or, if there - are no recommend Apps, click the and find the - desired App in the drop down menu. + Select the App you would like to install from the App thumbnails, or click and select the desired App. Enter any other required parameters for your App -- this may vary depending on diff --git a/platform/use-platform/namespaces/_partials/namespace/delete-ui.mdx b/platform/use-platform/namespaces/_partials/namespace/delete-ui.mdx index c4ba6dbd33..c51729f78e 100644 --- a/platform/use-platform/namespaces/_partials/namespace/delete-ui.mdx +++ b/platform/use-platform/namespaces/_partials/namespace/delete-ui.mdx @@ -15,6 +15,6 @@ import CreateNamespaceStep2 from '@site/static/media/ui/screenshots/spaces/creat While hovering over the row, you will see buttons appear on the right in the column - Click on the button to the namespace + Click the button to the namespace \ No newline at end of file diff --git a/platform/use-platform/namespaces/_partials/namespace/share-ui.mdx b/platform/use-platform/namespaces/_partials/namespace/share-ui.mdx index a0ac3ea87f..59a2faff19 100644 --- a/platform/use-platform/namespaces/_partials/namespace/share-ui.mdx +++ b/platform/use-platform/namespaces/_partials/namespace/share-ui.mdx @@ -7,21 +7,21 @@ import Expander from '@site/src/components/Expander' - Go to the Projects view using the menu on the left + Select the project using the project selector (top left), then click Namespaces. - Click on Namespaces and click on the Edit link on a namespace. + Find the namespace and click . - In the drawer select the 'Permissions' section. + In the configuration sheet that opens, click the tab. - Select the user or team you want to grant permissions in the 'User or Team' select. If you don't see the user or team you want to grant access in there, make sure they have project access. + Select the user or team you want to grant permissions from the selector. If the user or team is not listed, make sure they have project access. - Specify the cluster-role you want to assign the user or team within the namespace. + Specify the cluster role you want to assign the user or team within the namespace. - Click on the button at the very bottom + Click . \ No newline at end of file diff --git a/platform/use-platform/namespaces/_partials/sleep/configure-ui.mdx b/platform/use-platform/namespaces/_partials/sleep/configure-ui.mdx index 3c4c1639c5..f89340d3db 100644 --- a/platform/use-platform/namespaces/_partials/sleep/configure-ui.mdx +++ b/platform/use-platform/namespaces/_partials/sleep/configure-ui.mdx @@ -13,15 +13,15 @@ import CreateSpaceStep2 from '@site/static/media/ui/screenshots/spaces/create-sp In the Projects > {props.name === "tenant cluster" ? "Tenant Clusters" : "Namespaces"} view, hover over the {props.name} that you want to configure auto sleep for - Click on the button to the {props.name} + Click on the {props.name}. - In the drawer that appears on the right, expand the Sleep section. This only works for {props.name}s without a template, if you want to change the auto sleep configuration for a {props.name} created by a template, do the changes in the Templates view + In the configuration sheet that opens, expand the Sleep section. This only works for {props.name}s without a template. To change auto-sleep for a {props.name} created by a template, make the changes in the Templates view. - Use the field to specify the time to wait before putting the {props.name} to sleep if there is no more user activity in this {props.name} + Use the field to specify the time to wait before putting the {props.name} to sleep if there is no more user activity. - On the very bottom, click on the button to save the changes + Click . diff --git a/platform/use-platform/namespaces/_partials/sleep/schedule-ui.mdx b/platform/use-platform/namespaces/_partials/sleep/schedule-ui.mdx index 65dc7c015f..08e36e85b1 100644 --- a/platform/use-platform/namespaces/_partials/sleep/schedule-ui.mdx +++ b/platform/use-platform/namespaces/_partials/sleep/schedule-ui.mdx @@ -10,18 +10,18 @@ import Expander from '@site/src/components/Expander' In the Projects > {props.name === "tenant cluster" ? "Tenant Clusters" : "Namespaces"} view, hover over {props.name} that you want to configure auto sleep for - Click on the button to the {props.name} + Click on the {props.name}. - In the drawer that appears on the right, expand the Sleep Mode {props.name}. This only works for {props.name}s without a template, if you want to change the auto sleep configuration for a {props.name} created by a template, do the changes in the Templates view + In the configuration sheet that opens, expand the Sleep Mode section. This only works for {props.name}s without a template. To change auto-sleep for a {props.name} created by a template, make the changes in the Templates view. - Expand the Sleep & Wake-Up Schedule section + Expand the Sleep & Wake-Up Schedule section. - Use the field and/or the field to specify the Cronjob Times when the respective {props.name} should be put to sleep or woken up + Use the field and the field to specify when the {props.name} should be put to sleep or woken up. - On the very bottom, click on the button to save the changes + Click . \ No newline at end of file diff --git a/platform/use-platform/namespaces/_partials/space-constraints/create-ui.mdx b/platform/use-platform/namespaces/_partials/space-constraints/create-ui.mdx index cc25369460..32fd25ba4f 100644 --- a/platform/use-platform/namespaces/_partials/space-constraints/create-ui.mdx +++ b/platform/use-platform/namespaces/_partials/space-constraints/create-ui.mdx @@ -11,16 +11,16 @@ import CreateNamespaceStep2 from '@site/static/media/ui/screenshots/spaces/creat - Go to the Clusters view using the menu on the left + Go to Infrastructure > Control Plane Clusters. - Switch to the tab + Switch to the tab. - Click the button to create a new namespace constraints object + Click . - In the drawer that appears on the right, use the field to specify a Name for your namespace constraints object + In the configuration sheet that opens, use the field to specify a Name for your namespace constraints object. Expand the Enforce Resources section to specify manifests that should be deployed to and enforced in each namespace that is affected by these namespace constraints @@ -29,6 +29,6 @@ import CreateNamespaceStep2 from '@site/static/media/ui/screenshots/spaces/creat Expand the Enforce Namespace Settings section to specify other namespace settings such as sleep mode, auto-delete, labels and annotations that should be enforced for each namespace that is affected by these namespace constraints - On the very bottom, click on the button to create this namespace constraints object + Click to create this namespace constraints object. \ No newline at end of file diff --git a/platform/use-platform/namespaces/_partials/space-constraints/enforce-ui.mdx b/platform/use-platform/namespaces/_partials/space-constraints/enforce-ui.mdx index 5a7906c385..b4c229a7b6 100644 --- a/platform/use-platform/namespaces/_partials/space-constraints/enforce-ui.mdx +++ b/platform/use-platform/namespaces/_partials/space-constraints/enforce-ui.mdx @@ -11,37 +11,37 @@ import CreateNamespaceStep2 from '@site/static/media/ui/screenshots/spaces/creat - Go to the Clusters view using the menu on the left + Go to Infrastructure > Control Plane Clusters. - Switch to the tab + Switch to the tab. - Hover over the cluster access that you want to apply these namespace constraints to and click on the button to the cluster access + Click on the cluster access you want to apply these namespace constraints to. - In the drawer that appears on the right, expand the Restrictions section + In the configuration sheet that opens, expand the Restrictions section. - Use the field to select the Namespace Constraint that you want to enforce for all namespaces created using this cluster access + Use the field to select the namespace constraint you want to enforce for all namespaces created using this cluster access. - On the very bottom, click on the or button to save the changes + Click or to save the changes. - Switch to the tab + Switch to the tab. - Hover over the cluster access of the user or team that you want to configure automatic sleep mode for and click on the button to the cluster access + Click on the cluster access for the user or team you want to configure. - In the drawer that appears on the right, expand the Restrictions section + In the configuration sheet that opens, expand the Restrictions section. - Use the field to select the Namespace Constraint you edited or created in Step 3 above + Use the field to select the namespace constraint you edited or created above. - On the very bottom, click on the button to save the changes + Click to save the changes. diff --git a/platform/use-platform/namespaces/key-features/custom-links.mdx b/platform/use-platform/namespaces/key-features/custom-links.mdx index 4dd8fbf762..ccd29d4562 100644 --- a/platform/use-platform/namespaces/key-features/custom-links.mdx +++ b/platform/use-platform/namespaces/key-features/custom-links.mdx @@ -33,13 +33,13 @@ For more information on configuring custom links for tenant clusters, see the [C Edit an existing Namespace or create a new one. - Click to add a new link or to edit an existing one. + Click the edit icon next to the links section to open the links editor. Click to add a new link. Enter a URL and optionally a label for your link. - Click . + Click . Click , diff --git a/platform/use-platform/namespaces/key-features/prevent-deletion.mdx b/platform/use-platform/namespaces/key-features/prevent-deletion.mdx index 3a07108b8c..31e41757ab 100644 --- a/platform/use-platform/namespaces/key-features/prevent-deletion.mdx +++ b/platform/use-platform/namespaces/key-features/prevent-deletion.mdx @@ -44,7 +44,7 @@ spec: - Navigate to the Projects section using the menu on the left. + Go to Projects. @@ -52,8 +52,7 @@ spec: - Either click on the button or select the - dropdown next to an existing namespace and select the option. + Either click the button or click the option for the namespace you want to modify. @@ -61,13 +60,12 @@ spec: - Select the Prevent Deletion expander and tick the "enable - deletion prevention" checkbox. + Select the Prevent Deletion expander and enable . - Click on the button to save the changes or the{" "} - button, when creating a new namespace. + Click the button to save the changes, or the{" "} + button when creating a new namespace. diff --git a/platform/use-platform/virtual-clusters/key-features/custom-links.mdx b/platform/use-platform/virtual-clusters/key-features/custom-links.mdx index d7135441e0..f0e491a54f 100644 --- a/platform/use-platform/virtual-clusters/key-features/custom-links.mdx +++ b/platform/use-platform/virtual-clusters/key-features/custom-links.mdx @@ -9,6 +9,7 @@ import TabItem from "@theme/TabItem"; import NavStep from "@site/src/components/NavStep"; import Button from "@site/src/components/Button"; import Label from "@site/src/components/Label"; +import Flow, { Step } from "@site/src/components/Flow"; vCluster Platform lets you associate custom links to tenant cluster instances, for example to point to a github pull request or jira issue. @@ -19,12 +20,11 @@ vCluster Platform lets you associate custom links to tenant cluster instances, f {label: 'CLI', value: 'cli'}, ]}> - 1. Go to the Tenant Clusters view using the menu on the left - 1. Edit an existing Tenant Cluster or create a new one - 1. Click to add a new link or to edit existing ones. + 1. Select your project from the project selector, then click Tenant Clusters. + 1. Edit an existing tenant cluster or create a new one. + 1. Click the edit icon next to the links section to open the links editor. Click to add a new link. 1. Enter a URL and optionally a label for your link. - 1. Save your links by clicking . - 1. Click on the , or if you're editing an existing tenant cluster, to apply all changes. + 1. Click , or if you're editing an existing tenant cluster, to apply all changes. diff --git a/platform/use-platform/virtual-clusters/key-features/prevent-deletion.mdx b/platform/use-platform/virtual-clusters/key-features/prevent-deletion.mdx index 8577b15fe6..1fda3e330d 100644 --- a/platform/use-platform/virtual-clusters/key-features/prevent-deletion.mdx +++ b/platform/use-platform/virtual-clusters/key-features/prevent-deletion.mdx @@ -53,20 +53,20 @@ spec: tenant cluster in. - Click on Tenant Clusters. + Click Tenant Clusters. - Click on on the tenant cluster that you want to edit. + Click the option for the tenant cluster you want to modify. Navigate to section on the left. - Select the Prevent Deletion expander and tick the checkbox. + Select the Prevent Deletion expander and enable . - Click on the button to save the changes. + Click the button to save the changes. diff --git a/scripts/report-platform-ui-drift.js b/scripts/report-platform-ui-drift.js new file mode 100644 index 0000000000..1533646153 --- /dev/null +++ b/scripts/report-platform-ui-drift.js @@ -0,0 +1,431 @@ +#!/usr/bin/env node + +/** + * Reports likely drift between Platform docs UI tokens and the Platform UI source. + * + * Usage: + * npm run report-platform-ui-drift + * node scripts/report-platform-ui-drift.js --json + * node scripts/report-platform-ui-drift.js --ui-src ../loft-enterprise/ui/src + */ + +const fs = require('fs'); +const path = require('path'); +const glob = require('glob'); + +const DOC_COMPONENTS = ['Button', 'Label', 'NavStep', 'Field', 'Input']; +const UI_TEXT_PROPS = [ + 'aria-label', + 'description', + 'displayName', + 'label', + 'name', + 'placeholder', + 'saveText', + 'submitLabel', + 'title', + 'tooltip', +]; +const INSTRUCTION_PHRASES = [ + /\bdrop ?down arrow\b/gi, + /\bdrop ?down menu\b/gi, + /\bdrawer\b/gi, + /\bconfiguration pane\b/gi, + /\btextarea\b/gi, + /\bcheckbox\b/gi, + /\bleft menu\b/gi, + /\bleft sidebar\b/gi, +]; +const DEFAULT_DOCS_ROOT = path.join(__dirname, '..', 'platform'); +const DEFAULT_UI_SRC = path.join(__dirname, '..', '..', 'loft-enterprise', 'ui', 'src'); +const UI_FILE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx']); +const UI_IGNORE = [ + '**/__mocks__/**', + '**/gen/**', + '**/schemas/**', + '**/*.spec.*', + '**/*.test.*', + '**/*.d.ts', +]; +const MIN_TOKEN_LENGTH = 3; + +function parseArgs(argv) { + const args = { + docsRoot: DEFAULT_DOCS_ROOT, + uiSrc: DEFAULT_UI_SRC, + json: false, + }; + + for (let i = 2; i < argv.length; i += 1) { + const arg = argv[i]; + + if (arg === '--json') { + args.json = true; + continue; + } + + if (arg === '--docs-root') { + args.docsRoot = path.resolve(argv[++i]); + continue; + } + + if (arg === '--ui-src') { + args.uiSrc = path.resolve(argv[++i]); + continue; + } + + throw new Error(`Unknown argument: ${arg}`); + } + + return args; +} + +function assertDirectory(dir, label) { + if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) { + throw new Error(`${label} does not exist or is not a directory: ${dir}`); + } +} + +function normalizeText(value) { + return value + .replace(/\{['"`]\s*['"`]\}/g, ' ') + .replace(/\{['"`]([^'"`]+)['"`]\}/g, '$1') + .replace(/<[^>]+>/g, ' ') + .replace(/ /g, ' ') + .replace(/&/g, '&') + .replace(/\s+/g, ' ') + .trim(); +} + +function normalizeForSearch(value) { + return normalizeText(value) + .toLowerCase() + .replace(/argocd/g, 'argo cd') + .replace(/vcluster/g, 'vcluster') + .replace(/[\u2018\u2019]/g, "'") + .replace(/[\u201c\u201d]/g, '"') + .replace(/[.。]+$/g, '') + .replace(/\s+/g, ' ') + .trim(); +} + +function getNavStepSegments(value) { + return normalizeText(value) + .split('>') + .map((segment) => normalizeForSearch(segment)) + .filter((segment) => segment.length >= MIN_TOKEN_LENGTH); +} + +function getLineNumber(content, index) { + return content.slice(0, index).split('\n').length; +} + +function extractTokens(filePath, docsRoot) { + const content = fs.readFileSync(filePath, 'utf8'); + const tokens = []; + const skippedDynamic = []; + const instructionPhrases = []; + + for (const component of DOC_COMPONENTS) { + const pattern = new RegExp(`<${component}(?:\\s[^>]*)?>([\\s\\S]*?)<\\/${component}>`, 'g'); + let match; + + while ((match = pattern.exec(content)) !== null) { + const text = normalizeText(match[1]); + const normalized = normalizeForSearch(text); + const line = getLineNumber(content, match.index); + + if (/[{}]/.test(normalized)) { + skippedDynamic.push({ + component, + text, + file: path.relative(docsRoot, filePath), + line, + }); + continue; + } + + if (normalized.length < MIN_TOKEN_LENGTH) { + continue; + } + + tokens.push({ + component, + text, + normalized, + file: path.relative(docsRoot, filePath), + line, + }); + } + } + + const contentLines = content.split('\n'); + const proseContent = contentLines + .map((line) => (/^\s*import\s/.test(line) ? '' : line)) + .join('\n'); + + for (const phrasePattern of INSTRUCTION_PHRASES) { + let match; + + while ((match = phrasePattern.exec(proseContent)) !== null) { + instructionPhrases.push({ + text: normalizeText(match[0]), + normalized: normalizeForSearch(match[0]), + file: path.relative(docsRoot, filePath), + line: getLineNumber(proseContent, match.index), + }); + } + } + + return { tokens, skippedDynamic, instructionPhrases }; +} + +function getMdxFiles(docsRoot) { + return glob.sync('**/*.mdx', { + cwd: docsRoot, + absolute: true, + nodir: true, + ignore: ['**/node_modules/**', '**/build/**', '**/.docusaurus/**'], + }); +} + +function getUiFiles(uiSrc) { + return glob + .sync('**/*', { + cwd: uiSrc, + absolute: true, + nodir: true, + ignore: UI_IGNORE, + }) + .filter((file) => UI_FILE_EXTENSIONS.has(path.extname(file))); +} + +function buildUiIndex(uiSrc) { + const files = getUiFiles(uiSrc); + const haystack = files + .map((file) => normalizeUiSource(fs.readFileSync(file, 'utf8'))) + .join('\n'); + + return { + fileCount: files.length, + hasToken: (token) => haystack.includes(token), + }; +} + +function normalizeUiSource(content) { + return [content, extractUiTextProps(content)].map((value) => normalizeForSearch(value)).join('\n'); +} + +function extractUiTextProps(content) { + const propPattern = new RegExp( + `(?:${UI_TEXT_PROPS.join('|')})\\s*=\\s*(?:"([^"]+)"|'([^']+)'|\\{\\s*["'\`]([^"'\`]+)["'\`]\\s*\\})`, + 'g' + ); + const values = []; + let match; + + while ((match = propPattern.exec(content)) !== null) { + values.push(match[1] ?? match[2] ?? match[3]); + } + + return values.join('\n'); +} + +function isTokenFound(token, uiIndex) { + if (token.component !== 'NavStep') { + return uiIndex.hasToken(token.normalized); + } + + const segments = getNavStepSegments(token.text); + if (segments.length > 1) { + return segments.every((segment) => uiIndex.hasToken(segment)); + } + + return uiIndex.hasToken(token.normalized); +} + +function summarize(tokens, uiIndex) { + const byKey = new Map(); + + for (const token of tokens) { + const key = `${token.component}\0${token.normalized}`; + const existing = byKey.get(key); + + if (existing) { + existing.occurrences.push({ file: token.file, line: token.line }); + continue; + } + + byKey.set(key, { + component: token.component, + text: token.text, + normalized: token.normalized, + foundInUi: isTokenFound(token, uiIndex), + occurrences: [{ file: token.file, line: token.line }], + }); + } + + return Array.from(byKey.values()).sort((a, b) => { + if (a.foundInUi !== b.foundInUi) return a.foundInUi ? 1 : -1; + if (a.component !== b.component) return a.component.localeCompare(b.component); + return a.text.localeCompare(b.text); + }); +} + +function groupByFile(unmatched) { + const groups = new Map(); + + for (const token of unmatched) { + for (const occurrence of token.occurrences) { + const group = groups.get(occurrence.file) ?? []; + group.push({ + line: occurrence.line, + component: token.component, + text: token.text, + }); + groups.set(occurrence.file, group); + } + } + + return Array.from(groups.entries()) + .map(([file, tokens]) => ({ + file, + tokens: tokens.sort((a, b) => a.line - b.line || a.text.localeCompare(b.text)), + })) + .sort((a, b) => a.file.localeCompare(b.file)); +} + +function summarizeInstructionPhrases(phrases) { + const byKey = new Map(); + + for (const phrase of phrases) { + const key = `${phrase.file}\0${phrase.line}\0${phrase.normalized}`; + if (byKey.has(key)) { + continue; + } + + byKey.set(key, { + text: phrase.text, + normalized: phrase.normalized, + file: phrase.file, + line: phrase.line, + }); + } + + return Array.from(byKey.values()).sort((a, b) => { + if (a.file !== b.file) return a.file.localeCompare(b.file); + return a.line - b.line || a.text.localeCompare(b.text); + }); +} + +function groupInstructionPhrasesByFile(phrases) { + const groups = new Map(); + + for (const phrase of phrases) { + const group = groups.get(phrase.file) ?? []; + group.push({ + line: phrase.line, + text: phrase.text, + }); + groups.set(phrase.file, group); + } + + return Array.from(groups.entries()) + .map(([file, phrases]) => ({ + file, + phrases: phrases.sort((a, b) => a.line - b.line || a.text.localeCompare(b.text)), + })) + .sort((a, b) => a.file.localeCompare(b.file)); +} + +function printReport(report) { + console.log('Platform UI docs drift token report'); + console.log(''); + console.log(`Docs root: ${report.docsRoot}`); + console.log(`UI src: ${report.uiSrc}`); + console.log(`Docs files scanned: ${report.docsFilesScanned}`); + console.log(`UI files scanned: ${report.uiFilesScanned}`); + console.log(`Unique UI tokens: ${report.uniqueTokens}`); + console.log(`Matched in UI: ${report.matchedTokens}`); + console.log(`Unmatched in UI: ${report.unmatchedTokens}`); + console.log(`Skipped dynamic: ${report.skippedDynamicTokens}`); + console.log(`Instruction phrases:${report.instructionPhraseCount}`); + + if (report.unmatched.length === 0) { + console.log(''); + console.log('No unmatched docs UI tokens found.'); + return; + } + + console.log(''); + console.log('Unmatched tokens by docs file:'); + + for (const group of report.unmatched) { + console.log(''); + console.log(group.file); + + for (const token of group.tokens) { + console.log(` ${token.line}: <${token.component}>${token.text}`); + } + } + + console.log(''); + console.log('Note: this is a report-only heuristic. Unmatched tokens are review leads, not proof of drift.'); + + if (report.instructionPhrases.length === 0) { + return; + } + + console.log(''); + console.log('Unwrapped UI-instruction phrases:'); + + for (const group of report.instructionPhrases) { + console.log(''); + console.log(group.file); + + for (const phrase of group.phrases) { + console.log(` ${phrase.line}: ${phrase.text}`); + } + } +} + +function main() { + const args = parseArgs(process.argv); + assertDirectory(args.docsRoot, 'Docs root'); + assertDirectory(args.uiSrc, 'UI source directory'); + + const mdxFiles = getMdxFiles(args.docsRoot); + const extractionResults = mdxFiles.map((file) => extractTokens(file, args.docsRoot)); + const tokens = extractionResults.flatMap((result) => result.tokens); + const skippedDynamic = extractionResults.flatMap((result) => result.skippedDynamic); + const instructionPhrases = extractionResults.flatMap((result) => result.instructionPhrases); + const uiIndex = buildUiIndex(args.uiSrc); + const summarized = summarize(tokens, uiIndex); + const unmatched = summarized.filter((token) => !token.foundInUi); + const matched = summarized.length - unmatched.length; + const summarizedInstructionPhrases = summarizeInstructionPhrases(instructionPhrases); + + const report = { + docsRoot: args.docsRoot, + uiSrc: args.uiSrc, + docsFilesScanned: mdxFiles.length, + uiFilesScanned: uiIndex.fileCount, + uniqueTokens: summarized.length, + matchedTokens: matched, + unmatchedTokens: unmatched.length, + skippedDynamicTokens: skippedDynamic.length, + skippedDynamic, + instructionPhraseCount: summarizedInstructionPhrases.length, + instructionPhrases: groupInstructionPhrasesByFile(summarizedInstructionPhrases), + unmatched: groupByFile(unmatched), + }; + + if (args.json) { + console.log(JSON.stringify(report, null, 2)); + return; + } + + printReport(report); +} + +main(); From 5deabc28e164c42dcd7746c64b7c350e2bff2cc1 Mon Sep 17 00:00:00 2001 From: Daryl White Date: Fri, 26 Jun 2026 12:54:59 -0400 Subject: [PATCH 5/5] docs(doc-1574): update platform-ui-drift skill with known expected tokens and current baseline Co-Authored-By: Claude Sonnet 4.6 --- .claude/skills/platform-ui-drift/SKILL.md | 24 ++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/.claude/skills/platform-ui-drift/SKILL.md b/.claude/skills/platform-ui-drift/SKILL.md index b8029066f3..e51d0f41d3 100644 --- a/.claude/skills/platform-ui-drift/SKILL.md +++ b/.claude/skills/platform-ui-drift/SKILL.md @@ -37,6 +37,17 @@ Tokens in `` | `_partials/space-constraints/create-ui.mdx`, `use-platform/namespaces/_partials/space-constraints/create-ui.mdx` | Feature exists (breadcrumb in `breadcumbsTransforms.ts`) but has no dedicated UI component files in source | +| `` | `use-platform/namespaces/_partials/space-constraints/enforce-ui.mdx` | Same — no component file to grep | + **Common false negatives (real drift the script misses):** - `Admin > Config` — matched because "admin" and "config" appear elsewhere in code, but the real nav path is `Platform > Platform Config`. Always verify `Admin > *` paths manually. @@ -178,18 +189,9 @@ Common warnings triggered by drift fixes: - Title-case headings → sentence case - `via` → `using` -## Files with known drift clusters - -These files contain multiple unmatched tokens or instruction phrases and are good candidates for a batch fix pass: +## Drift baseline (as of 2026-06-26) -- `administer/clusters/advanced/ingress-suffix.mdx` — same nav/drawer/dropdown pattern as agent-config -- `configure/agent-settings/agent-upgrade.mdx` — same pattern -- `configure/agent-settings/customization.mdx` — same pattern -- `administer/clusters/cluster-roles.mdx` — fixed 2026-06-26 -- `administer/clusters/advanced/agent-config.mdx` — fixed 2026-06-26 -- `administer/projects/` — Allowed Templates / Allowed Clusters / Configure Project Quotas all stale -- `administer/templates/` — "left menu" throughout, dropdown references -- All files with `left sidebar` in `integrations/argocd/` — two occurrences +After the DOC-1574 sweep, the report stands at 4 unmatched tokens (all in the "known expected" table above) and 0 instruction phrases. Any new findings above this baseline represent genuine drift introduced since that date. ## Release checklist use