How loft-sh/vcluster works
1. This repository builds a virtual Kubernetes platform, not just a CLI.
The core product is vCluster: a tenant-facing Kubernetes control plane that runs on top of a host/control-plane cluster, or in standalone mode on dedicated infrastructure. The repo contains both the control-plane runtime and the user/admin CLI.
2. Two primary entrypoints define the system boundary.
cmd/vcluster is the in-cluster/server-side binary that starts the virtual control plane and its controllers. cmd/vclusterctl is the client-side command set used to create, connect to, manage, and debug vClusters from a developer machine or automation.
3. Deployment is chart-driven and mode-aware.
The chart/ Helm chart is the main packaging boundary for cluster installation. It renders the API server/control-plane workload, RBAC, networking, persistence, and optional components like etcd, ingress, metrics, and platform-specific integrations. The chart and pkg/pro/ show that the runtime supports multiple deployment models: shared nodes, dedicated nodes, private nodes, and standalone.
4. The heart of the architecture is resource virtualization and synchronization.
pkg/controllers/, pkg/syncer/, pkg/mappings/, and pkg/util/translate/ implement the bidirectional bridge between the virtual cluster API and the host cluster. Virtual resources are translated, mapped, recorded, and mirrored to host-side objects, while selected host resources are surfaced back into the tenant cluster.
5. Resource handling is organized by Kubernetes object type.
Under pkg/controllers/resources/ you can see separate syncers/translators for pods, services, namespaces, nodes, secrets, configmaps, PVCs/PVs, ingress/gateway APIs, storage classes, network policies, snapshot objects, and more. This is where the architecture becomes “Kubernetes-aware” rather than generic object replication.
6. Node and scheduling behavior are a major subsystem.
pkg/controllers/resources/nodes, pkg/controllers/resources/pods/scheduling, pkg/server/filters/podscheduling.go, and the node/scheduler test suites indicate special handling for virtual node identity, pod scheduling, and node-service behavior. This is central to the isolation model, especially for private nodes, dedicated nodes, and autoscaling scenarios.
7. Networking and API proxying are first-class concerns.
pkg/server/ provides request handling and filters for kubelet access, metrics, node-name rewriting, redirects, and panic recovery. The server layer is effectively the virtual API front door, proxying or transforming traffic between tenant clients and the underlying host or embedded components.
8. Identity, auth, and RBAC are split between tenant and host boundaries.
pkg/authentication/, pkg/authorization/, and the chart RBAC templates show that the system must authenticate tenant requests while also enforcing host-cluster permissions for the virtual control plane. There are dedicated paths for bearer tokens, impersonation, delegated auth, kubelet auth, and platform auth.
9. Certificates and TLS lifecycle are managed as a subsystem.
pkg/certs/ and pkg/server/cert/ handle cert creation, rotation, watching, and sync. This matters because the virtual API server, webhook/integration endpoints, and tenant-facing components need their own trust material and renewal flow.
10. State, persistence, and snapshots are built in.
pkg/snapshot/, pkg/etcd/, and the snapshot-related CLI commands show that the control plane can persist state in embedded etcd or external backends, and can export/import snapshots to object storage providers. The snapshot layer includes volume-aware restore paths, container/OCI/S3/Azure storage backends, and restore controllers.
11. Platform features are layered above the core vCluster mechanics.
pkg/platform/, pkg/pro/, and the many cmd/vclusterctl/cmd/platform/* commands indicate a broader platform integration layer for lifecycle management, secrets, backup, sleep/wakeup, connect/disconnect, and multi-tenant operations. These features rely on the same underlying cluster virtualization primitives but add management-plane workflows.
12. Plugin and extension points are explicit.
pkg/plugin/ contains v1 and v2 plugin APIs, including protobuf/gRPC definitions. This suggests an extension boundary for external behaviors such as UI or hook integrations, rather than hard-coding every feature into the control plane.
13. Configuration is a first-class input to architecture selection.
pkg/config/, config/, and chart/values.yaml define the runtime configuration model, including legacy migration, validation, diffs, defaults, and warnings. This configuration determines whether the cluster runs in shared, private-node, or standalone style, and which host integrations are enabled.
14. The repo includes strong verification and compatibility infrastructure.
e2e-next/, conformance/, and test/ are not product code, but they reveal the intended system shape: cross-version Kubernetes compatibility, lifecycle tests, security tests, storage/snapshot tests, and deployment-mode tests. The workflows in .github/workflows/ and load-test assets reinforce that the architecture is validated across install, upgrade, and scale scenarios.
15. External dependencies are mostly Kubernetes-native.
The system is built in Go and integrates with Kubernetes APIs, Helm, CRDs, admission/webhook-style behavior, CSI/CNI assumptions, and object storage backends for snapshots. The design centers on “virtual control plane + sync/translate layer + host/infra integrations,” with optional standalone operation when no host cluster should be required.
Main entry points: resources Resource sync · e2e-next Validation suites · server Server · pro Pro modes
Components 21
Control plane
Server-side runtime that exposes and runs the virtual Kubernetes control plane.
- vcluster · In-cluster entrypoint that starts the virtual control plane and controllers.
cmd/vcluster - Server · Virtual API server layer with request filters, proxying, and traffic shaping.
pkg/server - Setup · Wires controllers, managers, proxying, and runtime initialization.
pkg/setup - Auth & RBAC · Authentication and authorization paths across tenant, host, kubelet, and impersonation boundaries.
pkg/authentication - Controllers · Central controller registration plus shared control loops for core cluster behavior.
pkg/controllers
Client tools
CLI and user-facing workflows for creating, connecting, and operating vClusters.
- vclusterctl · User-facing command set for create, connect, debug, manage, and operate vClusters.
cmd/vclusterctl - CLI core · Shared client workflows for create/connect/delete/list/describe/pause/resume and local platform modes.
pkg/cli
Virtualization core
Translation, mapping, and synchronization layer between virtual and host clusters.
- Resource sync · Per-resource syncers and translators that virtualize Kubernetes objects by type.
pkg/controllers/resources - Sync engine · Generic syncer framework, handlers, importers, and context used by resource controllers.
pkg/syncer - Mappings · Canonical resource mappings, registry, store, and generic mirror/recorder plumbing.
pkg/mappings - Translate · Shared translation helpers for labels, namespaces, and object mutation between host and virtual views.
pkg/util/translate - Nodes · Virtual node identity, node service behavior, and node-specific translation and scheduling support.
pkg/controllers/resources/nodes - Pod scheduling · Pod scheduling translation and scheduling policy that ties together virtual nodes and placement.
pkg/controllers/resources/pods/scheduling
Platform features
Higher-level lifecycle, backup, sleep, and integration workflows built on top of the core cluster.
- Platform · Platform-level lifecycle, access, backup, sleep, and multi-tenant cluster operations.
pkg/platform - Pro modes · Mode-specific runtime support for shared, private-node, standalone, embedded etcd, and platform integrations.
pkg/pro - Snapshots · Snapshot creation, storage backends, restore controllers, and volume-aware restore flow.
pkg/snapshot - Plugins · v1 and v2 plugin APIs for external extensions and hook-style integrations.
pkg/plugin
Packaging and infra
Helm chart, configuration, certs, and deployment wiring for different runtime modes.
- Helm chart · Primary deployment boundary for workload, RBAC, networking, persistence, and optional components.
chart - Config · Configuration model, defaults, validation, legacy migration, and mode selection inputs.
pkg/config - Certificates · Certificate generation, rotation, watching, and sync for server and tenant-facing endpoints.
pkg/certs
Validation
Test and conformance suites that exercise install, modes, sync, security, and upgrade behavior.
- Validation suites · End-to-end, conformance, security, storage, mode, and migration validation across Kubernetes versions.
e2e-next
Connections 27
- vcluster → Server: starts · Server binary launches the virtual API and control-plane runtime.
- vcluster → Setup: boots · Entrypoint delegates initialization and controller wiring.
- Setup → Controllers: registers · Setup assembles and starts controller managers.
- Server → Auth & RBAC: secures · Request handling depends on authn/authz and kubelet/impersonation policies.
- Server → Certificates: serves tls · Server endpoints rely on certificate lifecycle and rotation.
- Server → Sync engine: proxies sync · API front door feeds translated and synchronized object flows.
- vclusterctl → CLI core: invokes · CLI entrypoint dispatches to shared client workflows.
- CLI core → Platform: manages · Client workflows cover platform lifecycle, access, backup, and sleep operations.
- CLI core → Snapshots: creates restores · Client commands expose snapshot and restore flows.
- Helm chart → Config: renders from · Deployment templates are driven by the configuration model and values.
- Helm chart → Pro modes: enables modes · Chart supports shared, private-node, standalone, and integration-heavy deployments.
- Config → Pro modes: selects · Configuration determines deployment mode and enabled integrations.
- Pro modes → Controllers: extends · Pro/runtime features add specialized controller behavior and patches.
- Controllers → Resource sync: orchestrates · Core controllers register and drive resource-specific sync loops.
- Resource sync → Sync engine: uses · Per-resource implementations build on the generic syncer framework.
- Sync engine → Mappings: consults · Syncing uses mapping registry and persistent mapping store.
- Mappings → Translate: applies · Mappings rely on translation helpers for object shape and identity changes.
- Resource sync → Nodes: specializes · Node subsystem is a dedicated resource boundary with service and identity handling.
- Resource sync → Pod scheduling: coordinates · Pod resource handling depends on scheduling-specific logic.
- Pod scheduling → Nodes: targets · Scheduling policy is tightly coupled to virtual node semantics.
- Resource sync → Snapshots: restores data · Storage-related controllers connect object sync with snapshot restore paths.
- Platform → Snapshots: backs up · Platform workflows build on snapshot and restore primitives.
- Platform → Plugins: extends · Platform features can be augmented through plugin APIs.
- Validation suites → Helm chart: verifies · Validation covers installation and chart rendering behavior.
- Validation suites → Resource sync: exercises · E2E and conformance suites validate resource sync behavior.
- Validation suites → Pro modes: covers · Validation includes isolation, rootless, scheduler, and private-node modes.
- Validation suites → Snapshots: checks · Storage and restore scenarios are validated end to end.