Architecture
vCluster Platform is the management plane for your clusterClusterA fully isolated Kubernetes environment provisioned for a single tenant. Each 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 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 clusters, and set which templates and policies apply. Platform controllers reconcile those decisions into connected clusters, where vCluster runs each cluster's control plane. That control plane delivers managed Kubernetes directly, or serves as the foundation for other cluster types like Slurm, Ray, and inference.
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: tenants, projects, clusters, VirtualClusterInstances, templates, users, access keys, and the resources that describe physical and virtual capacity.
- Platform manager. Controllers that reconcile Platform resources into connected clusters.
- Operational services. Audit, metrics, snapshots, integrations, and sleep/wake behavior.
Platform uses Kubernetes custom resources for all management state. By default, the platform stores these resources through the Kubernetes API of the control plane cluster it's installed on. To use an external relational database instead, the platform runs embedded Kubernetes backed by 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. Cluster control planes and project workloads run there, as do the provisioning components a node provider deploys. 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 project workloads.
Dive deeper into connected clusters →
Instances, machines, and infrastructure​
Platform manages the physical and virtual machines underneath the fleet through vMetal. vMetal isn't a separate service. It's the common provisioning model Platform exposes across a portfolio of drivers, and it ships and versions with Platform.
- Node provider. Targets one connected cluster and deploys the driver components that run there, such as Metal3, Ironic, and a DHCP server for bare metal. It groups capacity into node types.
- Node type. Selects machines by label and sets their provisioning defaults, such as OS image and SSH keys.
- Instance. One customer-facing claim on a provisioned server, either physical or virtual. The
NodeClaimresource represents the request and tracks its lifecycle. - Machine. A read-only inventory mirror for one physical server. It exists independently of the instance that claims it.
A provisioned instance has one of three outcomes. Its server joins a cluster as a worker, carries that cluster's own control plane, or stays independent. The request selects the outcome. You reach an independent server over SSH, and Platform doesn't install Kubernetes on it.
That third case is why the boundaries above matter. A cluster's control plane normally runs as a workload on a connected cluster. A standalone control plane runs directly on a provisioned server instead. Platform still needs the connected cluster that runs the provisioning components, just not one to host that control plane.
Tenants​
A tenant is the outermost boundary on a platform serving more than one organization. A platform admin decides which control plane clusters, node types, OS images, templates, and connectors that organization can use. A tenant admin then divides what's granted across projects.
Tenants are optional. Use projects alone when one group administers the whole platform. Add tenants when separate organizations share it and shouldn't see each other.
Projects​
A project is a policy boundary that groups 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. For most platforms, a project is the top-level unit.
Where tenants are in use, projects sit inside one, and a project can only access what its tenant was granted.
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, 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 →