# loft-sh/vcluster architecture

> Architecture diagram of the GitHub repository loft-sh/vcluster, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/loft-sh/vcluster
- Repository: https://github.com/loft-sh/vcluster

## Overview

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: [`pkg/controllers/resources`](https://github.com/loft-sh/vcluster/tree/main/pkg/controllers/resources) (Resource sync), [`e2e-next`](https://github.com/loft-sh/vcluster/tree/main/e2e-next) (Validation suites), [`pkg/server`](https://github.com/loft-sh/vcluster/tree/main/pkg/server) (Server), [`pkg/pro`](https://github.com/loft-sh/vcluster/tree/main/pkg/pro) (Pro modes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_control["Control plane"]
  node_node_cmd_vcluster["vcluster<br/>server binary"]
  node_node_server["Server<br/>api front door"]
  node_node_setup["Setup<br/>bootstrap"]
  node_node_authz["Auth & RBAC<br/>security boundary"]
  node_node_controllers["Controllers<br/>reconciliation"]
end

subgraph group_grp_client["Client tools"]
  node_node_cmd_vclusterctl["vclusterctl<br/>cli binary"]
  node_node_cli_core["CLI core<br/>client ops"]
end

subgraph group_grp_sync["Virtualization core"]
  node_node_resources["Resource sync<br/>object replication"]
  node_node_syncer["Sync engine<br/>sync runtime"]
  node_node_mappings["Mappings<br/>resource map"]
  node_node_translate["Translate<br/>object transform"]
  node_node_nodes["Nodes<br/>node subsystem"]
  node_node_podsched["Pod scheduling<br/>scheduling rules"]
end

subgraph group_grp_platform["Platform features"]
  node_node_platform["Platform<br/>mgmt workflows"]
  node_node_pro["Pro modes<br/>deployment modes"]
  node_node_snapshot["Snapshots<br/>backup/restore"]
  node_node_plugins["Plugins<br/>extension api"]
end

subgraph group_grp_infra["Packaging and infra"]
  node_node_chart["Helm chart<br/>packaging"]
  node_node_config["Config"]
  node_node_certs["Certificates<br/>tls lifecycle"]
end

subgraph group_grp_validation["Validation"]
  node_node_tests["Validation suites<br/>e2e/conformance"]
end

node_node_cmd_vcluster -->|"starts"| node_node_server
node_node_cmd_vcluster -->|"boots"| node_node_setup
node_node_setup -->|"registers"| node_node_controllers
node_node_server -->|"secures"| node_node_authz
node_node_server -->|"serves tls"| node_node_certs
node_node_server -->|"proxies sync"| node_node_syncer
node_node_cmd_vclusterctl -->|"invokes"| node_node_cli_core
node_node_cli_core -->|"manages"| node_node_platform
node_node_cli_core -->|"creates restores"| node_node_snapshot
node_node_chart -->|"renders from"| node_node_config
node_node_chart -->|"enables modes"| node_node_pro
node_node_config -->|"selects"| node_node_pro
node_node_pro -->|"extends"| node_node_controllers
node_node_controllers -->|"orchestrates"| node_node_resources
node_node_resources -->|"uses"| node_node_syncer
node_node_syncer -->|"consults"| node_node_mappings
node_node_mappings -->|"applies"| node_node_translate
node_node_resources -->|"specializes"| node_node_nodes
node_node_resources -->|"coordinates"| node_node_podsched
node_node_podsched -->|"targets"| node_node_nodes
node_node_resources -->|"restores data"| node_node_snapshot
node_node_platform -->|"backs up"| node_node_snapshot
node_node_platform -->|"extends"| node_node_plugins
node_node_tests -->|"verifies"| node_node_chart
node_node_tests -->|"exercises"| node_node_resources
node_node_tests -->|"covers"| node_node_pro
node_node_tests -->|"checks"| node_node_snapshot

click node_node_cmd_vcluster "https://github.com/loft-sh/vcluster/tree/main/cmd/vcluster"
click node_node_server "https://github.com/loft-sh/vcluster/tree/main/pkg/server"
click node_node_setup "https://github.com/loft-sh/vcluster/tree/main/pkg/setup"
click node_node_cmd_vclusterctl "https://github.com/loft-sh/vcluster/tree/main/cmd/vclusterctl"
click node_node_cli_core "https://github.com/loft-sh/vcluster/tree/main/pkg/cli"
click node_node_platform "https://github.com/loft-sh/vcluster/tree/main/pkg/platform"
click node_node_pro "https://github.com/loft-sh/vcluster/tree/main/pkg/pro"
click node_node_chart "https://github.com/loft-sh/vcluster/tree/main/chart"
click node_node_config "https://github.com/loft-sh/vcluster/tree/main/pkg/config"
click node_node_certs "https://github.com/loft-sh/vcluster/tree/main/pkg/certs"
click node_node_authz "https://github.com/loft-sh/vcluster/tree/main/pkg/authentication"
click node_node_controllers "https://github.com/loft-sh/vcluster/tree/main/pkg/controllers"
click node_node_resources "https://github.com/loft-sh/vcluster/tree/main/pkg/controllers/resources"
click node_node_syncer "https://github.com/loft-sh/vcluster/tree/main/pkg/syncer"
click node_node_mappings "https://github.com/loft-sh/vcluster/tree/main/pkg/mappings"
click node_node_translate "https://github.com/loft-sh/vcluster/tree/main/pkg/util/translate"
click node_node_nodes "https://github.com/loft-sh/vcluster/tree/main/pkg/controllers/resources/nodes"
click node_node_podsched "https://github.com/loft-sh/vcluster/tree/main/pkg/controllers/resources/pods/scheduling"
click node_node_snapshot "https://github.com/loft-sh/vcluster/tree/main/pkg/snapshot"
click node_node_plugins "https://github.com/loft-sh/vcluster/tree/main/pkg/plugin"
click node_node_tests "https://github.com/loft-sh/vcluster/tree/main/e2e-next"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_cmd_vcluster,node_node_server,node_node_setup,node_node_authz,node_node_controllers toneBlue
class node_node_cmd_vclusterctl,node_node_cli_core toneAmber
class node_node_resources,node_node_syncer,node_node_mappings,node_node_translate,node_node_nodes,node_node_podsched toneMint
class node_node_platform,node_node_pro,node_node_snapshot,node_node_plugins toneRose
class node_node_chart,node_node_config,node_node_certs toneIndigo
class node_node_tests toneTeal
```

## Components

### Control plane

Server-side runtime that exposes and runs the virtual Kubernetes control plane.

- [vcluster](https://github.com/loft-sh/vcluster/tree/main/cmd/vcluster): server binary · In-cluster entrypoint that starts the virtual control plane and controllers. · `cmd/vcluster`
- [Server](https://github.com/loft-sh/vcluster/tree/main/pkg/server): api front door · Virtual API server layer with request filters, proxying, and traffic shaping. · `pkg/server`
- [Setup](https://github.com/loft-sh/vcluster/tree/main/pkg/setup): bootstrap · Wires controllers, managers, proxying, and runtime initialization. · `pkg/setup`
- [Auth & RBAC](https://github.com/loft-sh/vcluster/tree/main/pkg/authentication): security boundary · Authentication and authorization paths across tenant, host, kubelet, and impersonation boundaries. · `pkg/authentication`
- [Controllers](https://github.com/loft-sh/vcluster/tree/main/pkg/controllers): reconciliation · 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](https://github.com/loft-sh/vcluster/tree/main/cmd/vclusterctl): cli binary · User-facing command set for create, connect, debug, manage, and operate vClusters. · `cmd/vclusterctl`
- [CLI core](https://github.com/loft-sh/vcluster/tree/main/pkg/cli): client ops · 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](https://github.com/loft-sh/vcluster/tree/main/pkg/controllers/resources): object replication · Per-resource syncers and translators that virtualize Kubernetes objects by type. · `pkg/controllers/resources`
- [Sync engine](https://github.com/loft-sh/vcluster/tree/main/pkg/syncer): sync runtime · Generic syncer framework, handlers, importers, and context used by resource controllers. · `pkg/syncer`
- [Mappings](https://github.com/loft-sh/vcluster/tree/main/pkg/mappings): resource map · Canonical resource mappings, registry, store, and generic mirror/recorder plumbing. · `pkg/mappings`
- [Translate](https://github.com/loft-sh/vcluster/tree/main/pkg/util/translate): object transform · Shared translation helpers for labels, namespaces, and object mutation between host and virtual views. · `pkg/util/translate`
- [Nodes](https://github.com/loft-sh/vcluster/tree/main/pkg/controllers/resources/nodes): node subsystem · Virtual node identity, node service behavior, and node-specific translation and scheduling support. · `pkg/controllers/resources/nodes`
- [Pod scheduling](https://github.com/loft-sh/vcluster/tree/main/pkg/controllers/resources/pods/scheduling): scheduling rules · 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](https://github.com/loft-sh/vcluster/tree/main/pkg/platform): mgmt workflows · Platform-level lifecycle, access, backup, sleep, and multi-tenant cluster operations. · `pkg/platform`
- [Pro modes](https://github.com/loft-sh/vcluster/tree/main/pkg/pro): deployment modes · Mode-specific runtime support for shared, private-node, standalone, embedded etcd, and platform integrations. · `pkg/pro`
- [Snapshots](https://github.com/loft-sh/vcluster/tree/main/pkg/snapshot): backup/restore · Snapshot creation, storage backends, restore controllers, and volume-aware restore flow. · `pkg/snapshot`
- [Plugins](https://github.com/loft-sh/vcluster/tree/main/pkg/plugin): extension api · 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](https://github.com/loft-sh/vcluster/tree/main/chart): packaging · Primary deployment boundary for workload, RBAC, networking, persistence, and optional components. · `chart`
- [Config](https://github.com/loft-sh/vcluster/tree/main/pkg/config): runtime config · Configuration model, defaults, validation, legacy migration, and mode selection inputs. · `pkg/config`
- [Certificates](https://github.com/loft-sh/vcluster/tree/main/pkg/certs): tls lifecycle · 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](https://github.com/loft-sh/vcluster/tree/main/e2e-next): e2e/conformance · End-to-end, conformance, security, storage, mode, and migration validation across Kubernetes versions. · `e2e-next`

## Connections

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