Skip to main content
Version: main 🚧

Sync

A virtual cluster does not have actual worker nodes or a network. Instead, the vCluster syncer component replicates the pods that are created within the virtual cluster to the host cluster. Subsequently, the host cluster schedules the pods, and the syncer keeps the virtual cluster pods and host cluster pods in sync.

By default, vCluster runs with a minimal set of RBAC permissions to allow execution in restricted environments. Certain resources require extra permissions to sync, which will automatically be given to the vCluster ServiceAccount if you enable the resource sync with the associated config value.

Sync from Virtual Cluster to Host Cluster​

vCluster can sync certain resources from the virtual cluster to the host cluster and back. These resources are typically created within the virtual cluster and are expected to be changeable within the virtual cluster. These are typically namespace-scoped resources (although exceptions exist) such as Pods, Secrets, ConfigMaps, Services etc.

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

Enabled by Default​

Disabled by Default​

Sync from Host Cluster to Virtual Cluster​

vCluster can sync certain resources purely from host to make them available inside the vCluster. This is useful if you only want to view certain resources in read-only mode, but not want the users inside the vCluster to change them.

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

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

Enabled by Default​

Disabled by Default​

How does syncing work?​

Syncing is the process where vCluster copies a resource between the virtual cluster and the host cluster. It's the basic principle vCluster uses to emulate a fully functional Kubernetes cluster.

vCluster only syncs low-level resources by default, such as pods, secrets, configmaps or services. As soon as one of these resources are created in the virtual cluster, vCluster will sync it to the other side. As soon as a resource was copied by vCluster, it will start watching for changes to the resource on either side, so when a controller changes something on the host cluster side, the vCluster will sync that change to the virtual cluster or when a change on the virtual cluster side happens, it will sync it to the host cluster, to make sure the resource is in sync.

Let's take Ingress as an example. A user that creates the following ingress in the virtual cluster:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx
spec:
  tls:
  - hosts:
      - https-example.foo.com
    secretName: testsecret-tls
  rules:
  - http:
      paths:
      - path: /
        pathType: ImplementationSpecific
        backend:
          service:
            name: nginx
            port:
              number: 80

When copying to the host cluster, the vCluster will change the ingress to:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    vcluster.loft.sh/object-host-name: nginx-x-default-x-vcluster
    vcluster.loft.sh/object-host-namespace: vcluster
    vcluster.loft.sh/object-kind: networking.k8s.io/v1, Kind=Ingress
    vcluster.loft.sh/object-name: nginx
    vcluster.loft.sh/object-namespace: default
    vcluster.loft.sh/object-uid: bb8bea39-8c0c-4295-8616-6a20b3b1900a
  labels:
    vcluster.loft.sh/managed-by: vcluster
    vcluster.loft.sh/namespace: default
  name: nginx-x-default-x-vcluster
  namespace: vcluster
spec:
  rules:
  - http:
      paths:
      - backend:
          service:
            name: nginx-x-default-x-vcluster
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
  tls:
  - hosts:
    - https-example.foo.com
    secretName: testsecret-tls-x-default-x-vcluster

There is a couple of important changes to be noticed:

  • Name Rewritten: vCluster rewrites the name of the resource to avoid conflicts in the host cluster. The name is rewritten in the form of NAME-x-NAMESPACE-x-VCLUSTER_NAME
  • Namespace Rewritten: vCluster rewrites the namespace of the resource to sync everything into the vcluster's namespace.
  • Annotations / Labels Added: vCluster adds annotations and labels to identify the resource in the host cluster.
  • References Rewritten: vCluster rewrites the spec.rules[*].http.paths[*].backend.service.name and spec.tls[*].secretName to match the rewritten names of the resources in the host cluster.

vCluster will also keep track from now of the resource within its internal name cache, that tracks the VIRTUAL NAME <-> HOST NAME as well as all references used by this resource. In the ingress case, this would be the service nginx and the secret testsecret-tls. Tracking references helps the vCluster to understand what resources are still needed in the host cluster. For secrets and configmaps this is important, because by default only the needed ones are actually synced to the host cluster.

