From 80bcc2e9eae2350c5de8891625eff8c242ded6c8 Mon Sep 17 00:00:00 2001 From: Daryl White Date: Thu, 11 Jun 2026 14:32:32 -0400 Subject: [PATCH 1/8] docs(platform): add architecture page with diagrams Adds platform/introduction/architecture.mdx covering the management plane, connected clusters and agents, failure behavior, entry points, project and tenant resource lifecycle, and network paths. Includes four SVG diagrams. Cross-links added from platform_intro, platform_communication, what-are-clusters, and what-are-projects. Closes DOC-1488 Co-Authored-By: Claude Sonnet 4.6 --- platform/introduction/architecture.mdx | 173 ++++++++++++++++++ platform/introduction/platform_intro.mdx | 2 + .../understand/platform_communication.mdx | 3 +- platform/understand/what-are-clusters.mdx | 2 + platform/understand/what-are-projects.mdx | 2 + .../platform-architecture-overview.svg | 71 +++++++ .../diagrams/platform-entry-points.svg | 59 ++++++ .../diagrams/platform-network-paths.svg | 58 ++++++ .../diagrams/platform-tenant-lifecycle.svg | 50 +++++ 9 files changed, 419 insertions(+), 1 deletion(-) create mode 100644 platform/introduction/architecture.mdx create mode 100644 static/media/platform/diagrams/platform-architecture-overview.svg create mode 100644 static/media/platform/diagrams/platform-entry-points.svg create mode 100644 static/media/platform/diagrams/platform-network-paths.svg create mode 100644 static/media/platform/diagrams/platform-tenant-lifecycle.svg diff --git a/platform/introduction/architecture.mdx b/platform/introduction/architecture.mdx new file mode 100644 index 0000000000..4ba8e6bfe2 --- /dev/null +++ b/platform/introduction/architecture.mdx @@ -0,0 +1,173 @@ +--- +title: Architecture +sidebar_label: Architecture +sidebar_position: 3 +description: Understand the vCluster Platform management plane, connected cluster agents, resource lifecycle, and network paths. +--- + +import GlossaryTerm from '@site/src/components/GlossaryTerm'; +import PlatformArchitectureOverview from '@site/static/media/platform/diagrams/platform-architecture-overview.svg'; +import PlatformEntryPoints from '@site/static/media/platform/diagrams/platform-entry-points.svg'; +import PlatformTenantLifecycle from '@site/static/media/platform/diagrams/platform-tenant-lifecycle.svg'; +import PlatformNetworkPaths from '@site/static/media/platform/diagrams/platform-network-paths.svg'; + +vCluster Platform is the management plane for your tenant cluster fleet. It runs in Kubernetes and exposes UI, CLI, and API entry points. It also reconciles Platform resources into connected Control Plane Clusters. + +Platform does not replace vCluster. Platform manages projects, users, templates, connected clusters, access, lifecycle automation, and node provisioning. vCluster remains the runtime that creates and runs each tenant cluster control plane. For vCluster internals, see the [vCluster architecture](/docs/vcluster/introduction/architecture). + +
+ +
Platform management plane and connected clusters
+
+ +## Management plane + +The Platform management plane runs as the `vcluster-platform` Helm chart. A standard installation deploys these components into the Platform namespace. + +The management plane is responsible for: + +- **Platform manager**. Runs the controllers that reconcile Platform resources. +- **API gateway**. Serves authenticated UI, CLI, integration, and automation requests. +- **Web UI**. Provides the browser interface for the Platform API. It runs as part of the management API process, not as a separate deployment. +- **Management API**. Serves resources such as Project, Cluster, VirtualClusterInstance, VirtualClusterTemplate, AccessKey, NodeProvider, and NodeClaim. +- **Operational services**. Coordinate audit events, metrics, cost data, sleep and wake behavior, snapshots, backups, and configured integrations. + +By default, Platform stores management resources as Kubernetes custom resources in the cluster where Platform runs. High-availability and multi-region deployments can configure an external database instead of the management cluster's own etcd. Platform availability depends on the management plane and its backing datastore. + +Platform follows the Kubernetes controller model. Users and automation create or update API resources. Controllers compare those resources with the actual state of connected clusters. They then create, update, or clean up dependent resources. + +## Connected clusters and agents + +A connected cluster is a Kubernetes cluster registered with Platform. Connected clusters are where tenant cluster control planes and project workloads run. Platform automatically registers the cluster where it is installed as the local cluster. Smaller deployments can run tenant clusters there too. + +Connecting a cluster installs the same Platform chart in `agentOnly` mode. In this mode, the chart starts the Platform image as the agent. It does not start the full management plane. The agent runs in the connected cluster and authenticates with a cluster access key. It keeps cluster-side state in sync with Platform. + +The agent handles work that must happen inside the connected cluster: + +- Installing and updating cluster-side resources required by Platform. +- Creating namespaces, RBAC, Helm releases, and Kubernetes resources for tenant clusters and spaces. +- Reporting status, health, and resource data back to Platform. +- Participating in proxy paths when Platform forwards requests to connected cluster or tenant cluster APIs. +- Supporting sleep, wake, and lifecycle operations that depend on the cluster where the tenant resources run. + +The agent uses outbound connectivity to Platform. Connected clusters do not need inbound access from Platform for the basic management channel. If the connection to Platform is interrupted, existing tenant clusters continue operating. Platform proxy access and lifecycle operations resume once the connection is restored. + +## Failure behavior + +| Condition | What continues | What is affected | +|---|---|---| +| Platform is unavailable | Existing tenant workloads and tenant cluster API servers continue running in connected clusters. | UI, Platform API, proxy access, lifecycle operations, and status updates are unavailable until Platform returns. | +| Agent connection is interrupted | Existing tenant clusters and workloads continue running in the connected cluster. | Platform cannot reconcile new changes for that connected cluster until the agent reconnects. | +| Tenant cluster API is unreachable | Platform and other tenant clusters continue operating. | Access, status, and lifecycle operations for that tenant cluster may fail until connectivity returns. | + +## Entry points + +Platform exposes several entry points through the API gateway. + +| Entry point | Used by | Purpose | +|---|---|---| +| Web UI | Browser users | Manage projects, tenant clusters, users, templates, connected clusters, and settings. | +| Platform API | UI, CLI, integrations, automation | Manage Platform resources such as projects, clusters, templates, users, and tenant cluster instances. | +| CLI | Operators and automation | Calls the Platform API for login, create, connect, inspect, and lifecycle commands. | +| Management Kubernetes API | CLI and Kubernetes clients | Proxies authenticated requests to Platform management resources under `/kubernetes/management`. | +| Connected cluster proxy | CLI and UI workflows | Proxies authenticated requests to a connected cluster under `/kubernetes/cluster/`. | +| Project resource proxy | Tenant cluster and space access | Proxies project-scoped requests under `/kubernetes/project//virtualcluster/` or `/kubernetes/project//space/`. | + +These routes let users work with Platform and tenant resources. Users do not receive credentials for the connected cluster itself. Platform authenticates the request and checks access. It then applies impersonation and forwards the request to the target API server. + +
+ +
Platform API gateway request paths
+
+ +## Project lifecycle + +Projects are the primary policy boundary in Platform. A Project groups tenant clusters, spaces, secrets, templates, quotas, and integrations. It also groups the users or teams who can access them. + +When a project is created, Platform reconciles the project into a project namespace in the management plane. That namespace holds tenant cluster instances and project secrets. Platform also reconciles project role bindings, access rules, quotas, integrations, and metadata. That metadata ties the namespace back to the project. + +Project namespaces are internal Platform namespaces. They are different from namespaces that tenant users create inside a tenant cluster. + +When a project changes, Platform updates the dependent resources. When a project is deleted, finalizers give Platform time to clean up project integrations and dependent resources before removing the project namespace. + +## Tenant resource lifecycle + +Most tenant resources follow the same pattern: + +1. A user, CLI command, integration, or GitOps workflow creates or updates a Platform API resource. +2. Platform validates the request against project membership, allowed clusters, allowed templates, quotas, and policy. +3. Platform reconciles the desired state into the selected connected cluster through the agent or proxy path. +4. The connected cluster reports status back to Platform. +5. Platform updates the resource status and displays it in the UI and API. + +For tenant clusters, the central resource is VirtualClusterInstance. A Platform-managed tenant cluster uses this resource as its desired state. It covers provisioning, configuration updates, upgrades, access, sleep behavior, and wake behavior. It also covers Argo CD registration and cleanup. An [externally deployed tenant cluster](../understand/externally-vs-platform-deployed.mdx) can also be registered with Platform. Its lifecycle stays owned by the external tool that created it. + +
+ +
Tenant resource lifecycle
+
+ +## Tenant cluster runtime + +Platform decides where and how a tenant cluster should be deployed, but vCluster runs the tenant cluster itself. + +During creation, Platform combines project policy, the selected VirtualClusterTemplate, user-provided parameters, and the selected connected cluster. It then installs or updates the vCluster Helm release in the target namespace. By default, that release creates the vCluster control plane StatefulSet. After that point, the vCluster runtime owns the Kubernetes control plane behavior. + +That runtime includes: + +- The tenant API server. +- The syncer. +- The data store. +- CoreDNS. +- The worker node model. +- Resource synchronization. + +Use Platform documentation for fleet lifecycle questions: + +- Who can create or access a tenant cluster. +- Which clusters and templates a project can use. +- How Platform manages create, update, upgrade, sleep, wake, automatic deletion, and access. +- How Platform provisions private nodes through node providers and node claims. + +Use the [vCluster architecture](/docs/vcluster/introduction/architecture) for runtime questions: + +- What runs inside the tenant cluster control plane. +- How the syncer works. +- How shared nodes and private nodes differ. +- How tenant cluster networking behaves. +- How vCluster Standalone and vind differ from Kubernetes hosted tenant clusters. + +## Network paths + +Platform supports multiple network paths depending on what is being accessed and how your environment is connected. + +
+ +
Network paths to connected cluster and tenant cluster APIs
+
+ +### Direct endpoint + +A tenant cluster can expose a direct Kubernetes API endpoint. In this model, the user's kubeconfig points directly to the tenant cluster endpoint. Platform still controls identity, access, and lifecycle. Steady state `kubectl` traffic can go directly to the tenant cluster API server. + +Use direct endpoints when tenant cluster API servers are reachable from users or automation and you want the shortest request path. + +### Platform proxy + +Platform can proxy Kubernetes API requests through its API gateway. Users authenticate to Platform. Platform checks project and tenant cluster access. The gateway forwards the request to the connected cluster or tenant cluster API server. + +Use the proxy path when users should not receive connected cluster credentials. This path also works when the target cluster is only reachable from Platform or the agent. It also lets Platform centralize access checks and audit records. + +### Tailscale network path + +Platform also uses a Tailscale network path for environments where direct connectivity is unavailable or unreliable. Platform coordinates network peers and can relay traffic through DERP when peers cannot connect directly. + +This path is useful when connected clusters, tenant clusters, or users are behind NAT, firewall rules, or private networks. The agent and Platform establish the network relationship. DERP provides a relay path when peer-to-peer traffic cannot be established. + +For troubleshooting this path, see [tsnet connectivity](../troubleshoot/tsnet-connectivity.mdx). For narrower communication concepts, see [vCluster Platform communication](../understand/platform_communication.mdx). + +## Further reading + +- [Connected clusters](../understand/what-are-clusters.mdx) +- [Projects](../understand/what-are-projects.mdx) +- [vCluster architecture](/docs/vcluster/introduction/architecture) diff --git a/platform/introduction/platform_intro.mdx b/platform/introduction/platform_intro.mdx index 69e29e0c52..7e408d6222 100644 --- a/platform/introduction/platform_intro.mdx +++ b/platform/introduction/platform_intro.mdx @@ -26,6 +26,8 @@ vCluster creates and runs tenant clusters. Platform manages the fleet. The relat Platform installs into a Kubernetes cluster and connects to other clusters in your environment. Those connected clusters become the Control Plane Clusters where tenant cluster control planes run. Platform doesn't replace those clusters. It manages what runs inside them. +[Understand the Platform architecture →](./architecture.mdx) + ## Projects Projects are the primary organizational unit in Platform. Each project is a policy boundary that groups tenant clusters and the users or teams who access them. diff --git a/platform/understand/platform_communication.mdx b/platform/understand/platform_communication.mdx index e0da020d60..36a64c718a 100644 --- a/platform/understand/platform_communication.mdx +++ b/platform/understand/platform_communication.mdx @@ -8,6 +8,8 @@ sidebar_label: What is vCluster-Platform Communication Several background processes run when creating a vCluster that enable communication with the platform. +For the full management plane, connected cluster, lifecycle, and network path overview, see [Platform architecture](../introduction/architecture.mdx). + ## Components in vCluster-platform communication ### The platform @@ -42,4 +44,3 @@ A bi-directional VPN tunnel then establishes secure communication between the pl ## Platform configuration Administrators can configure the endpoint and access key for the platform using Helm values. - diff --git a/platform/understand/what-are-clusters.mdx b/platform/understand/what-are-clusters.mdx index 204308aa36..3fb1120d3a 100644 --- a/platform/understand/what-are-clusters.mdx +++ b/platform/understand/what-are-clusters.mdx @@ -33,3 +33,5 @@ Platform itself runs on a Kubernetes cluster. That cluster is automatically conn The agent maintains a persistent outbound connection to the Platform API server. If connectivity is lost, existing tenant clusters continue running without interruption. Platform resumes full management once the connection is restored. [Connect a cluster →](../administer/clusters/connect-cluster.mdx) + +[Platform architecture →](../introduction/architecture.mdx) diff --git a/platform/understand/what-are-projects.mdx b/platform/understand/what-are-projects.mdx index 480cc5b601..9eaf919629 100644 --- a/platform/understand/what-are-projects.mdx +++ b/platform/understand/what-are-projects.mdx @@ -43,3 +43,5 @@ Projects can store secrets that are shared across resources within the project. Projects support integrations with external tools including ArgoCD and Rancher, allowing you to connect tenant cluster lifecycle management with your existing GitOps or platform tooling. [View integrations →](../integrations/argocd/overview.mdx) + +[Platform architecture →](../introduction/architecture.mdx) diff --git a/static/media/platform/diagrams/platform-architecture-overview.svg b/static/media/platform/diagrams/platform-architecture-overview.svg new file mode 100644 index 0000000000..a3648e472c --- /dev/null +++ b/static/media/platform/diagrams/platform-architecture-overview.svg @@ -0,0 +1,71 @@ + + + + + + + + + + + + Users + UI, CLI, API + + + vCluster Platform + Management plane + + + Web UI + Browser + + + Gateway + Auth + + + API + Resources + + + Controllers + Reconcile + + + Backing store + CRDs or database + + + Connected Cluster + + Agent + + Tenant + Namespaces, RBAC, Helm releases + + + Connected Cluster + + Agent + + Tenant + + + requests + + + + + + + + + reconcile + reconcile + diff --git a/static/media/platform/diagrams/platform-entry-points.svg b/static/media/platform/diagrams/platform-entry-points.svg new file mode 100644 index 0000000000..eea50f60e2 --- /dev/null +++ b/static/media/platform/diagrams/platform-entry-points.svg @@ -0,0 +1,59 @@ + + + + + + + + + + + + Web UI + Browser + + + CLI + Operators + + + Automation + Integrations + + + API gateway + + Authenticate + + Check access + + Impersonate + + + Management API + Platform resources + + + Connected cluster API + Cluster-scoped requests + + + Tenant cluster API + Project-scoped requests + + + + + + + + + + request + forwarded request + diff --git a/static/media/platform/diagrams/platform-network-paths.svg b/static/media/platform/diagrams/platform-network-paths.svg new file mode 100644 index 0000000000..34b5f59ad1 --- /dev/null +++ b/static/media/platform/diagrams/platform-network-paths.svg @@ -0,0 +1,58 @@ + + + + + + + + + + + + + + + User or automation + kubectl, UI, CLI + + + Platform gateway + Proxy and audit + + + Connected cluster API + Cluster proxy target + + + Tenant cluster API + Direct or proxied + + + Platform or agent peer + Tailscale path + + + DERP relay + + + direct endpoint + + + Platform proxy + + + tenant proxy + + + + + Tailscale path + + + relay fallback + diff --git a/static/media/platform/diagrams/platform-tenant-lifecycle.svg b/static/media/platform/diagrams/platform-tenant-lifecycle.svg new file mode 100644 index 0000000000..bd577699d2 --- /dev/null +++ b/static/media/platform/diagrams/platform-tenant-lifecycle.svg @@ -0,0 +1,50 @@ + + + + + + + + + + + + Request + User or GitOps + + + API resource + Desired state + + + Policy check + Project rules + + + Reconcile + Platform + + + Connected cluster + + Platform agent + + vCluster runtime + + + + + + + + status returns to the Platform API resource + + create + validate + apply + From 78aa9c022c696b502f2352eb1a3482525869b147 Mon Sep 17 00:00:00 2001 From: Daryl White Date: Thu, 11 Jun 2026 14:47:08 -0400 Subject: [PATCH 2/8] docs(platform): move failure behavior section to end of architecture page Co-Authored-By: Claude Sonnet 4.6 --- platform/introduction/architecture.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/platform/introduction/architecture.mdx b/platform/introduction/architecture.mdx index 4ba8e6bfe2..25c3da2401 100644 --- a/platform/introduction/architecture.mdx +++ b/platform/introduction/architecture.mdx @@ -52,14 +52,6 @@ The agent handles work that must happen inside the connected cluster: The agent uses outbound connectivity to Platform. Connected clusters do not need inbound access from Platform for the basic management channel. If the connection to Platform is interrupted, existing tenant clusters continue operating. Platform proxy access and lifecycle operations resume once the connection is restored. -## Failure behavior - -| Condition | What continues | What is affected | -|---|---|---| -| Platform is unavailable | Existing tenant workloads and tenant cluster API servers continue running in connected clusters. | UI, Platform API, proxy access, lifecycle operations, and status updates are unavailable until Platform returns. | -| Agent connection is interrupted | Existing tenant clusters and workloads continue running in the connected cluster. | Platform cannot reconcile new changes for that connected cluster until the agent reconnects. | -| Tenant cluster API is unreachable | Platform and other tenant clusters continue operating. | Access, status, and lifecycle operations for that tenant cluster may fail until connectivity returns. | - ## Entry points Platform exposes several entry points through the API gateway. @@ -166,6 +158,14 @@ This path is useful when connected clusters, tenant clusters, or users are behin For troubleshooting this path, see [tsnet connectivity](../troubleshoot/tsnet-connectivity.mdx). For narrower communication concepts, see [vCluster Platform communication](../understand/platform_communication.mdx). +## Failure behavior + +| Condition | What continues | What is affected | +|---|---|---| +| Platform is unavailable | Existing tenant workloads and tenant cluster API servers continue running in connected clusters. | UI, Platform API, proxy access, lifecycle operations, and status updates are unavailable until Platform returns. | +| Agent connection is interrupted | Existing tenant clusters and workloads continue running in the connected cluster. | Platform cannot reconcile new changes for that connected cluster until the agent reconnects. | +| Tenant cluster API is unreachable | Platform and other tenant clusters continue operating. | Access, status, and lifecycle operations for that tenant cluster may fail until connectivity returns. | + ## Further reading - [Connected clusters](../understand/what-are-clusters.mdx) From 513155b7a481b027d054059339f7412ce1fd248b Mon Sep 17 00:00:00 2001 From: Daryl White Date: Thu, 11 Jun 2026 19:22:51 -0400 Subject: [PATCH 3/8] docs(platform): address PR and product review feedback on architecture page - name vcluster-platform namespace - reorder management plane bullets gateway-first - rename tenant resource lifecycle to project resource lifecycle - update lifecycle step 3 wording per reviewer suggestion - add NodeProvider/NodeClaim note to project resource lifecycle - collapse tenant cluster runtime section to a single pointer to vcluster architecture - clarify backing store prose and link to external database docs - fix svg backing store label from "CRDs or database" to "Custom resources" Co-Authored-By: Claude Sonnet 4.6 --- platform/introduction/architecture.mdx | 40 +++++-------------- .../platform-architecture-overview.svg | 2 +- 2 files changed, 11 insertions(+), 31 deletions(-) diff --git a/platform/introduction/architecture.mdx b/platform/introduction/architecture.mdx index 25c3da2401..e29a96196f 100644 --- a/platform/introduction/architecture.mdx +++ b/platform/introduction/architecture.mdx @@ -22,17 +22,17 @@ Platform does not replace vCluster. Platform manages projects, users, templates, ## Management plane -The Platform management plane runs as the `vcluster-platform` Helm chart. A standard installation deploys these components into the Platform namespace. +The Platform management plane runs as the `vcluster-platform` Helm chart. A standard installation deploys these components into the `vcluster-platform` namespace. The management plane is responsible for: -- **Platform manager**. Runs the controllers that reconcile Platform resources. - **API gateway**. Serves authenticated UI, CLI, integration, and automation requests. - **Web UI**. Provides the browser interface for the Platform API. It runs as part of the management API process, not as a separate deployment. - **Management API**. Serves resources such as Project, Cluster, VirtualClusterInstance, VirtualClusterTemplate, AccessKey, NodeProvider, and NodeClaim. +- **Platform manager**. Runs the controllers that reconcile Platform resources. - **Operational services**. Coordinate audit events, metrics, cost data, sleep and wake behavior, snapshots, backups, and configured integrations. -By default, Platform stores management resources as Kubernetes custom resources in the cluster where Platform runs. High-availability and multi-region deployments can configure an external database instead of the management cluster's own etcd. Platform availability depends on the management plane and its backing datastore. +By default, Platform stores management resources as Kubernetes custom resources in the management cluster. High-availability and multi-region deployments can configure an [external relational database](../administer/clusters/advanced/external-database/external-database.mdx) as the backing store instead. Platform availability depends on the management plane and its backing datastore. Platform follows the Kubernetes controller model. Users and automation create or update API resources. Controllers compare those resources with the actual state of connected clusters. They then create, update, or clean up dependent resources. @@ -82,18 +82,20 @@ Project namespaces are internal Platform namespaces. They are different from nam When a project changes, Platform updates the dependent resources. When a project is deleted, finalizers give Platform time to clean up project integrations and dependent resources before removing the project namespace. -## Tenant resource lifecycle +## Project resource lifecycle -Most tenant resources follow the same pattern: +Most project resources follow the same pattern: 1. A user, CLI command, integration, or GitOps workflow creates or updates a Platform API resource. 2. Platform validates the request against project membership, allowed clusters, allowed templates, quotas, and policy. -3. Platform reconciles the desired state into the selected connected cluster through the agent or proxy path. +3. Connected cluster agents reconcile the desired state to cluster-side state. 4. The connected cluster reports status back to Platform. 5. Platform updates the resource status and displays it in the UI and API. For tenant clusters, the central resource is VirtualClusterInstance. A Platform-managed tenant cluster uses this resource as its desired state. It covers provisioning, configuration updates, upgrades, access, sleep behavior, and wake behavior. It also covers Argo CD registration and cleanup. An [externally deployed tenant cluster](../understand/externally-vs-platform-deployed.mdx) can also be registered with Platform. Its lifecycle stays owned by the external tool that created it. +Platform also manages supporting resources within a project. NodeProvider and NodeClaim resources handle private node provisioning and lifecycle. These resources follow the same lifecycle pattern as other project resources. +
Tenant resource lifecycle
@@ -103,31 +105,9 @@ For tenant clusters, the central resource is VirtualClusterInstance. A Platform- Platform decides where and how a tenant cluster should be deployed, but vCluster runs the tenant cluster itself. -During creation, Platform combines project policy, the selected VirtualClusterTemplate, user-provided parameters, and the selected connected cluster. It then installs or updates the vCluster Helm release in the target namespace. By default, that release creates the vCluster control plane StatefulSet. After that point, the vCluster runtime owns the Kubernetes control plane behavior. - -That runtime includes: - -- The tenant API server. -- The syncer. -- The data store. -- CoreDNS. -- The worker node model. -- Resource synchronization. - -Use Platform documentation for fleet lifecycle questions: - -- Who can create or access a tenant cluster. -- Which clusters and templates a project can use. -- How Platform manages create, update, upgrade, sleep, wake, automatic deletion, and access. -- How Platform provisions private nodes through node providers and node claims. - -Use the [vCluster architecture](/docs/vcluster/introduction/architecture) for runtime questions: +During creation, Platform combines project policy, the selected VirtualClusterTemplate, user-provided parameters, and the selected connected cluster. It then installs or updates the vCluster Helm release in the target namespace. After that point, the vCluster runtime owns the Kubernetes control plane behavior. -- What runs inside the tenant cluster control plane. -- How the syncer works. -- How shared nodes and private nodes differ. -- How tenant cluster networking behaves. -- How vCluster Standalone and vind differ from Kubernetes hosted tenant clusters. +For the API server, syncer, data store, CoreDNS, networking, and worker node models, see the [vCluster architecture](/docs/vcluster/introduction/architecture). ## Network paths diff --git a/static/media/platform/diagrams/platform-architecture-overview.svg b/static/media/platform/diagrams/platform-architecture-overview.svg index a3648e472c..3d15492ef6 100644 --- a/static/media/platform/diagrams/platform-architecture-overview.svg +++ b/static/media/platform/diagrams/platform-architecture-overview.svg @@ -39,7 +39,7 @@ Backing store - CRDs or database + Custom resources Connected Cluster From 0c1eb01ead8e074fac33b8229f1b74b6a26a7dcc Mon Sep 17 00:00:00 2001 From: Daryl White Date: Thu, 11 Jun 2026 20:01:22 -0400 Subject: [PATCH 4/8] docs(platform): restructure architecture page for progressive disclosure reorder sections so the page teaches from outside in: management plane, connected clusters, entry points, projects, resource lifecycle, network paths, failure behavior. merge the two lifecycle sections into one, remove the defensive vCluster disclaimer from the intro, add plain-language bridge sentences to orient new readers before technical detail arrives, and move the lifecycle diagram to sit immediately after the numbered pattern. Closes DOC-1488 Co-Authored-By: Claude Sonnet 4.6 --- platform/introduction/architecture.mdx | 34 +++++++++++--------------- 1 file changed, 14 insertions(+), 20 deletions(-) diff --git a/platform/introduction/architecture.mdx b/platform/introduction/architecture.mdx index e29a96196f..3c55c4a834 100644 --- a/platform/introduction/architecture.mdx +++ b/platform/introduction/architecture.mdx @@ -11,9 +11,9 @@ import PlatformEntryPoints from '@site/static/media/platform/diagrams/platform-e import PlatformTenantLifecycle from '@site/static/media/platform/diagrams/platform-tenant-lifecycle.svg'; import PlatformNetworkPaths from '@site/static/media/platform/diagrams/platform-network-paths.svg'; -vCluster Platform is the management plane for your tenant cluster fleet. It runs in Kubernetes and exposes UI, CLI, and API entry points. It also reconciles Platform resources into connected Control Plane Clusters. +vCluster Platform is the management plane for your tenant cluster fleet. It runs in Kubernetes and exposes UI, CLI, and API entry points. It reconciles Platform resources into connected control plane clusters. -Platform does not replace vCluster. Platform manages projects, users, templates, connected clusters, access, lifecycle automation, and node provisioning. vCluster remains the runtime that creates and runs each tenant cluster control plane. For vCluster internals, see the [vCluster architecture](/docs/vcluster/introduction/architecture). +Platform is where admins define projects, specify who can create tenant clusters, and set which templates and policies apply.
@@ -22,7 +22,7 @@ Platform does not replace vCluster. Platform manages projects, users, templates, ## Management plane -The Platform management plane runs as the `vcluster-platform` Helm chart. A standard installation deploys these components into the `vcluster-platform` namespace. +The management plane is Platform's central control point. It stores desired state for all Platform resources and drives reconciliation into connected clusters. It runs as the `vcluster-platform` Helm chart, deployed into the `vcluster-platform` namespace. The management plane is responsible for: @@ -54,7 +54,7 @@ The agent uses outbound connectivity to Platform. Connected clusters do not need ## Entry points -Platform exposes several entry points through the API gateway. +Most users enter through the UI or CLI. Internally, those requests pass through the same API gateway and are routed to the right API. | Entry point | Used by | Purpose | |---|---|---| @@ -72,19 +72,17 @@ These routes let users work with Platform and tenant resources. Users do not rec
Platform API gateway request paths
-## Project lifecycle +## Projects -Projects are the primary policy boundary in Platform. A Project groups tenant clusters, spaces, secrets, templates, quotas, and integrations. It also groups the users or teams who can access them. +Projects are the primary policy boundary in Platform. A project groups tenant clusters, spaces, secrets, templates, quotas, and integrations. It also groups the users or teams who can access them. -When a project is created, Platform reconciles the project into a project namespace in the management plane. That namespace holds tenant cluster instances and project secrets. Platform also reconciles project role bindings, access rules, quotas, integrations, and metadata. That metadata ties the namespace back to the project. +Platform represents each project as a namespace in the management plane. That namespace holds tenant cluster instances and project secrets, along with reconciled role bindings, access rules, quotas, integrations, and metadata. Project namespaces are internal Platform namespaces. They are different from namespaces that tenant users create inside a tenant cluster. -When a project changes, Platform updates the dependent resources. When a project is deleted, finalizers give Platform time to clean up project integrations and dependent resources before removing the project namespace. +## Resource lifecycle -## Project resource lifecycle - -Most project resources follow the same pattern: +Most Platform resources follow the same reconciliation pattern: 1. A user, CLI command, integration, or GitOps workflow creates or updates a Platform API resource. 2. Platform validates the request against project membership, allowed clusters, allowed templates, quotas, and policy. @@ -92,20 +90,16 @@ Most project resources follow the same pattern: 4. The connected cluster reports status back to Platform. 5. Platform updates the resource status and displays it in the UI and API. -For tenant clusters, the central resource is VirtualClusterInstance. A Platform-managed tenant cluster uses this resource as its desired state. It covers provisioning, configuration updates, upgrades, access, sleep behavior, and wake behavior. It also covers Argo CD registration and cleanup. An [externally deployed tenant cluster](../understand/externally-vs-platform-deployed.mdx) can also be registered with Platform. Its lifecycle stays owned by the external tool that created it. - -Platform also manages supporting resources within a project. NodeProvider and NodeClaim resources handle private node provisioning and lifecycle. These resources follow the same lifecycle pattern as other project resources. -
Tenant resource lifecycle
-## Tenant cluster runtime +For tenant clusters, the central resource is VirtualClusterInstance. A Platform-managed tenant cluster uses this resource as its desired state. It covers provisioning, configuration updates, upgrades, access, sleep behavior, and wake behavior. It also covers Argo CD registration and cleanup. An [externally deployed tenant cluster](../understand/externally-vs-platform-deployed.mdx) can also be registered with Platform. Its lifecycle stays owned by the external tool that created it. -Platform decides where and how a tenant cluster should be deployed, but vCluster runs the tenant cluster itself. +Platform also manages supporting resources within a project. NodeProvider and NodeClaim resources handle private node provisioning and lifecycle. These resources follow the same lifecycle pattern as other project resources. -During creation, Platform combines project policy, the selected VirtualClusterTemplate, user-provided parameters, and the selected connected cluster. It then installs or updates the vCluster Helm release in the target namespace. After that point, the vCluster runtime owns the Kubernetes control plane behavior. +Platform decides where and how a tenant cluster should be deployed, but vCluster runs the tenant cluster itself. During creation, Platform combines project policy, the selected VirtualClusterTemplate, user-provided parameters, and the selected connected cluster. It then installs or updates the vCluster Helm release in the target namespace. After that point, the vCluster runtime owns the Kubernetes control plane behavior. For the API server, syncer, data store, CoreDNS, networking, and worker node models, see the [vCluster architecture](/docs/vcluster/introduction/architecture). @@ -128,11 +122,11 @@ Use direct endpoints when tenant cluster API servers are reachable from users or Platform can proxy Kubernetes API requests through its API gateway. Users authenticate to Platform. Platform checks project and tenant cluster access. The gateway forwards the request to the connected cluster or tenant cluster API server. -Use the proxy path when users should not receive connected cluster credentials. This path also works when the target cluster is only reachable from Platform or the agent. It also lets Platform centralize access checks and audit records. +Use the proxy path when users should not receive connected cluster credentials. This path also works when the target cluster is only reachable from Platform or the agent. It lets Platform centralize access checks and audit records. ### Tailscale network path -Platform also uses a Tailscale network path for environments where direct connectivity is unavailable or unreliable. Platform coordinates network peers and can relay traffic through DERP when peers cannot connect directly. +Platform uses a Tailscale network path for environments where direct connectivity is unavailable or unreliable. Platform coordinates network peers and can relay traffic through DERP when peers cannot connect directly. This path is useful when connected clusters, tenant clusters, or users are behind NAT, firewall rules, or private networks. The agent and Platform establish the network relationship. DERP provides a relay path when peer-to-peer traffic cannot be established. From 19d995766b38690334466241dcaef7b7f10a9f1b Mon Sep 17 00:00:00 2001 From: Daryl White Date: Thu, 11 Jun 2026 20:23:46 -0400 Subject: [PATCH 5/8] docs(platform): refine architecture page structure and diagrams add a new intro-level overview svg with simpler abstraction for the page opener, move the detailed management-plane overview diagram to after the connected clusters section where it synthesizes both preceding sections, expand the local cluster explanation with its ui label and a dedicated paragraph, update the writer skill with progressive disclosure guidance for explanation and concept pages. Co-Authored-By: Claude Sonnet 4.6 --- .claude/skills/vcluster-docs-writer/SKILL.md | 26 ++++++++- platform/introduction/architecture.mdx | 14 ++++- .../diagrams/platform-intro-overview.svg | 57 +++++++++++++++++++ 3 files changed, 93 insertions(+), 4 deletions(-) create mode 100644 static/media/platform/diagrams/platform-intro-overview.svg diff --git a/.claude/skills/vcluster-docs-writer/SKILL.md b/.claude/skills/vcluster-docs-writer/SKILL.md index 2790cd43db..1e040186dc 100644 --- a/.claude/skills/vcluster-docs-writer/SKILL.md +++ b/.claude/skills/vcluster-docs-writer/SKILL.md @@ -281,7 +281,31 @@ import Partial from '@site/docs/_partials/example.mdx'; See `references/partials-guide.md` for complete patterns and troubleshooting. -## Critical Rules +## Concept and Explanation Pages + +Explanation pages (architecture, overview, "what is X") should build the reader's mental model from the outside in. Each section should answer the question a reader would naturally ask next, given what they just learned. + +**The progressive disclosure sequence:** + +1. What it IS — plain-language definition before any technical framing +2. What it contains — structural components and their roles +3. How the parts connect — topology, agents, registrations +4. How you interact with it — entry points, access patterns +5. How work flows through it — lifecycle, reconciliation, request paths +6. Operational detail — network paths, failure behavior, edge cases + +**Rules:** + +- Do not introduce a term before the concept behind it is established. Glossary links help but do not substitute for a clear conceptual foundation. +- Add a plain-language "why this matters" sentence before technical component lists. Readers need to know what the list is for before they can absorb its items. +- Place diagrams immediately after the content they illustrate — not after examples that build on the pattern. A diagram should reinforce what was just described, not summarize what follows. +- Do not open explanation pages with defensive disclaimers ("X does not replace Y"). Put the relationship between products where it naturally belongs in the flow — usually at the handoff point between sections. +- Merge sections with confusingly similar names. Adjacent sections covering the same concept from slightly different angles (e.g. "Project lifecycle" and "Project resource lifecycle") signal a structural problem, not a content problem. +- Separate "what it is" sections from "how it works" sections. A section covering both structure and behavior is usually two sections collapsed into one. + +**Check the flow by asking:** can a reader who skims only the section headings reconstruct the mental model? If the heading sequence reads like a component inventory rather than a conceptual arc, restructure. + + ### Never-Do - ⚠️ **NEVER modify versioned docs** unless explicitly requested diff --git a/platform/introduction/architecture.mdx b/platform/introduction/architecture.mdx index 3c55c4a834..dbf8b429ac 100644 --- a/platform/introduction/architecture.mdx +++ b/platform/introduction/architecture.mdx @@ -6,6 +6,7 @@ description: Understand the vCluster Platform management plane, connected cluste --- import GlossaryTerm from '@site/src/components/GlossaryTerm'; +import PlatformIntroOverview from '@site/static/media/platform/diagrams/platform-intro-overview.svg'; import PlatformArchitectureOverview from '@site/static/media/platform/diagrams/platform-architecture-overview.svg'; import PlatformEntryPoints from '@site/static/media/platform/diagrams/platform-entry-points.svg'; import PlatformTenantLifecycle from '@site/static/media/platform/diagrams/platform-tenant-lifecycle.svg'; @@ -16,8 +17,8 @@ vCluster Platform is the management plane for your -
Platform management plane and connected clusters
+ +
Platform connects admins and automation to connected clusters and tenant clusters
## Management plane @@ -38,7 +39,9 @@ Platform follows the Kubernetes controller model. Users and automation create or ## Connected clusters and agents -A connected cluster is a Kubernetes cluster registered with Platform. Connected clusters are where tenant cluster control planes and project workloads run. Platform automatically registers the cluster where it is installed as the local cluster. Smaller deployments can run tenant clusters there too. +A connected cluster is a Kubernetes cluster registered with Platform. Connected clusters are where tenant cluster control planes and project workloads run. Platform automatically registers the cluster where it is installed as the local cluster. In the UI, this appears as **Local cluster** in the connected cluster list. + +The local cluster can also run tenant cluster control planes and project workloads. This lets smaller deployments use the same cluster for both the management plane and tenant resources. Connecting a cluster installs the same Platform chart in `agentOnly` mode. In this mode, the chart starts the Platform image as the agent. It does not start the full management plane. The agent runs in the connected cluster and authenticates with a cluster access key. It keeps cluster-side state in sync with Platform. @@ -52,6 +55,11 @@ The agent handles work that must happen inside the connected cluster: The agent uses outbound connectivity to Platform. Connected clusters do not need inbound access from Platform for the basic management channel. If the connection to Platform is interrupted, existing tenant clusters continue operating. Platform proxy access and lifecycle operations resume once the connection is restored. +
+ +
Platform management plane and connected clusters
+
+ ## Entry points Most users enter through the UI or CLI. Internally, those requests pass through the same API gateway and are routed to the right API. diff --git a/static/media/platform/diagrams/platform-intro-overview.svg b/static/media/platform/diagrams/platform-intro-overview.svg new file mode 100644 index 0000000000..15f68c0ef8 --- /dev/null +++ b/static/media/platform/diagrams/platform-intro-overview.svg @@ -0,0 +1,57 @@ + + + + + + + + + + + + Admins and automation + UI, CLI, API, GitOps + + + vCluster Platform + Management plane + + Projects and access + + Templates and policies + + + Connected cluster + Workloads run here + + + Connected cluster + Workloads run here + + + + + Tenant clusters + vCluster runtime + + + + + Tenant clusters + vCluster runtime + + + intent + + + + reconcile + + + + From 938ec8ff62c02b1699bbe24e978a9fef4998830b Mon Sep 17 00:00:00 2001 From: Daryl White Date: Fri, 12 Jun 2026 13:18:36 -0400 Subject: [PATCH 6/8] docs(platform): split architecture into structural and behavioral pages Replaces the single architecture page with two focused pages: - architecture.mdx: structural introduction (what exists and how it fits together) - how-platform-works.mdx: behavioral page (controller model, lifecycle, network paths, failure) Fills gaps in understand pages: adds proxy path participation to what-are-clusters.mdx and project namespace model to what-are-projects.mdx. Closes DOC-1488 Co-Authored-By: Claude Sonnet 4.6 --- platform/introduction/architecture.mdx | 128 ++++--------------- platform/introduction/how-platform-works.mdx | 102 +++++++++++++++ platform/understand/what-are-clusters.mdx | 2 +- platform/understand/what-are-projects.mdx | 2 + 4 files changed, 129 insertions(+), 105 deletions(-) create mode 100644 platform/introduction/how-platform-works.mdx diff --git a/platform/introduction/architecture.mdx b/platform/introduction/architecture.mdx index dbf8b429ac..a1bba0749f 100644 --- a/platform/introduction/architecture.mdx +++ b/platform/introduction/architecture.mdx @@ -2,19 +2,17 @@ title: Architecture sidebar_label: Architecture sidebar_position: 3 -description: Understand the vCluster Platform management plane, connected cluster agents, resource lifecycle, and network paths. +description: The structural components of vCluster Platform and how they fit together. --- import GlossaryTerm from '@site/src/components/GlossaryTerm'; import PlatformIntroOverview from '@site/static/media/platform/diagrams/platform-intro-overview.svg'; import PlatformArchitectureOverview from '@site/static/media/platform/diagrams/platform-architecture-overview.svg'; import PlatformEntryPoints from '@site/static/media/platform/diagrams/platform-entry-points.svg'; -import PlatformTenantLifecycle from '@site/static/media/platform/diagrams/platform-tenant-lifecycle.svg'; -import PlatformNetworkPaths from '@site/static/media/platform/diagrams/platform-network-paths.svg'; vCluster Platform is the management plane for your tenant cluster fleet. It runs in Kubernetes and exposes UI, CLI, and API entry points. It reconciles Platform resources into connected control plane clusters. -Platform is where admins define projects, specify who can create tenant clusters, and set which templates and policies apply. +Platform is where admins define projects, specify who can create tenant clusters, and set which templates and policies apply. Platform controllers reconcile those decisions into connected clusters, where vCluster runs each tenant cluster control plane.
@@ -23,133 +21,55 @@ Platform is where admins define projects, specify who can create tenant clusters ## Management plane -The management plane is Platform's central control point. It stores desired state for all Platform resources and drives reconciliation into connected clusters. It runs as the `vcluster-platform` Helm chart, deployed into the `vcluster-platform` namespace. +The management plane runs as the `vcluster-platform` Helm chart, deployed into the `vcluster-platform` namespace. It is the source of truth for all Platform decisions. -The management plane is responsible for: +- **API gateway.** Authenticates all inbound requests and routes them to the right backend. +- **Web UI.** Browser interface for the Platform API, running as part of the management API process. +- **Management API.** Serves Platform resources: projects, clusters, VirtualClusterInstances, templates, users, and access keys. +- **Platform manager.** Controllers that reconcile Platform resources into connected clusters. +- **Operational services.** Audit, metrics, cost data, sleep and wake behavior, snapshots, and integrations. -- **API gateway**. Serves authenticated UI, CLI, integration, and automation requests. -- **Web UI**. Provides the browser interface for the Platform API. It runs as part of the management API process, not as a separate deployment. -- **Management API**. Serves resources such as Project, Cluster, VirtualClusterInstance, VirtualClusterTemplate, AccessKey, NodeProvider, and NodeClaim. -- **Platform manager**. Runs the controllers that reconcile Platform resources. -- **Operational services**. Coordinate audit events, metrics, cost data, sleep and wake behavior, snapshots, backups, and configured integrations. - -By default, Platform stores management resources as Kubernetes custom resources in the management cluster. High-availability and multi-region deployments can configure an [external relational database](../administer/clusters/advanced/external-database/external-database.mdx) as the backing store instead. Platform availability depends on the management plane and its backing datastore. - -Platform follows the Kubernetes controller model. Users and automation create or update API resources. Controllers compare those resources with the actual state of connected clusters. They then create, update, or clean up dependent resources. +Platform uses Kubernetes custom resources for all management state. The backing store is etcd by default. High-availability deployments can use an [external relational database](../administer/clusters/advanced/external-database/external-database.mdx) instead. ## Connected clusters and agents -A connected cluster is a Kubernetes cluster registered with Platform. Connected clusters are where tenant cluster control planes and project workloads run. Platform automatically registers the cluster where it is installed as the local cluster. In the UI, this appears as **Local cluster** in the connected cluster list. - -The local cluster can also run tenant cluster control planes and project workloads. This lets smaller deployments use the same cluster for both the management plane and tenant resources. - -Connecting a cluster installs the same Platform chart in `agentOnly` mode. In this mode, the chart starts the Platform image as the agent. It does not start the full management plane. The agent runs in the connected cluster and authenticates with a cluster access key. It keeps cluster-side state in sync with Platform. - -The agent handles work that must happen inside the connected cluster: +A connected cluster is a Kubernetes cluster registered with Platform. Tenant cluster control planes and project workloads run there. Connecting a cluster installs the Platform agent, which maintains an outbound connection to Platform and keeps cluster-side state in sync. -- Installing and updating cluster-side resources required by Platform. -- Creating namespaces, RBAC, Helm releases, and Kubernetes resources for tenant clusters and spaces. -- Reporting status, health, and resource data back to Platform. -- Participating in proxy paths when Platform forwards requests to connected cluster or tenant cluster APIs. -- Supporting sleep, wake, and lifecycle operations that depend on the cluster where the tenant resources run. - -The agent uses outbound connectivity to Platform. Connected clusters do not need inbound access from Platform for the basic management channel. If the connection to Platform is interrupted, existing tenant clusters continue operating. Platform proxy access and lifecycle operations resume once the connection is restored. +Platform automatically registers the cluster where it is installed as the local cluster. Smaller deployments can use it for both the management plane and tenant workloads.
Platform management plane and connected clusters
-## Entry points - -Most users enter through the UI or CLI. Internally, those requests pass through the same API gateway and are routed to the right API. - -| Entry point | Used by | Purpose | -|---|---|---| -| Web UI | Browser users | Manage projects, tenant clusters, users, templates, connected clusters, and settings. | -| Platform API | UI, CLI, integrations, automation | Manage Platform resources such as projects, clusters, templates, users, and tenant cluster instances. | -| CLI | Operators and automation | Calls the Platform API for login, create, connect, inspect, and lifecycle commands. | -| Management Kubernetes API | CLI and Kubernetes clients | Proxies authenticated requests to Platform management resources under `/kubernetes/management`. | -| Connected cluster proxy | CLI and UI workflows | Proxies authenticated requests to a connected cluster under `/kubernetes/cluster/`. | -| Project resource proxy | Tenant cluster and space access | Proxies project-scoped requests under `/kubernetes/project//virtualcluster/` or `/kubernetes/project//space/`. | - -These routes let users work with Platform and tenant resources. Users do not receive credentials for the connected cluster itself. Platform authenticates the request and checks access. It then applies impersonation and forwards the request to the target API server. - -
- -
Platform API gateway request paths
-
+[Dive deeper into connected clusters →](../understand/what-are-clusters.mdx) ## Projects -Projects are the primary policy boundary in Platform. A project groups tenant clusters, spaces, secrets, templates, quotas, and integrations. It also groups the users or teams who can access them. - -Platform represents each project as a namespace in the management plane. That namespace holds tenant cluster instances and project secrets, along with reconciled role bindings, access rules, quotas, integrations, and metadata. - -Project namespaces are internal Platform namespaces. They are different from namespaces that tenant users create inside a tenant cluster. - -## Resource lifecycle - -Most Platform resources follow the same reconciliation pattern: +A project is the primary policy boundary in Platform. It groups tenant clusters, spaces, templates, secrets, quotas, and integrations, and defines the users and teams who can access them. Each project specifies which connected clusters its members can deploy into, and which templates they can use. -1. A user, CLI command, integration, or GitOps workflow creates or updates a Platform API resource. -2. Platform validates the request against project membership, allowed clusters, allowed templates, quotas, and policy. -3. Connected cluster agents reconcile the desired state to cluster-side state. -4. The connected cluster reports status back to Platform. -5. Platform updates the resource status and displays it in the UI and API. +[Dive deeper into projects →](../understand/what-are-projects.mdx) -
- -
Tenant resource lifecycle
-
- -For tenant clusters, the central resource is VirtualClusterInstance. A Platform-managed tenant cluster uses this resource as its desired state. It covers provisioning, configuration updates, upgrades, access, sleep behavior, and wake behavior. It also covers Argo CD registration and cleanup. An [externally deployed tenant cluster](../understand/externally-vs-platform-deployed.mdx) can also be registered with Platform. Its lifecycle stays owned by the external tool that created it. - -Platform also manages supporting resources within a project. NodeProvider and NodeClaim resources handle private node provisioning and lifecycle. These resources follow the same lifecycle pattern as other project resources. - -Platform decides where and how a tenant cluster should be deployed, but vCluster runs the tenant cluster itself. During creation, Platform combines project policy, the selected VirtualClusterTemplate, user-provided parameters, and the selected connected cluster. It then installs or updates the vCluster Helm release in the target namespace. After that point, the vCluster runtime owns the Kubernetes control plane behavior. +## Access -For the API server, syncer, data store, CoreDNS, networking, and worker node models, see the [vCluster architecture](/docs/vcluster/introduction/architecture). +Most users enter through the UI or CLI. All requests pass through the API gateway, which authenticates each request and routes it to the right backend. -## Network paths +- **Web UI.** Browser interface for managing projects, tenant clusters, users, templates, and connected clusters. +- **CLI.** Calls the Platform API for login, create, connect, inspect, and lifecycle commands. +- **Automation.** Integrations, GitOps workflows, and scripts call the Platform API directly. -Platform supports multiple network paths depending on what is being accessed and how your environment is connected. +The gateway uses Kubernetes impersonation to forward requests. It presents the caller's verified identity to the target API without issuing direct cluster credentials.
- -
Network paths to connected cluster and tenant cluster APIs
+ +
Platform API gateway request paths
-### Direct endpoint - -A tenant cluster can expose a direct Kubernetes API endpoint. In this model, the user's kubeconfig points directly to the tenant cluster endpoint. Platform still controls identity, access, and lifecycle. Steady state `kubectl` traffic can go directly to the tenant cluster API server. - -Use direct endpoints when tenant cluster API servers are reachable from users or automation and you want the shortest request path. - -### Platform proxy - -Platform can proxy Kubernetes API requests through its API gateway. Users authenticate to Platform. Platform checks project and tenant cluster access. The gateway forwards the request to the connected cluster or tenant cluster API server. - -Use the proxy path when users should not receive connected cluster credentials. This path also works when the target cluster is only reachable from Platform or the agent. It lets Platform centralize access checks and audit records. - -### Tailscale network path - -Platform uses a Tailscale network path for environments where direct connectivity is unavailable or unreliable. Platform coordinates network peers and can relay traffic through DERP when peers cannot connect directly. - -This path is useful when connected clusters, tenant clusters, or users are behind NAT, firewall rules, or private networks. The agent and Platform establish the network relationship. DERP provides a relay path when peer-to-peer traffic cannot be established. - -For troubleshooting this path, see [tsnet connectivity](../troubleshoot/tsnet-connectivity.mdx). For narrower communication concepts, see [vCluster Platform communication](../understand/platform_communication.mdx). - -## Failure behavior - -| Condition | What continues | What is affected | -|---|---|---| -| Platform is unavailable | Existing tenant workloads and tenant cluster API servers continue running in connected clusters. | UI, Platform API, proxy access, lifecycle operations, and status updates are unavailable until Platform returns. | -| Agent connection is interrupted | Existing tenant clusters and workloads continue running in the connected cluster. | Platform cannot reconcile new changes for that connected cluster until the agent reconnects. | -| Tenant cluster API is unreachable | Platform and other tenant clusters continue operating. | Access, status, and lifecycle operations for that tenant cluster may fail until connectivity returns. | +[Dive deeper into entry points and proxy paths →](./how-platform-works.mdx#entry-points) ## Further reading +- [How Platform works](./how-platform-works.mdx) - [Connected clusters](../understand/what-are-clusters.mdx) - [Projects](../understand/what-are-projects.mdx) - [vCluster architecture](/docs/vcluster/introduction/architecture) diff --git a/platform/introduction/how-platform-works.mdx b/platform/introduction/how-platform-works.mdx new file mode 100644 index 0000000000..94178dc1d7 --- /dev/null +++ b/platform/introduction/how-platform-works.mdx @@ -0,0 +1,102 @@ +--- +title: How Platform works +sidebar_label: How Platform works +sidebar_position: 4 +description: How vCluster Platform reconciles resources, routes traffic, and behaves when components are unavailable. +--- + +import PlatformEntryPoints from '@site/static/media/platform/diagrams/platform-entry-points.svg'; +import PlatformTenantLifecycle from '@site/static/media/platform/diagrams/platform-tenant-lifecycle.svg'; +import PlatformNetworkPaths from '@site/static/media/platform/diagrams/platform-network-paths.svg'; + +Platform follows the Kubernetes controller model. Users and automation create or update API resources expressing desired state. Controllers in the management plane compare that state against connected clusters and reconcile the difference. The connected cluster agent applies changes locally and reports status back to Platform. vCluster then runs the tenant cluster control plane within the connected cluster. + +For the structural components, see [Platform architecture](./architecture.mdx). + +## Entry points + +All requests enter through the API gateway, which authenticates each request, checks access, applies impersonation, and forwards to the appropriate backend. Users do not receive credentials for connected clusters directly. + +| Entry point | Used by | Purpose | +|---|---|---| +| Web UI | Browser users | Manage projects, tenant clusters, users, templates, connected clusters, and settings. | +| Platform API | UI, CLI, integrations, automation | Manage Platform resources such as projects, clusters, templates, users, and tenant cluster instances. | +| CLI | Operators and automation | Calls the Platform API for login, create, connect, inspect, and lifecycle commands. | +| Management Kubernetes API | CLI and Kubernetes clients | Proxies authenticated requests to Platform management resources under `/kubernetes/management`. | +| Connected cluster proxy | CLI and UI workflows | Proxies authenticated requests to a connected cluster under `/kubernetes/cluster/`. | +| Project resource proxy | Tenant cluster and space access | Proxies project-scoped requests under `/kubernetes/project//virtualcluster/` or `/kubernetes/project//space/`. | + +
+ +
Platform API gateway request paths
+
+ +## Resource lifecycle + +When a user or automation creates or updates a Platform resource, it moves through a consistent path from request to deployed state: + +1. A user, CLI command, integration, or GitOps workflow submits a request. Platform creates or updates the API resource expressing desired state. +2. Platform validates the resource against project policy, allowed clusters, allowed templates, and quotas. +3. Platform controllers reconcile the desired state. The connected cluster agent applies changes locally, including namespaces, RBAC, and Helm releases. +4. The connected cluster reports status back to Platform. The resource status is updated and reflected in the UI and API. + +
+ +
Tenant resource lifecycle
+
+ +For tenant clusters, the central resource is VirtualClusterInstance. A Platform-managed tenant cluster uses this resource as its desired state. It covers provisioning, configuration updates, upgrades, access, sleep behavior, wake behavior, Argo CD registration, and cleanup. An [externally deployed tenant cluster](../understand/externally-vs-platform-deployed.mdx) can be registered with Platform without transferring lifecycle ownership to Platform. + +Platform manages supporting resources within a project. NodeProvider and NodeClaim resources handle private node provisioning and lifecycle. These resources follow the same lifecycle pattern as other project resources. + +## Tenant cluster runtime + +Platform decides where and how a tenant cluster should be deployed, but vCluster runs the tenant cluster itself. During creation, Platform combines project policy, the selected VirtualClusterTemplate, user-provided parameters, and the selected connected cluster. It then installs or updates the vCluster Helm release in the target namespace. After that point, the vCluster runtime owns the Kubernetes control plane behavior. + +For the API server, syncer, data store, CoreDNS, networking, and worker node models, see the [vCluster architecture](/docs/vcluster/introduction/architecture). + +## Network paths + +Platform supports multiple network paths depending on what is being accessed and how your environment is connected. + +
+ +
Network paths to connected cluster and tenant cluster APIs
+
+ +### Direct endpoint + +A tenant cluster can expose a direct Kubernetes API endpoint. In this model, the user's kubeconfig points directly to the tenant cluster endpoint. Platform still controls identity, access, and lifecycle. Steady state `kubectl` traffic can go directly to the tenant cluster API server. + +Use direct endpoints when tenant cluster API servers are reachable from users or automation and you want the shortest request path. + +### Platform proxy + +Platform can proxy Kubernetes API requests through its API gateway. Users authenticate to Platform. Platform checks project and tenant cluster access. The gateway forwards the request to the connected cluster or tenant cluster API server. + +Use the proxy path when users should not receive connected cluster credentials or when the target cluster is only reachable from Platform or the agent. It centralizes access checks and audit records. + +### Tailscale network path + +Platform uses a Tailscale network path for environments where direct connectivity is unavailable or unreliable. Platform coordinates network peers and can relay traffic through DERP when peers cannot connect directly. + +This path is useful when connected clusters, tenant clusters, or users are behind NAT, firewall rules, or private networks. The agent and Platform establish the network relationship. DERP provides a relay path when peer-to-peer traffic cannot be established. + +For troubleshooting this path, see [tsnet connectivity](../troubleshoot/tsnet-connectivity.mdx). For narrower communication concepts, see [vCluster Platform communication](../understand/platform_communication.mdx). + +## Failure behavior + +Platform, connected cluster agents, and tenant cluster control planes fail independently of each other. Existing workloads continue running in connected clusters even when management connectivity is lost. + +| Condition | What continues | What is affected | +|---|---|---| +| Platform is unavailable | Existing tenant workloads and tenant cluster API servers continue running in connected clusters. | UI, Platform API, proxy access, lifecycle operations, and status updates are unavailable until Platform returns. | +| Agent connection is interrupted | Existing tenant clusters and workloads continue running in the connected cluster. | Platform cannot reconcile new changes for that connected cluster until the agent reconnects. | +| Tenant cluster API is unreachable | Platform and other tenant clusters continue operating. | Access, status, and lifecycle operations for that tenant cluster may fail until connectivity returns. | + +## Further reading + +- [Platform architecture](./architecture.mdx) +- [Connected clusters](../understand/what-are-clusters.mdx) +- [Projects](../understand/what-are-projects.mdx) +- [vCluster architecture](/docs/vcluster/introduction/architecture) diff --git a/platform/understand/what-are-clusters.mdx b/platform/understand/what-are-clusters.mdx index 3fb1120d3a..545a20b1bf 100644 --- a/platform/understand/what-are-clusters.mdx +++ b/platform/understand/what-are-clusters.mdx @@ -8,7 +8,7 @@ A connected cluster is a Kubernetes cluster linked to vCluster Platform. It serv ## How connection works -Connecting a cluster installs the vCluster Platform agent on it. The agent provides the communication layer between Platform and that cluster: tenant cluster provisioning, access control enforcement, lifecycle operations, and health monitoring. It uses an outbound connection to Platform, so no inbound firewall rules are required on the cluster. +Connecting a cluster installs the vCluster Platform agent on it. The agent provides the communication layer between Platform and that cluster. It handles tenant cluster provisioning, access control enforcement, lifecycle operations, health monitoring, and proxy path forwarding when Platform routes requests to connected cluster or tenant cluster APIs. It uses an outbound connection to Platform, so no inbound firewall rules are required on the cluster. Once connected, the cluster appears in the Platform UI and can be assigned to projects. Members of those projects can then create tenant clusters and spaces within the cluster, scoped to their access level. diff --git a/platform/understand/what-are-projects.mdx b/platform/understand/what-are-projects.mdx index 9eaf919629..d2a28528a4 100644 --- a/platform/understand/what-are-projects.mdx +++ b/platform/understand/what-are-projects.mdx @@ -10,6 +10,8 @@ For AI cloud operators, projects map naturally to customer accounts: each custom {/* TODO: screenshot — Projects overview showing multiple projects with member count, tenant cluster count, and quota usage */} +Platform represents each project as a namespace in the management plane. That namespace holds tenant cluster instances and project secrets, along with reconciled role bindings, access rules, quotas, integrations, and metadata. Project namespaces are internal to Platform and are distinct from namespaces that tenant users create inside a tenant cluster. + ## Members Every project has members: the users and teams authorized to access it. Only members (and global admins) can see or interact with resources inside a project. Each member is assigned a role that defines what they can do within the project. From d03055ac43ba7d1e1356e628ae79330186bc83b9 Mon Sep 17 00:00:00 2001 From: Daryl White Date: Tue, 23 Jun 2026 08:23:19 -0400 Subject: [PATCH 7/8] docs(platform): add description front matter to what-are-projects Co-Authored-By: Claude Sonnet 4.6 --- platform/understand/what-are-projects.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/platform/understand/what-are-projects.mdx b/platform/understand/what-are-projects.mdx index e5471f1ebf..acdf51af21 100644 --- a/platform/understand/what-are-projects.mdx +++ b/platform/understand/what-are-projects.mdx @@ -2,6 +2,7 @@ title: What are Projects sidebar_label: What Are Projects sidebar_position: 1 +description: Projects are the primary organizational unit in vCluster Platform, grouping tenant clusters, spaces, and users under a shared policy boundary. --- import TenantClusterProjectFilter from '@site/static/media/platform/screenshots/tenant-cluster-management-dashboard-with-project-filter.png'; From 7b085b235db92dc1c94fa96fa3a01f2f9c7703b2 Mon Sep 17 00:00:00 2001 From: Daryl White Date: Mon, 29 Jun 2026 13:31:25 -0400 Subject: [PATCH 8/8] docs(platform): address review feedback on architecture pages - fix storage description in architecture.mdx: embedded db by default, kine for HA (not etcd) - rewrite direct endpoint section as regional and direct access endpoints - add GlossaryTerm import and wrap first tenant-cluster use in how-platform-works.mdx - remove link to platform_communication.mdx pending rewrite (DOC-1580) - add description frontmatter to what-are-clusters.mdx - update network paths aria-label to match renamed section - fix double blank line in vcluster-docs-writer SKILL.md - scope pr template hook to gh pr create commands only Co-Authored-By: Claude Sonnet 4.6 --- .claude/settings.json | 4 +--- .claude/skills/vcluster-docs-writer/SKILL.md | 2 -- platform/introduction/architecture.mdx | 2 +- platform/introduction/how-platform-works.mdx | 13 +++++++------ platform/understand/what-are-clusters.mdx | 1 + 5 files changed, 10 insertions(+), 12 deletions(-) diff --git a/.claude/settings.json b/.claude/settings.json index 6ff9b424f5..2940aeface 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -6,9 +6,7 @@ "hooks": [ { "type": "command", - "if": "Bash(gh pr create *)", - "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"additionalContext\":\"Read .github/pull_request_template.md and use its exact structure as the PR body before continuing.\"}}'", - "statusMessage": "Checking PR template..." + "command": "cmd=$(jq -r '.tool_input.command // \"\"'); case \"$cmd\" in \"gh pr create \"*) echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"additionalContext\":\"Read .github/pull_request_template.md and use its exact structure as the PR body before continuing.\"}}';; esac" } ] } diff --git a/.claude/skills/vcluster-docs-writer/SKILL.md b/.claude/skills/vcluster-docs-writer/SKILL.md index 1e040186dc..ce989cfe90 100644 --- a/.claude/skills/vcluster-docs-writer/SKILL.md +++ b/.claude/skills/vcluster-docs-writer/SKILL.md @@ -305,8 +305,6 @@ Explanation pages (architecture, overview, "what is X") should build the reader' **Check the flow by asking:** can a reader who skims only the section headings reconstruct the mental model? If the heading sequence reads like a component inventory rather than a conceptual arc, restructure. - - ### Never-Do - ⚠️ **NEVER modify versioned docs** unless explicitly requested - ⚠️ **NEVER run `npm run build`** (user runs when needed) diff --git a/platform/introduction/architecture.mdx b/platform/introduction/architecture.mdx index a1bba0749f..f08200a915 100644 --- a/platform/introduction/architecture.mdx +++ b/platform/introduction/architecture.mdx @@ -29,7 +29,7 @@ The management plane runs as the `vcluster-platform` Helm chart, deployed into t - **Platform manager.** Controllers that reconcile Platform resources into connected clusters. - **Operational services.** Audit, metrics, cost data, sleep and wake behavior, snapshots, and integrations. -Platform uses Kubernetes custom resources for all management state. The backing store is etcd by default. High-availability deployments can use an [external relational database](../administer/clusters/advanced/external-database/external-database.mdx) instead. +Platform uses Kubernetes custom resources for all management state. The default single-replica deployment uses an embedded database. High-availability deployments can connect to an [external relational database](../administer/clusters/advanced/external-database/external-database.mdx) through Kine, which provides an etcd-compatible API over MySQL or PostgreSQL. ## Connected clusters and agents diff --git a/platform/introduction/how-platform-works.mdx b/platform/introduction/how-platform-works.mdx index 94178dc1d7..a497be09cf 100644 --- a/platform/introduction/how-platform-works.mdx +++ b/platform/introduction/how-platform-works.mdx @@ -5,11 +5,12 @@ sidebar_position: 4 description: How vCluster Platform reconciles resources, routes traffic, and behaves when components are unavailable. --- +import GlossaryTerm from '@site/src/components/GlossaryTerm'; import PlatformEntryPoints from '@site/static/media/platform/diagrams/platform-entry-points.svg'; import PlatformTenantLifecycle from '@site/static/media/platform/diagrams/platform-tenant-lifecycle.svg'; import PlatformNetworkPaths from '@site/static/media/platform/diagrams/platform-network-paths.svg'; -Platform follows the Kubernetes controller model. Users and automation create or update API resources expressing desired state. Controllers in the management plane compare that state against connected clusters and reconcile the difference. The connected cluster agent applies changes locally and reports status back to Platform. vCluster then runs the tenant cluster control plane within the connected cluster. +Platform follows the Kubernetes controller model. Users and automation create or update API resources expressing desired state. Controllers in the management plane compare that state against connected clusters and reconcile the difference. The connected cluster agent applies changes locally and reports status back to Platform. vCluster then runs the tenant cluster control plane within the connected cluster. For the structural components, see [Platform architecture](./architecture.mdx). @@ -60,15 +61,15 @@ For the API server, syncer, data store, CoreDNS, networking, and worker node mod Platform supports multiple network paths depending on what is being accessed and how your environment is connected.
- +
Network paths to connected cluster and tenant cluster APIs
-### Direct endpoint +### Regional and direct access endpoints -A tenant cluster can expose a direct Kubernetes API endpoint. In this model, the user's kubeconfig points directly to the tenant cluster endpoint. Platform still controls identity, access, and lifecycle. Steady state `kubectl` traffic can go directly to the tenant cluster API server. +Platform supports two approaches for bypassing the central API gateway. **Regional cluster endpoints** route requests through the agent installed on the connected cluster, avoiding the central Platform gateway while still applying authentication, authorization, and audit locally. **Direct access points** expose the tenant cluster API server endpoint directly in the user's kubeconfig. Platform still controls identity, access, and lifecycle in both cases. -Use direct endpoints when tenant cluster API servers are reachable from users or automation and you want the shortest request path. +Use these paths when round-trip latency through the central gateway is a concern, or when users need a kubeconfig that points directly to their tenant cluster. See [regional cluster endpoints](../administer/clusters/advanced/regional-cluster-endpoints.mdx) for setup. ### Platform proxy @@ -82,7 +83,7 @@ Platform uses a Tailscale network path for environments where direct connectivit This path is useful when connected clusters, tenant clusters, or users are behind NAT, firewall rules, or private networks. The agent and Platform establish the network relationship. DERP provides a relay path when peer-to-peer traffic cannot be established. -For troubleshooting this path, see [tsnet connectivity](../troubleshoot/tsnet-connectivity.mdx). For narrower communication concepts, see [vCluster Platform communication](../understand/platform_communication.mdx). +For troubleshooting this path, see [tsnet connectivity](../troubleshoot/tsnet-connectivity.mdx). ## Failure behavior diff --git a/platform/understand/what-are-clusters.mdx b/platform/understand/what-are-clusters.mdx index 23a973765a..7abf7a1be6 100644 --- a/platform/understand/what-are-clusters.mdx +++ b/platform/understand/what-are-clusters.mdx @@ -2,6 +2,7 @@ title: What are Connected Clusters sidebar_label: What Are Connected Clusters sidebar_position: 3 +description: Connected clusters are Kubernetes clusters registered with vCluster Platform, serving as the control plane clusters where tenant cluster control planes run. --- import ConnectedClustersDashboard from '@site/static/media/platform/screenshots/connected-clusters-agent-status.png';