Skip to main content
Version: main 🚧

Sync from host to virtual

Limited vCluster Tenancy Configuration Support

This feature is only available for the following:

Running the control plane as a container and the following worker node types:
  • Host Nodes

Read more about how syncing works before deciding which resources to sync from the host cluster to the virtual cluster.

vCluster can sync certain resources from the host cluster to make them available inside the virtual cluster, but when these resources are synced, they are only synced in read-only mode. No changes to the resource in the virtual cluster syncs back to the host cluster as the resources are shared across the host cluster.

A good example would be nodes, which are nice to view inside the virtual cluster and can be also used to enabled certain features such as scheduling inside the vCluster, but you wouldn't want your virtual cluster to change the node itself. Another benefit of only syncing from host is that vCluster itself only requires read-only RBAC permissions.

vCluster also allows to sync custom resources via the custom resource definitions syncer

There are a couple of labels that are created on the host cluster by vCluster that never get synced to the virtual cluster resource. These labels are:

  • release (Label is needed to avoid conflicts with the vCluster pods themselves).
  • vcluster.loft.sh/namespace
  • vcluster.loft.sh/managed-by
  • vcluster.loft.sh/controlled-by

Resource creation behavior​

Cluster-scoped resources are surfaced read-only. If they don’t already exist in the virtual cluster, they are not created during sync. This includes:

Namespaced resources are materialized in the virtual cluster if they don’t already exist. This includes:

Enabled by default​

Disabled by default​

No bi-directional syncing​

Since syncing resources from the host cluster is in read only mode and changes in the virtual cluster do not get applied to the resource in the host cluster, bi-directional syncing does not exist across these resources.

Config reference​

fromHost required object ​

Configure what resources vCluster should sync from the host cluster to the virtual cluster.

nodes required object ​

Nodes defines if nodes should get synced from the host cluster to the virtual cluster, but not back.

enabled required boolean false ​

Enabled specifies if syncing real nodes should be enabled. If this is disabled, vCluster will create fake nodes instead.

syncBackChanges required boolean false ​

SyncBackChanges enables syncing labels and taints from the virtual cluster to the host cluster. If this is enabled someone within the virtual cluster will be able to change the labels and taints of the host cluster node.

clearImageStatus required boolean false ​

ClearImageStatus will erase the image status when syncing a node. This allows to hide images that are pulled by the node.

selector required object ​

Selector can be used to define more granular what nodes should get synced from the host cluster to the virtual cluster.

all required boolean false ​

All specifies if all nodes should get synced by vCluster from the host to the virtual cluster or only the ones where pods are assigned to.

labels required object {} ​

Labels are the node labels used to sync nodes from host cluster to virtual cluster. This will also set the node selector when syncing a pod from virtual cluster to host cluster to the same value.

patches required object[] ​

Patches patch the resource according to the provided specification.

path required string ​

Path is the path within the patch to target. If the path is not found within the patch, the patch is not applied.

expression required string ​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string ​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object ​

Reference treats the path value as a reference to another object and will rewrite it based on the chosen mode automatically. In single-namespace mode this will translate the name to "vxxxxxxxxx" to avoid conflicts with other names, in multi-namespace mode this will not translate the name.

apiVersion required string ​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string ​

APIVersionPath is optional relative path to use to determine the kind. If APIVersionPath is not found, will fallback to apiVersion.

kind required string ​

Kind is the kind of the referenced object.

kindPath required string ​

KindPath is the optional relative path to use to determine the kind. If KindPath is not found, will fallback to kind.

namePath required string ​

NamePath is the optional relative path to the reference name within the object.

namespacePath required string ​

NamespacePath is the optional relative path to the reference namespace within the object. If omitted or not found, namespacePath equals to the metadata.namespace path of the object.

labels required object ​

Labels treats the path value as a labels selector.

events required object ​

Events defines if events should get synced from the host cluster to the virtual cluster, but not back.

enabled required boolean true ​

Enabled defines if this option should be enabled.

patches required object[] ​

Patches patch the resource according to the provided specification.

path required string ​

Path is the path within the patch to target. If the path is not found within the patch, the patch is not applied.

expression required string ​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string ​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object ​

Reference treats the path value as a reference to another object and will rewrite it based on the chosen mode automatically. In single-namespace mode this will translate the name to "vxxxxxxxxx" to avoid conflicts with other names, in multi-namespace mode this will not translate the name.

apiVersion required string ​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string ​

