Skip to main content
Version: v5.0 Stable

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.Related: Control plane cluster, 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.Related: Cluster, Control plane cluster, Cluster.

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.

From intent to clustersAdmins and automation send intent to vCluster Platform through the UI, CLI, API, and GitOps. The Platform management plane holds projects and access, and templates and policies. Platform reconciles that intent into connected clusters. Each connected cluster runs the vCluster runtime and hosts many clusters, drawn as a stack of cards.From intent to clustersAdmins and automationUI, CLI, API, GitOpsvCluster PlatformManagement planeProjects and accessTemplates and policiesConnected clusterWorkloads run hereConnected clusterWorkloads run hereClustersvCluster runtimeClustersvCluster runtime
Platform connects admins and automation to connected clusters and the clusters running on them

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.

Management plane and connected clustersUsers reach vCluster Platform through the UI, CLI, and API. The management plane runs a web UI, an authenticating gateway, a management API serving Platform resources, controllers that reconcile them, and a backing store of custom resources. Platform reconciles that state into connected clusters, each running a Platform agent alongside cluster workloads.Management plane and connected clustersUsersUI, CLI, APIvCluster PlatformManagement planeWeb UIBrowserGatewayAuthAPIResourcesControllersReconcileBacking storeCustom resourcesConnected clusterAgentOutbound linkClusterNamespaces, RBACConnected clusterAgentOutbound linkClusterNamespaces, RBAC
Platform management plane and connected clusters

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 NodeClaim resource 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.

Where a provisioned instance ends upThe Platform management plane defines node providers, node types, and instances represented by NodeClaims. A connected cluster runs the provisioning components that a node provider deploys and hosts cluster control planes by default. Each provisioned instance has one of three outcomes: a worker that joins a cluster, a control plane that runs on the provisioned server rather than in the connected cluster, or an independent server that joins no cluster and is reached over SSH.Where a provisioned instance ends upvCluster PlatformManagement planeNode providerConnected cluster targetNode typeLabels and defaultsInstanceA NodeClaim requestConnected clusterRegistered with PlatformProvisioning componentsFrom the node providerRuns on this clusterClustercontrol planeHosted here by defaultInstancesProvisioned serversWorkerJoins a clusterControl planeOn the serverIndependentStays a serverClusterWhat it joinsWorker nodeRuns workloadsControl planeServes the APINo clusterReached over SSH
A provisioned instance becomes a worker, a control plane, or an independent server

Dive deeper into vMetal →

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.

Dive deeper into tenants →

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.

Dive deeper into projects →

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.

API gateway request pathsRequests from the web UI, the CLI, and automation all arrive at the Platform API gateway. The gateway authenticates the caller, checks access, and impersonates them. It then forwards the request to the management API for Platform resources, to a connected cluster API for cluster-scoped requests, or to a cluster API for project-scoped requests.API gateway request pathsWeb UIBrowserCLIOperatorsAutomationIntegrationsAPI gatewayAuthenticateCheck accessImpersonateManagement APIPlatform resourcesConnected cluster APICluster-scoped requestsCluster APIProject-scoped requests
Platform API gateway request paths

Dive deeper into entry points and proxy paths →

Further reading​