Architecture Spectrum
vCluster architectures range from maximum density to complete isolation:Shared Nodes
Maximum density, minimum cost. Virtual clusters share host nodes.
Dedicated Nodes
Isolated compute on labeled node pools within the host cluster.
Private Nodes
Full CNI/CSI isolation with external nodes joining directly.
Standalone Mode
No host cluster required. vCluster runs on bare metal or VMs.
Architecture Comparison
Choose your architecture based on your isolation, compliance, and infrastructure requirements:| Feature | Shared Nodes | Dedicated Nodes | Private Nodes | Standalone |
|---|---|---|---|---|
| Host Cluster Required | Yes | Yes | Yes | No |
| Node Isolation | ❌ | ✅ | ✅ | ✅ |
| CNI/CSI Isolation | ❌ | ❌ | ✅ | ✅ |
| Network Isolation | Namespace | Node Labels | Full | Full |
| Storage Isolation | Namespace | Node Labels | Full | Full |
| Resource Efficiency | Highest | High | Medium | Low |
| Setup Complexity | Lowest | Low | Medium | Highest |
| Best For | Dev/test, cost optimization | Production multi-tenancy | Compliance, GPU workloads | Bare metal, edge computing |
Core Components
Regardless of architecture, all vCluster deployments include:Control Plane Components
API Server
API Server
Each virtual cluster has its own Kubernetes API server that provides complete API isolation. Users interact with the virtual cluster through this API server, which handles authentication, authorization, and admission control.The API server runs in the host cluster (or standalone) and maintains its own view of the cluster state.
Controller Manager
Controller Manager
Manages core Kubernetes controllers within the virtual cluster, handling workload lifecycle, service endpoints, and other built-in resources.In shared and dedicated modes, some responsibilities are delegated to the host cluster for efficiency.
Data Store (etcd or SQL)
Data Store (etcd or SQL)
Stores the virtual cluster’s state. Options include:
- Embedded SQLite: Default, runs in-process (easiest)
- Embedded etcd: High availability option
- External etcd: Deployed by Helm or externally managed
- External Database: PostgreSQL, MySQL, RDS via Kine
Syncer
Syncer
The syncer is vCluster’s core innovation. It synchronizes resources between the virtual and host clusters (or manages resources directly in standalone mode).Key responsibilities:
- Syncing pods, services, and other resources
- Rewriting resource references and names
- Managing resource mappings and translation
- Handling bi-directional synchronization
Optional Components
- Scheduler: Optional virtual scheduler (K8s distro only) for advanced scheduling
- CoreDNS: Provides DNS resolution within the virtual cluster
- Konnectivity: Reverse tunnel for private nodes communication
- Cloud Controller Manager: Sets node IPs and provider IDs for private nodes
How vCluster Works
User Creates Resources
Users interact with the virtual cluster API server using
kubectl or other Kubernetes tools. The API server authenticates and authorizes requests, then stores resources in its data store.Syncer Watches Resources
The syncer watches for changes in the virtual cluster (and host cluster). It maintains mappings between virtual and physical resources.
Resources Get Translated
When resources need to run on host infrastructure, the syncer translates them:
- Adds namespace prefixes to names
- Rewrites labels and annotations
- Injects tolerations and node selectors
- Maps virtual references to physical ones
Resources Run on Infrastructure
Depending on the architecture:
- Shared/Dedicated: Pods run on host cluster nodes
- Private: Pods run on external nodes with their own CNI/CSI
- Standalone: Pods run on nodes joined directly to vCluster
Choosing an Architecture
Use this decision tree to select the right architecture:Do you have a Kubernetes cluster?
Do you have a Kubernetes cluster?
No: Use Standalone ModeYes: Continue to next question
Do you need complete network/storage isolation?
Do you need complete network/storage isolation?
Yes: Use Private NodesNo: Continue to next question
Do you need compute isolation between tenants?
Do you need compute isolation between tenants?
Yes: Use Dedicated NodesNo: Use Shared Nodes
Quick Recommendations
Development & Testing
Shared Nodes - Fastest setup, lowest cost, perfect for temporary environments and CI/CD pipelines.
Production Multi-Tenancy
Dedicated Nodes - Good isolation without operational complexity, ideal for SaaS platforms and team environments.
Regulated Industries
Private Nodes - Complete isolation for compliance requirements like PCI-DSS, HIPAA, or SOC 2.
Bare Metal / Edge
Standalone - No host cluster needed, perfect for edge computing, bare metal, and maximum performance.
Resource Syncing
All architectures use vCluster’s resource syncing mechanism:From Virtual to Host (toHost)
Resources created in the virtual cluster that need to run on physical infrastructure:- Pods: Workload containers (always synced)
- Services: Network endpoints
- PersistentVolumeClaims: Storage requests
- ConfigMaps/Secrets: Configuration data (only those referenced by pods)
- Endpoints/EndpointSlices: Service backend information
From Host to Virtual (fromHost)
Resources synced from host to virtual for compatibility:- Nodes: Host nodes (or fake nodes in shared mode)
- StorageClasses: Available storage types
- IngressClasses: Available ingress controllers
- Events: Node and infrastructure events
In private and standalone modes, many “fromHost” syncs are disabled because the virtual cluster manages these resources directly.
Performance Characteristics
Shared Nodes
- Startup Time: ~10-15 seconds
- Resource Overhead: ~200MB memory, 0.2 CPU
- Density: 50+ vClusters per host cluster
Dedicated Nodes
- Startup Time: ~10-15 seconds
- Resource Overhead: ~200MB + dedicated node resources
- Density: Limited by available nodes
Private Nodes
- Startup Time: ~30-60 seconds (node join time)
- Resource Overhead: ~500MB + full node resources
- Density: Limited by node provisioning
Standalone
- Startup Time: ~60-120 seconds (full cluster bootstrap)
- Resource Overhead: Full control plane + nodes
- Density: 1 vCluster = 1 cluster
Security Considerations
Security posture varies by architecture:| Aspect | Shared | Dedicated | Private | Standalone |
|---|---|---|---|---|
| API Isolation | ✅ | ✅ | ✅ | ✅ |
| Process Isolation | Container | Container | VM/Bare Metal | VM/Bare Metal |
| Network Isolation | Namespace | Node Labels | Full CNI | Full CNI |
| Storage Isolation | Namespace | Node Labels | Full CSI | Full CSI |
| Host Access Required | Yes (limited) | Yes (limited) | No | No |
| Attack Surface | Highest | High | Low | Lowest |
Next Steps
Explore Architectures
Deep dive into each architecture to understand implementation details, configuration, and use cases.
Auto Nodes
Learn about Karpenter-powered autoscaling for private nodes across any infrastructure.