APIVersionPath is optional relative path to use to determine the kind. If APIVersionPath is not found, will fallback to apiVersion.

kind required string ​

Kind is the kind of the referenced object.

kindPath required string ​

KindPath is the optional relative path to use to determine the kind. If KindPath is not found, will fallback to kind.

namePath required string ​

NamePath is the optional relative path to the reference name within the object.

namespacePath required string ​

NamespacePath is the optional relative path to the reference namespace within the object. If omitted or not found, namespacePath equals to the metadata.namespace path of the object.

labels required object ​

Labels treats the path value as a labels selector.

ingressClasses required object ​

IngressClasses defines if ingress classes should get synced from the host cluster to the virtual cluster, but not back.

enabled required boolean false ​

Enabled defines if this option should be enabled.

patches required object[] ​

Patches patch the resource according to the provided specification.

path required string ​

Path is the path within the patch to target. If the path is not found within the patch, the patch is not applied.

expression required string ​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string ​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object ​

Reference treats the path value as a reference to another object and will rewrite it based on the chosen mode automatically. In single-namespace mode this will translate the name to "vxxxxxxxxx" to avoid conflicts with other names, in multi-namespace mode this will not translate the name.

apiVersion required string ​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string ​

APIVersionPath is optional relative path to use to determine the kind. If APIVersionPath is not found, will fallback to apiVersion.

kind required string ​

Kind is the kind of the referenced object.

kindPath required string ​

KindPath is the optional relative path to use to determine the kind. If KindPath is not found, will fallback to kind.

namePath required string ​

NamePath is the optional relative path to the reference name within the object.

namespacePath required string ​

NamespacePath is the optional relative path to the reference namespace within the object. If omitted or not found, namespacePath equals to the metadata.namespace path of the object.

labels required object ​

Labels treats the path value as a labels selector.

selector required object ​

Selector defines the selector to use for the resource. If not set, all resources of that type will be synced.

matchLabels required object ​
matchExpressions required object[] ​
key required string ​
operator required string ​
values required string[] ​

runtimeClasses required object ​

RuntimeClasses defines if runtime classes should get synced from the host cluster to the virtual cluster, but not back.

enabled required boolean false ​

Enabled defines if this option should be enabled.

patches required object[] ​

Patches patch the resource according to the provided specification.

path required string ​

Path is the path within the patch to target. If the path is not found within the patch, the patch is not applied.

expression required string ​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string ​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object ​

Reference treats the path value as a reference to another object and will rewrite it based on the chosen mode automatically. In single-namespace mode this will translate the name to "vxxxxxxxxx" to avoid conflicts with other names, in multi-namespace mode this will not translate the name.

apiVersion required string ​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string ​

APIVersionPath is optional relative path to use to determine the kind. If APIVersionPath is not found, will fallback to apiVersion.

kind required string ​

Kind is the kind of the referenced object.

kindPath required string ​

KindPath is the optional relative path to use to determine the kind. If KindPath is not found, will fallback to kind.

namePath required string ​

NamePath is the optional relative path to the reference name within the object.

namespacePath required string ​

NamespacePath is the optional relative path to the reference namespace within the object. If omitted or not found, namespacePath equals to the metadata.namespace path of the object.

labels required object ​

Labels treats the path value as a labels selector.

selector required object ​

Selector defines the selector to use for the resource. If not set, all resources of that type will be synced.

matchLabels required object ​
matchExpressions required object[] ​
key required string ​
operator required string ​
values required string[] ​

priorityClasses required object ​

PriorityClasses defines if priority classes classes should get synced from the host cluster to the virtual cluster, but not back.

enabled required boolean false ​

Enabled defines if this option should be enabled.

patches required object[] ​

Patches patch the resource according to the provided specification.

path required string ​

Path is the path within the patch to target. If the path is not found within the patch, the patch is not applied.

expression required string ​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string ​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object ​

Reference treats the path value as a reference to another object and will rewrite it based on the chosen mode automatically. In single-namespace mode this will translate the name to "vxxxxxxxxx" to avoid conflicts with other names, in multi-namespace mode this will not translate the name.

apiVersion required string ​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string ​

APIVersionPath is optional relative path to use to determine the kind. If APIVersionPath is not found, will fallback to apiVersion.

kind required string ​

Kind is the kind of the referenced object.

kindPath required string ​

KindPath is the optional relative path to use to determine the kind. If KindPath is not found, will fallback to kind.

namePath required string ​

NamePath is the optional relative path to the reference name within the object.

namespacePath required string ​

