Nodes

Limited vCluster Tenancy Configuration Support

This feature is only available when using the following worker node types:

Host Nodes

By default, this is disabled by default. vCluster only displays nodes in the virtual cluster if the virtual cluster has synced pods to that worker node from the host. If there are no more pods on a node, vCluster deletes the node. Without syncing the nodes, these nodes are considered pseudo nodes as the name is the only real value, and the rest of the nod information is randomly generated.

If you need specific node informatin, enabling to sync nodes from the host will allow the real information from the node to be available from the virtual cluster context. In order to access node informatin, a cluster role is deployed onto the host cluster.

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.

Selecting a set of nodes

By default, vCluster is able to schedule pods to any of the worker nodes in the host cluster, but you can isolate a virtual cluster to only use a set of specific nodes from the host cluster. There are multiple reasons why you may want to dedicate nodes to a virtual cluster including:

• Restricting vCluster to nodes in a specific region.
• Targeting nodes with a particular architecture.
• Using only spot or preemptible instances.
• Preventing vCluster workloads from running on critical infrastructure nodes.

Selecting nodes is based on a node label selector, where the nodes on the host cluster must have the matching labels.

Select a set of nodes without syncing node information

If you don't want to sync node information, you can still select to use only a set of nodes from the host cluster.

Select dedicated nodes without syncing real node information

sync:
  fromHost:
    nodes:
      # Do not sync real node information
      enabled: false
      # Select a set of nodes based on the node labels
      selector:
        labels:
          environment: production
          team: backend

Select a set of nodes and sync node information

You can select a set of nodes from the host cluster while also requesting that the nodes sync with the real information from the host cluster.

Select dedicated nodes and syncing real node information

sync:
  fromHost:
    nodes:
      # Sync real node information
      enabled: true
      # Select a set of nodes based on the node labels
      selector:
        labels:
          environment: production
          team: backend

Sync real nodes

Sync nodes to the virtual cluster in order to view real node information. The virtual cluster will only display the host nodes that have a pod deployed onto it. By enabling this sync, a cluster role is deployed by the vCluster onto the host cluster.

Sync nodes for real node information

sync:
  fromHost:
    nodes:
      enabled: true

Sync all real nodes

When syncing nodes, only nodes that have pods deployed on them will show up in the virtual cluster, but you can sync all the nodes from the host cluster. When selecting all the nodes, kubectl get nodes will display all the host nodes whether or not a pod has been scheduled onto the host cluster.

Make all nodes visible to the virtual cluster

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

Sync back labels and taints

By default, when syncing nodes from the host cluster, labels and taints are only synced from the host cluster to the virtual cluster. No changes from the virtual cluster context would be reflected on the host nodes.

Enabling syncBackChanges allows labels and taints set from the virtual cluster context to be synced to the host nodes. Additional permissions are added to the cluster role in order to edit the host nodes.

Sync labels and taints from the virtual cluster context to the host node

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

Hide image information

When multiple tenants are using the same set of host nodes, container image metadata could be used maliciously. For increased security, you can enable clearImageStatus to remove all status.images from the node object.

Clear Image Status on the Node

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

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.

JavaScript Runtime

vCluster uses Goja, a pure Go implementation of ECMAScript, to evaluate JavaScript expressions. This provides a secure, sandboxed environment for executing your patch expressions. Refer to Goja's documentation for details on supported JavaScript features and limitations.

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.

Patch path validation

If the path in a patch references a field where the parent object is null or doesn't exist, vCluster logs an error in the vCluster container but it does not block the synchronization to the host. For example, if you specify path: spec.template.metadata.labels["my-label"] but spec.template is null, the patch fails and you'll see an error in the vCluster logs.

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"'

Adding new keys in maps like annotations or labels to the resource is also possible with expressions. For example, to add a label to the resource in the host cluster, you can use:

sync:
  toHost:
    nodes:
      enabled: true
      patches:
      - path: metadata.label["my-new-label"]
        expression: 'valueExists ? value + "-changed" : "new-label-value"'

The value variable in the case where the map entry does not exist is null. To distinguish between an entry that does not exist and an entry that exists with a null value, you can use the valueExists variable in your expression. The valueExists variable is true if the entry exists in the map, even if its value is null.

The keys can also be conditionally added based on the value returned by the expression. If the expression evaluates to null, the key is not added to the map. Here is an example of conditionally adding a label based on the existence of another label:

sync:
  toHost:
    nodes:
      enabled: true
      patches:
      - path: metadata.labels["conditional-label"]
        expression: "context.virtualObject.metadata?.label?.['my-label'] ? 'my-value' : null"

The above example checks if the my-label label exists in the virtual object. If it does, it adds the conditional-label with the value my-value. If it does not exist, it does not add the label.

JavaScript expressions

The JavaScript expression patch supports a limited set of JavaScript features. For example, it does not support import statements or other Node.js-specific features. You can use standard JavaScript expressions, functions, and operators. The expression is evaluated in a sandboxed environment, so it cannot access external resources or the host system. Also, the JavaScript expression must be a valid ES6 expression. This means it should not contain any statements, only expressions that return a value.

A common use is to use ternary operators to conditionally modify values based on their existence or other criteria. Another common use is the optional chaining operator like in: value.myfield?.anotherfield || "default-value".

Additional functions available:

• atob(encodedData): Decodes a base64-encoded string and returns the decoded string. Ex: atob("bXktdmFsdWU=") returns my-value.
• btoa(stringToEncode): Encodes a string in base64 and returns the encoded string. Ex: btoa("my-value") returns bXktdmFsdWU=.

These functions are useful for encoding/decoding values when syncing between clusters:

sync:
  toHost:
    nodes:
      enabled: true
      patches:
      - path: metadata.annotations["encoded-value"]
        expression: 'btoa(value)'
      - path: metadata.annotations["decoded-value"]
        expression: 'atob(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.

::: Reference Patches with Namespace Syncing If you have enabled syncing namespaces, reference patches are only required if the namespace is part of the patch. You can use the namespacePath option to specify the path of the namespace of the reference. :::

Config reference

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.