Skip to main content
Version: main 🚧

Nodes

This is disabled by default.

vCluster syncs pseudo nodes from the host cluster where there are virtual cluster pods running. Pseudo nodes only have real values for the CPU, architecture, and operating system, while everything else is randomly generated. A single pseudo node can either represent a single real node on the host cluster, or it can represent multiple real nodes. If there are no more pods on a node, vCluster deletes the pseudo node.

However, when you need to access specific node information, you can choose to sync real nodes from the host cluster to the virtual cluster. This requires a cluster role.

Node IP obfuscation

By default, vCluster obfuscates node IP addresses when syncing real nodes to protect sensitive information. Learn how to control node IP visibility for your use case.

Sync pseudo nodes (default)​

Sync pseudo nodes​

Sync pseudo nodes to the virtual cluster. This is enabled by default. This default configuration does not require a cluster role.

sync:
  fromHost:
    nodes:
      enabled: false

vCluster ignores the selector.all and selector.labels fields. However, if a pod is created with spec.nodeSelector, the syncer generates a pseudo node in the virtual cluster. This pseudo node includes annotations and labels from the real node, allowing the pod's node selector to match a corresponding node within the virtual cluster.

For more information, see the Kubernetes documentation on spec.nodeSelector.

Sync real nodes​

Sync real nodes to the virtual cluster where virtual cluster pods are running:

sync:
  fromHost:
    nodes:
      enabled: true

Sync pseudo nodes with label selector​

Sync pseudo nodes that match a given label selector. This example sets the node selector to the same values when syncing a pod from virtual cluster to host cluster:

sync:
  fromHost:
    nodes:
      enabled: false
      selector:
        labels:
          environment: production
          team: backend

Sync real nodes with label selector​

Sync real nodes that match a given label selector. This example sets the node selector to the same values when syncing a pod from virtual cluster to host cluster:

sync:
  fromHost:
    nodes:
      enabled: true
      selector:
        labels:
          environment: production
          team: backend

Sync all real nodes​

Sync all real nodes, regardless of whether a virtual cluster pod is running on it or not:

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

Sync real nodes and sync back labels and taints​

Enable syncing real nodes from the host cluster to the virtual cluster as well as syncing back from the virtual cluster any changes to node labels and taints. Enabling this adds RBAC permissions to the syncer component to allow it to modify the host nodes and statuses.

sync:
  fromHost:
    nodes:
      enabled: true
      syncBackChanges: true

Sync real nodes and hide image information​

Enable syncing real nodes. This clears all status.images from the node when it is synced to the virtual cluster. For certain multi-tenant use cases, such as multi-customer tenancy, images can leak sensitive information about a node.

sync:
  fromHost:
    nodes:
      enabled: true
      clearImageStatus: true

Node sync configuration options​

nodes.enabled:

  • Covered in the general syncer configuration documentation
  • Required to schedule any pods in the virtual cluster.
  • Can be disabled in the control plane vCluster when using isolated control planes, where all workloads are instead scheduled in the workload vCluster (which should have node syncing enabled).

nodes.syncBackChanges:

  • Replaces the deprecated --sync-node-changes flag.
  • Enables syncing of labels and taints from virtual cluster nodes back to host cluster nodes.
  • Requires additional RBAC permissions to modify Node and Node/status resources in the host cluster.

nodes.clearImageStatus:

  • Controls the --node-clear-image-status flag.
  • Clears the status.images field from node objects to prevent leaking container image metadata.
  • Useful in multi-tenant environments to reduce exposure of underlying node-level information.

nodes.selector.all:

  • Sets the --sync-all-nodes syncer flag.
  • When enabled, syncs all nodes from the host cluster into the virtual cluster.

nodes.selector.labels:

  • Selects specific node labels to sync into the virtual cluster.
  • Allows control over which host nodes the vCluster sees or can schedule workloads to.
  • Example use cases include:
    • Restrict vCluster to nodes in a specific region.
    • Target nodes with a particular architecture.
    • Use only spot or preemptible instances.
    • Prevent vCluster workloads from running on critical infrastructure nodes.

Patches​

Enterprise-Only Feature

This feature is an Enterprise feature. See our pricing plans or contact our sales team for more information.

Patches override the default resource syncing rules in your vCluster yaml configurations.

By default, vCluster syncs specific resources between virtual and host clusters. To modify the sync behavior, you can use patches to specify which fields to edit, exclude, or override during syncing.