NamespacePath is the optional relative path to the reference namespace within the object. If omitted or not found, namespacePath equals to the metadata.namespace path of the object.

labels required object ​

Labels treats the path value as a labels selector.

selector required object ​

Selector defines the selector to use for the resource. If not set, all resources of that type will be synced.

matchLabels required object ​
matchExpressions required object[] ​
key required string ​
operator required string ​
values required string[] ​

storageClasses required object ​

StorageClasses defines if storage classes should get synced from the host cluster to the virtual cluster, but not back. If auto, is automatically enabled when the virtual scheduler is enabled.

enabled required string|boolean auto ​

Enabled defines if this option should be enabled.

patches required object[] ​

Patches patch the resource according to the provided specification.

path required string ​

Path is the path within the patch to target. If the path is not found within the patch, the patch is not applied.

expression required string ​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string ​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object ​

Reference treats the path value as a reference to another object and will rewrite it based on the chosen mode automatically. In single-namespace mode this will translate the name to "vxxxxxxxxx" to avoid conflicts with other names, in multi-namespace mode this will not translate the name.

apiVersion required string ​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string ​

APIVersionPath is optional relative path to use to determine the kind. If APIVersionPath is not found, will fallback to apiVersion.

kind required string ​

Kind is the kind of the referenced object.

kindPath required string ​

KindPath is the optional relative path to use to determine the kind. If KindPath is not found, will fallback to kind.

namePath required string ​

NamePath is the optional relative path to the reference name within the object.

namespacePath required string ​

NamespacePath is the optional relative path to the reference namespace within the object. If omitted or not found, namespacePath equals to the metadata.namespace path of the object.

labels required object ​

Labels treats the path value as a labels selector.

selector required object ​

Selector defines the selector to use for the resource. If not set, all resources of that type will be synced.

matchLabels required object ​
matchExpressions required object[] ​
key required string ​
operator required string ​
values required string[] ​

csiNodes required object ​

CSINodes defines if csi nodes should get synced from the host cluster to the virtual cluster, but not back. If auto, is automatically enabled when the virtual scheduler is enabled.

enabled required string|boolean auto ​

Enabled defines if this option should be enabled.

patches required object[] ​

Patches patch the resource according to the provided specification.

path required string ​

Path is the path within the patch to target. If the path is not found within the patch, the patch is not applied.

expression required string ​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string ​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object ​

Reference treats the path value as a reference to another object and will rewrite it based on the chosen mode automatically. In single-namespace mode this will translate the name to "vxxxxxxxxx" to avoid conflicts with other names, in multi-namespace mode this will not translate the name.

apiVersion required string ​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string ​

APIVersionPath is optional relative path to use to determine the kind. If APIVersionPath is not found, will fallback to apiVersion.

kind required string ​

Kind is the kind of the referenced object.

kindPath required string ​

KindPath is the optional relative path to use to determine the kind. If KindPath is not found, will fallback to kind.

namePath required string ​

NamePath is the optional relative path to the reference name within the object.

namespacePath required string ​

NamespacePath is the optional relative path to the reference namespace within the object. If omitted or not found, namespacePath equals to the metadata.namespace path of the object.

labels required object ​

Labels treats the path value as a labels selector.

csiDrivers required object ​

CSIDrivers defines if csi drivers should get synced from the host cluster to the virtual cluster, but not back. If auto, is automatically enabled when the virtual scheduler is enabled.

enabled required string|boolean auto ​

Enabled defines if this option should be enabled.

patches required object[] ​

Patches patch the resource according to the provided specification.

path required string ​

Path is the path within the patch to target. If the path is not found within the patch, the patch is not applied.

expression required string ​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string ​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object ​

Reference treats the path value as a reference to another object and will rewrite it based on the chosen mode automatically. In single-namespace mode this will translate the name to "vxxxxxxxxx" to avoid conflicts with other names, in multi-namespace mode this will not translate the name.

apiVersion required string ​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string ​

APIVersionPath is optional relative path to use to determine the kind. If APIVersionPath is not found, will fallback to apiVersion.

kind required string ​

Kind is the kind of the referenced object.

kindPath required string ​

KindPath is the optional relative path to use to determine the kind. If KindPath is not found, will fallback to kind.

namePath required string ​

NamePath is the optional relative path to the reference name within the object.

namespacePath required string ​

NamespacePath is the optional relative path to the reference namespace within the object. If omitted or not found, namespacePath equals to the metadata.namespace path of the object.

labels required object ​

