Syncing From Host

Some resources need to flow from the host cluster into the virtual cluster. This is primarily used for cluster-level resources that workloads need to discover, such as storage classes, nodes, and CSI resources.

How From-Host Syncing Works

From-host syncing follows a different pattern than to-host syncing:

The syncer watches for resources in the host cluster (or specific namespaces)
When a matching resource is found, it’s copied into the virtual cluster
The virtual copy is kept in sync with the host original
When the host resource is deleted, the virtual copy is removed

The implementation is in pkg/syncer/from_host_syncer.go:102:

func (s *genericFromHostSyncer) SyncToVirtual(ctx *synccontext.SyncContext, event *synccontext.SyncToVirtualEvent[client.Object]) (ctrl.Result, error) {
    vObj := translate.VirtualMetadata(event.Host, s.HostToVirtual(...))
    // Copy fields from host to virtual
    return patcher.CreateVirtualObject(ctx, event.Host, vObj, ...)
}

Default Synced Resources

Events

Enabled by default - Syncs events from host to virtual cluster so users can see what’s happening with their workloads.

sync:
  fromHost:
    events:
      enabled: true

Events related to synced resources (Pods, PVCs, etc.) are automatically imported into the virtual cluster.

Storage Resources (Auto-Enabled)

These resources are automatically enabled when the virtual scheduler is enabled:

sync:
  fromHost:
    storageClasses:
      enabled: auto  # Enabled with virtual scheduler
    csiDrivers:
      enabled: auto
    csiNodes:
      enabled: auto
    csiStorageCapacities:
      enabled: auto

To always enable them:

sync:
  fromHost:
    storageClasses:
      enabled: true
    csiDrivers:
      enabled: true
    csiNodes:
      enabled: true
    csiStorageCapacities:
      enabled: true

Optional Resources

These resources can be enabled as needed:

Nodes

By default, vCluster creates fake nodes. You can sync real nodes from the host:

sync:
  fromHost:
    nodes:
      enabled: true
      # Allow syncing changes from virtual to host
      syncBackChanges: false
      # Hide image status to prevent image enumeration
      clearImageStatus: false
      selector:
        # Sync all nodes vs only nodes with vCluster pods
        all: false
        # Sync only nodes with specific labels
        labels: {}

Sync all nodes:

sync:
  fromHost:
    nodes:
      enabled: true
      selector:
        all: true

Sync nodes with specific labels:

sync:
  fromHost:
    nodes:
      enabled: true
      selector:
        labels:
          node-role.kubernetes.io/worker: ""

IngressClasses

sync:
  fromHost:
    ingressClasses:
      enabled: true

Allows virtual cluster users to discover available ingress classes.

RuntimeClasses

sync:
  fromHost:
    runtimeClasses:
      enabled: true

Useful when using alternative container runtimes like Kata Containers or gVisor.

PriorityClasses

sync:
  fromHost:
    priorityClasses:
      enabled: true

Imports host cluster priority classes for pod scheduling.

VolumeSnapshotClasses

sync:
  fromHost:
    volumeSnapshotClasses:
      enabled: true

DeviceClasses

sync:
  fromHost:
    deviceClasses:
      enabled: true

For Dynamic Resource Allocation (DRA) devices.

Mapped Resources

Some resources support namespace mappings to sync specific resources from host namespaces:

ConfigMaps

Sync ConfigMaps from specific host namespaces:

sync:
  fromHost:
    configMaps:
      enabled: true
      mappings:
        byName:
          # Sync all ConfigMaps from host namespace to virtual namespace
          "kube-system/*": "kube-system/*"
          
          # Sync specific ConfigMap with same name
          "default/my-config": "default/my-config"
          
          # Sync specific ConfigMap with different name
          "default/host-config": "default/virtual-config"
          
          # Sync from vCluster namespace to virtual namespace
          "/my-config": "default/my-config"
          
          # Sync everything from vCluster namespace
          "": "imported/*"

Example mappings:

sync:
  fromHost:
    configMaps:
      enabled: true
      mappings:
        byName:
          # Import all ConfigMaps from kube-system
          "kube-system/*": "kube-system/*"
          # Import a specific monitoring config
          "monitoring/prometheus-config": "monitoring/prometheus"

Secrets

Sync Secrets from host to virtual cluster:

sync:
  fromHost:
    secrets:
      enabled: true
      mappings:
        byName:
          # Same wildcard syntax as ConfigMaps
          "cert-manager/*": "cert-manager/*"
          "default/registry-creds": "default/registry-creds"

Example use case - Image pull secrets:

sync:
  fromHost:
    secrets:
      enabled: true
      mappings:
        byName:
          # Sync image pull secret from host to all virtual namespaces
          "default/registry-credentials": "default/registry-credentials"

Mapping Syntax

The byName mapping syntax supports these patterns:

Pattern	Description	Example
`"namespace/*"`	All resources in namespace	`"kube-system/": "kube-system/"`
`"namespace/name"`	Specific resource, same name	`"default/config": "default/config"`
`"namespace/name1"` to different	Specific resource, rename	`"default/host-name": "default/virt-name"`
`""` or `"/name"`	From vCluster namespace	`"/secret": "default/secret"`
`""` with wildcard	All from vCluster namespace	`"": "imported/*"`

Configuration Examples

Basic Setup (Defaults)

sync:
  fromHost:
    events:
      enabled: true
    storageClasses:
      enabled: auto
    csiDrivers:
      enabled: auto
    csiNodes:
      enabled: auto
    csiStorageCapacities:
      enabled: auto