For example, vCluster can mirror resources from the virtual cluster to the host cluster—any changes made in the virtual cluster are automatically applied to the host cluster. The same applies in the other direction if syncing is set up from host to virtual cluster.

vCluster supports two patch types:

  • JavaScript expression patch: Uses JavaScript ES6 expressions to dynamically modify fields during syncing. You can define how a field changes when syncing from a virtual cluster to a host cluster, or from a host cluster to a virtual cluster.
  • Reference patch: Modifies specific fields within a resource to point to different resources. If the referenced resource exists in the host cluster, vCluster automatically imports it into the virtual cluster. If the referenced resource exists in the virtual cluster and syncing is configured, vCluster can import it into the host cluster.
Using wildcards in patches

You can apply a wildcard, using an asterisk (*) in a specified path, to modify all elements of an array or object. For instance, spec.containers[*].name selects the name field of every container in the spec.containers array, and spec.containers[*].volumeMounts[*] selects all volumeMounts for each container. When using the asterisk (*) notation, vCluster applies changes individually to every element that matches the path.

JavaScript expression patch​

A JavaScript expression patch allows you to use JavaScript ES6 expressions to change specific fields when syncing between virtual and host clusters. This is useful when modifying resource configurations to align with differing environments or naming conventions between clusters. If your clusters use different container name prefixes, a JavaScript expression patch can automatically update them.

You can define a path for status.nodeInfo.operatingSystem field in vcluster.yaml using the following configuration:

sync:
fromHost:
  nodes:
    enabled: true
    patches:
    - path: status.nodeInfo.operatingSystem
      expression: '"my-prefix-"+value'
      # optional reverseExpression to reverse the change from the host cluster
      # reverseExpression: 'value.slice("my-prefix".length)'

In the example:

  • The path targets the status.nodeInfo.operatingSystem field to override when syncing to the host cluster. The * wildcard applies the patch to each container individually.
  • "'my-prefix-' + value" defines a JavaScript expression that prepends "my-prefix-" to the status.nodeInfo.operatingSystem field in the host cluster.
Reverse sync

You can use the reverseExpression field to define how to revert changes when syncing from the host cluster back to the virtual cluster. For example, add reverseExpression: {"value.slice('my-prefix'.length)"} to vcluster.yaml to remove the "my-prefix-" prefix when syncing back from the host cluster to the virtual cluster in the previous example.

To replace value with a hardcoded one, put the desired value in the quotation marks:

sync:
fromHost:
  nodes:
    enabled: true
    patches:
    - path: status.nodeInfo.operatingSystem
      expression: '"my-value"'

Context variable​

The context variable is an object supported in JavaScript expression patches, that provides access to virtual cluster data during syncing. The context object includes the following properties:

  • context.vcluster.name: Name of the virtual cluster.
  • context.vcluster.namespace: Namespace of the virtual cluster.
  • context.vcluster.config: Configuration of the virtual cluster, basically vcluster.yaml merged with the defaults.
  • context.hostObject: Host object (null if not available).
  • context.virtualObject: Virtual object (null if not available).
  • context.path: Matched path on the object, useful when using wildcard path selectors (*).

Reference patch​

A reference patch links a field in one resource to another resource. During syncing, vCluster updates the reference and imports the linked resource from the virtual cluster to the host cluster or from the host cluster to the virtual cluster, depending on the sync direction and whether the resource exists.

You can use reference patches to share resources, such as Secrets or ConfigMaps, between clusters without manually recreating or duplicating them.

For example, if the host cluster contains a secret named "my-example-secret", vCluster automatically imports it into the virtual cluster.

Workloads in the virtual cluster can then use the secret without manual syncing.

You can sync between the virtual cluster and the host cluster by mapping spec.secretName to a secret in the host cluster:

sync:
toHost:
  nodes:
    enabled: true
    patches:
    - path: metadata.annotations["my-secret-ref"]
      reference:
        apiVersion: v1
        kind: Secret

In the example:

  • The code uses a patch to add metadata.annotations["my-secret-ref"]
  • It references a Secret in the host cluster using the patch and ensures nodes in the host cluster links to the correct Secret.
Multi namespace mode

With multi-namespace mode you only need to rewrite references that include a namespace. You can use the namespacePath option to specify the path of the namespace of the reference.

For more advanced use cases, such as controlling node IP visibility, see the control node IP visibility guide.

Config reference​

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.

patches required object[] pro​

Patches patch the resource according to the provided specification.

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.