Architecture
vCluster Platform is the management plane for your 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. fleet. It runs in Kubernetes and exposes UI, CLI, and API entry points. It reconciles Platform resources into connected control plane clustersControl Plane ClusterThe Kubernetes cluster that hosts the virtualized control planes for tenant clusters. The Control Plane Cluster is operated by the platform provider and is completely invisible to tenants. There are no shared control plane nodes, no in-cluster agent pods, and no lateral path between tenant environments. With shared nodes, this cluster also runs tenant workloads alongside the control plane pods — the same node pool is used for both..
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.
Management plane​
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.
- 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.
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 through Kine, which provides an etcd-compatible API over MySQL or PostgreSQL.
Connected clusters and agents​
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.
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.
Dive deeper into connected clusters →
Projects​
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.
Access​
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.
- 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.
The gateway uses Kubernetes impersonation to forward requests. It presents the caller's verified identity to the target API without issuing direct cluster credentials.
Dive deeper into entry points and proxy paths →