How Platform works
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 clusterTenant ClusterA fully isolated Kubernetes environment provisioned for a single tenant. Each tenant cluster has its own API server, controller manager, and resource namespace, backed by a virtualized control plane hosted on a Control Plane Cluster. From the tenant's perspective it behaves exactly like a standard Kubernetes cluster. control plane within the connected cluster.
For the structural components, see Platform architecture.
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/<cluster>. |
| Project resource proxy | Tenant cluster and space access | Proxies project-scoped requests under /kubernetes/project/<project>/virtualcluster/<name> or /kubernetes/project/<project>/space/<name>. |
Resource lifecycle​
When a user or automation creates or updates a Platform resource, it moves through a consistent path from request to deployed state:
- A user, CLI command, integration, or GitOps workflow submits a request. Platform creates or updates the API resource expressing desired state.
- Platform validates the resource against project policy, allowed clusters, allowed templates, and quotas.
- Platform controllers reconcile the desired state. The connected cluster agent applies changes locally, including namespaces, RBAC, and Helm releases.
- The connected cluster reports status back to Platform. The resource status is updated and reflected 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, wake behavior, Argo CD registration, and cleanup. An externally deployed tenant cluster 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.
Network paths​
Platform supports multiple network paths depending on what is being accessed and how your environment is connected.
Regional and direct access endpoints​
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 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 for setup.
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.
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. |