The Syncer: The Magic Bridge

The Core Problem

If the virtual cluster has no nodes, how do Pods actually run? The virtual API server accepts a Pod definition and stores it in SQLite — but nothing executes it, because there is no kubelet watching the virtual API server. This is the job of the Syncer.

The Syncer is a controller process running alongside the virtual API server inside the host namespace. It watches for resources created inside the virtual cluster and translates them into real resources on the host cluster.

The Sync Workflow — Step by Step

Here is exactly what happens when a tenant creates a Pod:

Tenant kubectl → Virtual API Server → (Pod stored in SQLite, status: Pending)
                                              ↓
                                          Syncer watches virtual API server
                                              ↓
                              Syncer creates a REAL Pod in host namespace
                              (renamed to avoid collisions)
                                              ↓
                              Host scheduler places Pod on a real Node
                                              ↓
                              Syncer watches real Pod status
                                              ↓
                              Syncer writes status back to virtual Pod
                              (IP, phase, conditions all mirrored back)

Naming convention: The real Pod in the host namespace gets a mangled name to prevent collisions across multiple virtual clusters. A virtual Pod named nginx in namespace default inside vCluster tenant-1 in host namespace host-ns-1 becomes something like nginx-x-default-x-tenant-1, living in namespace host-ns-1. This naming scheme encodes the virtual namespace and cluster name, ensuring uniqueness even if two different virtual clusters both have a Pod named nginx.

What Gets Synced (and What Doesn't)

The Syncer is selective by design. It only syncs the low-level primitives that the host cluster needs to actually run workloads:

This selective sync is what keeps the host cluster clean. A host admin looking at host-ns-1 sees only Pods and a handful of Secrets — not the hundreds of Deployments, ConfigMaps, and RBAC objects that exist inside the virtual cluster.