Advanced Node Syncing

Sync real nodes for better resource visibility:

sync:
  fromHost:
    nodes:
      enabled: true
      selector:
        all: true
        labels:
          node-type: worker
      # Prevent modification of host nodes from virtual cluster
      syncBackChanges: false
      # Hide pulled images for security
      clearImageStatus: true

Full Storage Integration

Enable all storage-related resources:

sync:
  fromHost:
    storageClasses:
      enabled: true
    csiDrivers:
      enabled: true
    csiNodes:
      enabled: true
    csiStorageCapacities:
      enabled: true
    volumeSnapshotClasses:
      enabled: true

Import Host Configurations

Sync ConfigMaps and Secrets from host:

sync:
  fromHost:
    configMaps:
      enabled: true
      mappings:
        byName:
          "kube-system/coredns": "kube-system/coredns"
          "monitoring/*": "monitoring/*"
    secrets:
      enabled: true
      mappings:
        byName:
          "default/registry-creds": "default/registry-creds"
          "cert-manager/*": "cert-manager/*"

Multi-Namespace Mapping

Import resources from multiple host namespaces:

sync:
  fromHost:
    configMaps:
      enabled: true
      mappings:
        byName:
          # Import from multiple namespaces
          "team-a/*": "team-a/*"
          "team-b/*": "team-b/*"
          "shared/*": "shared/*"
          # Import from vCluster's own namespace
          "/shared-config": "default/config"

Implementation Details

Custom Manager for Mappings

When using namespace mappings, vCluster creates a custom physical manager that watches multiple namespaces (pkg/syncer/from_host_syncer.go:182):

func ConfigureNewLocalManager(ctx *synccontext.RegisterContext, mappings map[string]string, syncerName string) (ctrl.Manager, bool, error) {
    multiNsCacheConfig, customManagerNeeded := vclusterconfig.GetLocalCacheOptionsFromConfigMappings(mappings, ctx.Config.HostNamespace)
    if !customManagerNeeded {
        return nil, true, nil
    }
    // Create multi-namespace manager
    localMultiNamespaceManager, err := ctrl.NewManager(ctx.Config.HostConfig, GetOptionsForMultiNamespaceManager(ctx, multiNsCacheConfig))
    // ...
}

This allows vCluster to efficiently watch resources across multiple host namespaces.

Resource Copying

The from-host syncer copies specific fields from host to virtual resources (pkg/controllers/resources/configmaps/from_host_syncer.go:36):

func (s *syncToHostConfigMapSyncer) CopyHostObjectToVirtual(vObj, pObj client.Object) {
    vCm := vObj.(*corev1.ConfigMap)
    hostCopy := pObj.(*corev1.ConfigMap).DeepCopy()
    vCm.SetAnnotations(hostCopy.GetAnnotations())
    vCm.SetLabels(hostCopy.Labels)
    vCm.Data = hostCopy.Data
}

Only necessary fields are copied to maintain consistency.

Troubleshooting

Resource Not Appearing in Virtual Cluster

Verify resource exists in host cluster:
```
kubectl get storageclass
```

Check syncing is enabled:

helm get values my-vcluster -n vcluster-my-vcluster

Check vCluster logs:

kubectl logs -n vcluster-my-vcluster deploy/my-vcluster -f | grep -i "storageclass"

Verify RBAC permissions:

kubectl get clusterrole vc-my-vcluster -o yaml

Mapped Resources Not Syncing

Check namespace permissions: The vCluster service account needs read access to mapped namespaces
Verify mapping syntax: Ensure byName mappings are correct

Check for errors in logs:

kubectl logs -n vcluster-my-vcluster deploy/my-vcluster -f | grep "mapping"

Events Not Showing Up

Events are filtered to only show events related to synced resources. If a Pod is synced to the host, its events will be synced back to the virtual cluster.

Security Considerations

Namespace access: Mapped resources require additional RBAC permissions in host namespaces
Secret exposure: Be cautious when syncing secrets from host to virtual cluster
Node information: Consider using clearImageStatus: true to hide container images
Sync back changes: Keep syncBackChanges: false for nodes unless specifically needed

Best Practices

Start with defaults: The auto-enabled storage resources are usually sufficient
Use specific mappings: Avoid wildcards like "*/*" that sync everything
Limit node syncing: Use selector.all: false and selector.labels to sync only needed nodes
Monitor permissions: Ensure vCluster has appropriate RBAC for mapped namespaces
Document mappings: Keep track of what’s being synced and why

Get Started

Architecture

Deployment

Operations

Resource Syncing

Use Cases

Security

Integrations

Documentation Index

​How From-Host Syncing Works

​Default Synced Resources

​Events

​Storage Resources (Auto-Enabled)

​Optional Resources

​Nodes

​IngressClasses

​RuntimeClasses

​PriorityClasses

​VolumeSnapshotClasses

​DeviceClasses

​Mapped Resources

​ConfigMaps

​Secrets

​Mapping Syntax

​Configuration Examples

​Basic Setup (Defaults)

​Advanced Node Syncing

​Full Storage Integration

​Import Host Configurations

​Multi-Namespace Mapping

​Implementation Details

​Custom Manager for Mappings

​Resource Copying

​Troubleshooting

​Resource Not Appearing in Virtual Cluster

​Mapped Resources Not Syncing

​Events Not Showing Up

​Security Considerations

​Best Practices

​Next Steps

Build docs developers (and LLMs) love