Config reference​

sync required object pro​

Sync describes how to sync resources from the virtual cluster to host cluster and back.

toHost required object pro​

Configure resources to sync from the virtual cluster to the host cluster.

pods required object pro​

Pods defines if pods created within the virtual cluster should get synced to the host cluster.

enabled required boolean true pro​

Enabled defines if pod syncing should be enabled.

translateImage required object {} pro​

TranslateImage maps an image to another image that should be used instead. For example this can be used to rewrite a certain image that is used within the virtual cluster to be another image on the host cluster

enforceTolerations required string[] [] pro​

EnforceTolerations will add the specified tolerations to all pods synced by the virtual cluster.

useSecretsForSATokens required boolean false pro​

UseSecretsForSATokens will use secrets to save the generated service account tokens by virtual cluster instead of using a pod annotation.

rewriteHosts required object pro​

RewriteHosts is a special option needed to rewrite statefulset containers to allow the correct FQDN. virtual cluster will add a small container to each stateful set pod that will initially rewrite the /etc/hosts file to match the FQDN expected by the virtual cluster.

enabled required boolean true pro​

Enabled specifies if rewriting stateful set pods should be enabled.

initContainer required object pro​

InitContainer holds extra options for the init container used by vCluster to rewrite the FQDN for stateful set pods.

image required string library/alpine:3.20 pro​

Image is the image virtual cluster should use to rewrite this FQDN.

resources required object pro​

Resources are the resources that should be assigned to the init container for each stateful set init container.

limits required object map[cpu:30m memory:64Mi] pro​

Limits are resource limits for the container

requests required object map[cpu:30m memory:64Mi] pro​

Requests are minimal resources that will be consumed by the container

translate required object[] pro​

Translate the patch according to the given patches.

path required string pro​

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 pro​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string pro​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object pro​

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 pro​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string pro​

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

kind required string pro​

Kind is the kind of the referenced object.

kindPath required string pro​

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

namePath required string pro​

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

namespacePath required string pro​

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 pro​

Labels treats the path value as a labels selector.

secrets required object pro​

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

enabled required boolean true pro​

Enabled defines if this option should be enabled.

all required boolean false pro​

All defines if all resources of that type should get synced or only the necessary ones that are needed.

translate required object[] pro​

Translate the patch according to the given patches.

path required string pro​

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 pro​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string pro​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object pro​

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 pro​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string pro​

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

kind required string pro​

Kind is the kind of the referenced object.

kindPath required string pro​

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

namePath required string pro​

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

namespacePath required string pro​

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 pro​

Labels treats the path value as a labels selector.

configMaps required object pro​

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

enabled required boolean true pro​

Enabled defines if this option should be enabled.

all required boolean false pro​

All defines if all resources of that type should get synced or only the necessary ones that are needed.

translate required object[] pro​

Translate the patch according to the given patches.

path required string pro​

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 pro​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string pro​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object pro​

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 pro​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string pro​

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

kind required string pro​

Kind is the kind of the referenced object.

kindPath required string pro​

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

namePath required string pro​

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

namespacePath required string pro​

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 pro​

Labels treats the path value as a labels selector.

ingresses required object pro​

Ingresses defines if ingresses created within the virtual cluster should get synced to the host cluster.

enabled required boolean false pro​

Enabled defines if this option should be enabled.

translate required object[] pro​

Translate the patch according to the given patches.

path required string pro​

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 pro​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string pro​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object pro​

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 pro​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string pro​

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

kind required string pro​

Kind is the kind of the referenced object.

kindPath required string pro​

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

namePath required string pro​

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

namespacePath required string pro​

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 pro​

Labels treats the path value as a labels selector.

services required object pro​

Services defines if services created within the virtual cluster should get synced to the host cluster.

enabled required boolean true pro​

Enabled defines if this option should be enabled.

translate required object[] pro​

Translate the patch according to the given patches.

path required string pro​

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 pro​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string pro​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object pro​

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 pro​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string pro​

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

kind required string pro​

