Pods

Supported Configurations

Running the control plane as a container with:

• Shared Nodes

By default, this is enabled.

Sync all Pod resources, including ephemeral containers, from the tenant cluster to the control plane 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:
        - example-key=example-value:NoSchedule
        - another-key: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 tenant cluster are not accessible in the control plane cluster due to registry restrictions or security policies, translateImage can map these to equivalent, permitted images in the control plane cluster's registry.

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

Patches

Use sync.toHost.pods.patches to transform Pod fields, such as spec.containers[*].name, while syncing to the control plane cluster. See Patching synced resources for syntax, directionality, and examples.

Use secrets for ServiceAccount tokens

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

Rewrite hosts

Applies only to Pods that have the field spec.subdomain set. In such Pods, the fqdn hostname (hostname -f) is constructed based on the control plane cluster namespace the vCluster runs in. This is usually not what applications expect as they are unaware of the control plane cluster.

If this option is enabled, vCluster injects an initContainer to override the Pod's /etc/hosts file to change the fqdn hostname to match the expected domain.

Configuration change

In vCluster version 0.27.0, the rewriteHosts.initContainer.image configuration changed from a string to an object format. This change provides granular control over the registry, repository, and tag of the image.

For more information on the new object structure, see the configuration reference.

Config reference

Do Not Disable

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

pods object

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

enabled boolean true

Enabled defines if pod syncing should be enabled.

translateImage object {}

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 string[] []

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

useSecretsForSATokens boolean false

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

runtimeClassName string

RuntimeClassName is the runtime class to set for synced pods.

priorityClassName string

PriorityClassName is the priority class to set for synced pods.

rewriteHosts object

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 boolean true

Enabled specifies if rewriting stateful set pods should be enabled.

initContainer object

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

image object

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

registry string mirror.gcr.io

Registry is the registry of the container image, e.g. my-registry.com or ghcr.io. This setting can be globally overridden via the controlPlane.advanced.defaultImageRegistry option. Empty means docker hub.

repository string library/alpine

Repository is the repository of the container image, e.g. my-repo/my-image

tag string 3.20

Tag is the tag of the container image, and is the default version.

resources object

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

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

Limits are resource limits for the container

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

Requests are minimal resources that will be consumed by the container

patches 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 string

Expression transforms the value according to the given JavaScript expression.

reverseExpression string

ReverseExpression transforms the value according to the given JavaScript expression.

reference 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 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 string

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

namePath string

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

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

Labels treats the path value as a labels selector.

hybridScheduling object

HybridScheduling is used to enable and configure hybrid scheduling for pods in the virtual cluster.

enabled boolean false

Enabled specifies if hybrid scheduling is enabled.

hostSchedulers string[] []

HostSchedulers is a list of schedulers that are deployed on the host cluster.