Labels treats the path value as a labels selector.

csiStorageCapacities required object ​

CSIStorageCapacities defines if csi storage capacities should get synced from the host cluster to the virtual cluster, but not back. If auto, is automatically enabled when the virtual scheduler is enabled.

enabled required string|boolean auto ​

Enabled defines if this option should be enabled.

patches required object[] ​

Patches patch the resource according to the provided specification.

path required string ​

Path is the path within the patch to target. If the path is not found within the patch, the patch is not applied.

expression required string ​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string ​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object ​

Reference treats the path value as a reference to another object and will rewrite it based on the chosen mode automatically. In single-namespace mode this will translate the name to "vxxxxxxxxx" to avoid conflicts with other names, in multi-namespace mode this will not translate the name.

apiVersion required string ​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string ​

APIVersionPath is optional relative path to use to determine the kind. If APIVersionPath is not found, will fallback to apiVersion.

kind required string ​

Kind is the kind of the referenced object.

kindPath required string ​

KindPath is the optional relative path to use to determine the kind. If KindPath is not found, will fallback to kind.

namePath required string ​

NamePath is the optional relative path to the reference name within the object.

namespacePath required string ​

NamespacePath is the optional relative path to the reference namespace within the object. If omitted or not found, namespacePath equals to the metadata.namespace path of the object.

labels required object ​

Labels treats the path value as a labels selector.

customResources required {key: object} ​

CustomResources defines what custom resources should get synced read-only to the virtual cluster from the host cluster. vCluster will automatically add any required RBAC to the vCluster cluster role.

enabled required boolean ​

Enabled defines if this option should be enabled.

scope required string ​

Scope defines the scope of the resource

patches required object[] ​

Patches patch the resource according to the provided specification.

path required string ​

Path is the path within the patch to target. If the path is not found within the patch, the patch is not applied.

expression required string ​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string ​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object ​

Reference treats the path value as a reference to another object and will rewrite it based on the chosen mode automatically. In single-namespace mode this will translate the name to "vxxxxxxxxx" to avoid conflicts with other names, in multi-namespace mode this will not translate the name.

apiVersion required string ​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string ​

APIVersionPath is optional relative path to use to determine the kind. If APIVersionPath is not found, will fallback to apiVersion.

kind required string ​

Kind is the kind of the referenced object.

kindPath required string ​

KindPath is the optional relative path to use to determine the kind. If KindPath is not found, will fallback to kind.

namePath required string ​

NamePath is the optional relative path to the reference name within the object.

namespacePath required string ​

NamespacePath is the optional relative path to the reference namespace within the object. If omitted or not found, namespacePath equals to the metadata.namespace path of the object.

labels required object ​

Labels treats the path value as a labels selector.

mappings required object ​

Mappings for Namespace and Object

byName required object ​

ByName is a map of host-object-namespace/host-object-name: virtual-object-namespace/virtual-object-name. There are several wildcards supported:

  1. To match all objects in host namespace and sync them to different namespace in vCluster: byName: "foo/": "foo-in-virtual/"
  2. To match specific object in the host namespace and sync it to the same namespace with the same name: byName: "foo/my-object": "foo/my-object"
  3. To match specific object in the host namespace and sync it to the same namespace with different name: byName: "foo/my-object": "foo/my-virtual-object"
  4. To match all objects in the vCluster host namespace and sync them to a different namespace in vCluster: byName: "": "my-virtual-namespace/*"
  5. To match specific objects in the vCluster host namespace and sync them to a different namespace in vCluster: byName: "/my-object": "my-virtual-namespace/my-object"

volumeSnapshotClasses required object ​

VolumeSnapshotClasses defines if volume snapshot classes created within the virtual cluster should get synced to the host cluster.

enabled required boolean false ​

Enabled defines if this option should be enabled.

patches required object[] ​

Patches patch the resource according to the provided specification.

path required string ​

Path is the path within the patch to target. If the path is not found within the patch, the patch is not applied.

expression required string ​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string ​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object ​

Reference treats the path value as a reference to another object and will rewrite it based on the chosen mode automatically. In single-namespace mode this will translate the name to "vxxxxxxxxx" to avoid conflicts with other names, in multi-namespace mode this will not translate the name.

apiVersion required string ​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string ​

APIVersionPath is optional relative path to use to determine the kind. If APIVersionPath is not found, will fallback to apiVersion.

kind required string ​

Kind is the kind of the referenced object.

kindPath required string ​