Kind is the kind of the referenced object.

kindPath required string pro​

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

namePath required string pro​

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

namespacePath required string pro​

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 pro​

Labels treats the path value as a labels selector.

endpoints required object pro​

Endpoints defines if endpoints created within the virtual cluster should get synced to the host cluster.

enabled required boolean true pro​

Enabled defines if this option should be enabled.

networkPolicies required object pro​

NetworkPolicies defines if network policies created within the virtual cluster should get synced to the host cluster.

enabled required boolean false pro​

Enabled defines if this option should be enabled.

persistentVolumeClaims required object pro​

PersistentVolumeClaims defines if persistent volume claims created within the virtual cluster should get synced to the host cluster.

enabled required boolean true pro​

Enabled defines if this option should be enabled.

translate required object[] pro​

Translate the patch according to the given patches.

path required string pro​

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 pro​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string pro​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object pro​

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 pro​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string pro​

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

kind required string pro​

Kind is the kind of the referenced object.

kindPath required string pro​

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

namePath required string pro​

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

namespacePath required string pro​

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 pro​

Labels treats the path value as a labels selector.

persistentVolumes required object pro​

PersistentVolumes defines if persistent volumes created within the virtual cluster should get synced to the host cluster.

enabled required boolean false pro​

Enabled defines if this option should be enabled.

volumeSnapshots required object pro​

VolumeSnapshots defines if volume snapshots created within the virtual cluster should get synced to the host cluster.

enabled required boolean false pro​

Enabled defines if this option should be enabled.

storageClasses required object pro​

StorageClasses defines if storage classes created within the virtual cluster should get synced to the host cluster.

enabled required boolean false pro​

Enabled defines if this option should be enabled.

serviceAccounts required object pro​

ServiceAccounts defines if service accounts created within the virtual cluster should get synced to the host cluster.

enabled required boolean false pro​

Enabled defines if this option should be enabled.

podDisruptionBudgets required object pro​

PodDisruptionBudgets defines if pod disruption budgets created within the virtual cluster should get synced to the host cluster.

enabled required boolean false pro​

Enabled defines if this option should be enabled.

priorityClasses required object pro​

PriorityClasses defines if priority classes created within the virtual cluster should get synced to the host cluster.

enabled required boolean false pro​

Enabled defines if this option should be enabled.

customResources required {key: object} pro​

CustomResources defines what custom resources should get synced from the virtual cluster to the host cluster. vCluster will copy the definition automatically from host cluster to virtual cluster on startup. vCluster will also automatically add any required RBAC permissions to the vCluster role for this to work.

enabled required boolean pro​

Enabled defines if this option should be enabled.

translate required object[] pro​

Translate the patch according to the given patches.

path required string pro​

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 pro​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string pro​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object pro​

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 pro​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string pro​

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

kind required string pro​

Kind is the kind of the referenced object.

kindPath required string pro​

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

namePath required string pro​

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

namespacePath required string pro​

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 pro​

Labels treats the path value as a labels selector.

fromHost required object pro​

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

nodes required object pro​

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

enabled required boolean false pro​

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

syncBackChanges required boolean false pro​

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 pro​

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

selector required object pro​

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 pro​

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 {} pro​

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.

events required object pro​

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

enabled required boolean true pro​

Enabled defines if this option should be enabled.

ingressClasses required object pro​

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

enabled required boolean false pro​

Enabled defines if this option should be enabled.

runtimeClasses required object pro​

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

enabled required boolean false pro​

Enabled defines if this option should be enabled.

priorityClasses required object pro​

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

enabled required boolean false pro​

Enabled defines if this option should be enabled.

storageClasses required object pro​

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 pro​

Enabled defines if this option should be enabled.

csiNodes required object pro​

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 pro​

Enabled defines if this option should be enabled.

csiDrivers required object pro​

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 pro​

Enabled defines if this option should be enabled.

csiStorageCapacities required object pro​

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 pro​

Enabled defines if this option should be enabled.

customResources required {key: object} pro​

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 pro​

Enabled defines if this option should be enabled.