Secrets

By default, this is enabled.

Sync Secret resources used by pods from the virtual cluster to the host cluster. Apps frequently need secret data to function.

Sync only utilized secrets from virtual to host cluster (Default)

sync:
  toHost:
    secrets:
      enabled: true

Sync all secrets from virtual to host cluster

vCluster only knows about a couple of virtual cluster resources that actually use secrets and tries to sync only those into the host cluster. You can enable syncing all virtual cluster secrets to avoid the problem that needed secrets are not synced to the host cluster.

sync:
  toHost:
    secrets:
      enabled: true
      all: true

Patches

Pro Feature

This feature is available in the vCluster Pro tier. Contact us for more details and to start a trial.

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 metadata.annotations[*] field in vcluster.yaml using the following configuration:

sync:
  toHost:
    secrets:
      enabled: true
      patches:
      - path: metadata.annotations[*]
        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 metadata.annotations[*] 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 metadata.annotations[*] 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.

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:
    secrets:
      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 secrets 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.

Config reference

Do Not Disable

Disabling the syncing of this resource could cause the vCluster to not work properly.

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.

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.