KindPath is the optional relative path to use to determine the kind. If KindPath is not found, will fallback to kind.

namePath required string ​

NamePath is the optional relative path to the reference name within the object.

namespacePath required string ​

NamespacePath is the optional relative path to the reference namespace within the object. If omitted or not found, namespacePath equals to the metadata.namespace path of the object.

labels required object ​

Labels treats the path value as a labels selector.

configMaps required object ​

ConfigMaps defines if config maps in the host should get synced to the virtual cluster.

enabled required boolean false ​

Enabled defines if this option should be enabled.

patches required object[] ​

Patches patch the resource according to the provided specification.

path required string ​

Path is the path within the patch to target. If the path is not found within the patch, the patch is not applied.

expression required string ​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string ​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object ​

Reference treats the path value as a reference to another object and will rewrite it based on the chosen mode automatically. In single-namespace mode this will translate the name to "vxxxxxxxxx" to avoid conflicts with other names, in multi-namespace mode this will not translate the name.

apiVersion required string ​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string ​

APIVersionPath is optional relative path to use to determine the kind. If APIVersionPath is not found, will fallback to apiVersion.

kind required string ​

Kind is the kind of the referenced object.

kindPath required string ​

KindPath is the optional relative path to use to determine the kind. If KindPath is not found, will fallback to kind.

namePath required string ​

NamePath is the optional relative path to the reference name within the object.

namespacePath required string ​

NamespacePath is the optional relative path to the reference namespace within the object. If omitted or not found, namespacePath equals to the metadata.namespace path of the object.

labels required object ​

Labels treats the path value as a labels selector.

mappings required object ​

Mappings for Namespace and Object

byName required object {} ​

ByName is a map of host-object-namespace/host-object-name: virtual-object-namespace/virtual-object-name. There are several wildcards supported:

  1. To match all objects in host namespace and sync them to different namespace in vCluster: byName: "foo/": "foo-in-virtual/"
  2. To match specific object in the host namespace and sync it to the same namespace with the same name: byName: "foo/my-object": "foo/my-object"
  3. To match specific object in the host namespace and sync it to the same namespace with different name: byName: "foo/my-object": "foo/my-virtual-object"
  4. To match all objects in the vCluster host namespace and sync them to a different namespace in vCluster: byName: "": "my-virtual-namespace/*"
  5. To match specific objects in the vCluster host namespace and sync them to a different namespace in vCluster: byName: "/my-object": "my-virtual-namespace/my-object"

secrets required object ​

Secrets defines if secrets in the host should get synced to the virtual cluster.

enabled required boolean false ​

Enabled defines if this option should be enabled.

patches required object[] ​

Patches patch the resource according to the provided specification.

path required string ​

Path is the path within the patch to target. If the path is not found within the patch, the patch is not applied.

expression required string ​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string ​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object ​

Reference treats the path value as a reference to another object and will rewrite it based on the chosen mode automatically. In single-namespace mode this will translate the name to "vxxxxxxxxx" to avoid conflicts with other names, in multi-namespace mode this will not translate the name.

apiVersion required string ​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string ​

APIVersionPath is optional relative path to use to determine the kind. If APIVersionPath is not found, will fallback to apiVersion.

kind required string ​

Kind is the kind of the referenced object.

kindPath required string ​

KindPath is the optional relative path to use to determine the kind. If KindPath is not found, will fallback to kind.

namePath required string ​

NamePath is the optional relative path to the reference name within the object.

namespacePath required string ​

NamespacePath is the optional relative path to the reference namespace within the object. If omitted or not found, namespacePath equals to the metadata.namespace path of the object.

labels required object ​

Labels treats the path value as a labels selector.

mappings required object ​

Mappings for Namespace and Object

byName required object {} ​

ByName is a map of host-object-namespace/host-object-name: virtual-object-namespace/virtual-object-name. There are several wildcards supported:

  1. To match all objects in host namespace and sync them to different namespace in vCluster: byName: "foo/": "foo-in-virtual/"
  2. To match specific object in the host namespace and sync it to the same namespace with the same name: byName: "foo/my-object": "foo/my-object"
  3. To match specific object in the host namespace and sync it to the same namespace with different name: byName: "foo/my-object": "foo/my-virtual-object"
  4. To match all objects in the vCluster host namespace and sync them to a different namespace in vCluster: byName: "": "my-virtual-namespace/*"
  5. To match specific objects in the vCluster host namespace and sync them to a different namespace in vCluster: byName: "/my-object": "my-virtual-namespace/my-object"