Pods

By default, this is enabled.

Sync all Pod resources, including ephemeral containers, from the virtual cluster to the host cluster.

Automatically apply tolerations to all pods synced by vCluster

Kubernetes has a concept of Taints and Tolerations, which is used for controlling scheduling. If you have a use case that requires vCluster to sync all pods and automatically set a toleration on those pods, then you can achieve this with the enforceTolerations option. You can pass multiple toleration expressions, and the syncer adds them to every new pod that vCluster syncs.

sync:
  toHost:
    pods:
      enabled: true
      enforceTolerations:
        - key: "example-key"
          operator: "Equal"
          value: "example-value"
          effect: "NoSchedule"
        - key: "another-key"
          operator: "Exists"
          effect: "PreferNoSchedule"

info

vCluster does not support setting the tolerationSeconds field of a toleration. If your use case requires this, open an issue in the vCluster repo on GitHub.

Replace container images when pods are synced

If certain images used within the virtual cluster are not accessible in the host cluster due to registry restrictions or security policies, translateImage can map these to equivalent, permitted images in the host cluster's registry.

sync:
  toHost:
    pods:
      enabled: true
      translateImage:
        "virtualcluster/image:tag": "hostcluster/alternative-image:tag"

Translate Patches

Pro Feature

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

You can modify the sync behaviour with translate patches that target specific paths. Currently there is 2 different kinds of patches supported.

Wildcard patches

You can use * in paths to select all entries of an array or object, e.g. spec.containers[*].name or spec.containers[*].volumeMounts[*]. vCluster will then just call the patch multiple times.

JavaScript Expressions

These are powerful JavaScript ES6 compatible expressions to change a field while syncing. You can define how it should changed when syncing from the vCluster into the host cluster or when syncing from the host cluster into the virtual cluster. To change the path spec.containers[*].name you can do:

sync:
  toHost:
    pods:
      enabled: true
      translate:
      - path: spec.containers[*].name
        expression:
          toHost: '"my-prefix"+value'
          # optional fromHost, if omitted patches fromHost will be discarded
          # fromHost: 'value.slice("my-prefix".length)'

There is also a variable called context besides value that can be used to access vCluster specific data:

• context.vcluster.name: Name of the vCluster
• context.vcluster.namespace: Namespace of the vCluster
• context.vcluster.config: Config of the vCluster, basically vcluster.yaml merged with the defaults
• context.hostObject: Host object (can be null if not available)
• context.virtualObject: Virtual object (can be null if not available)
• context.path: The matched path on the object, useful when using wildcard path selectors (*)

Reference patches

Tell vCluster that this specific field points to a different resource that should get rewritten. vCluster will also automatically import the referenced resource if it can find it in the host cluster. For example:

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

This will tell vCluster to translate the path metadata.annotations["my-secret-ref"] as it points to a secret. If the secret is created in the host cluster, vCluster will automatically import it.

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.

Use secrets for ServiceAccount tokens

A host Pod requires a ServiceAccount token to communicate with the virtual clusters API. If you don't want to create these secrets in the host cluster, disable this option. vCluster then adds annotations to the pods.

Config reference

Do Not Disable

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

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

Expression transforms the value according to the given JavaScript expression.

toHost required string pro

ToHost is the expression to apply when retrieving a change from virtual to host.

fromHost required string pro

FromHost is the patch to apply when retrieving a change from host to virtual.

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.