vcluster.yaml configuration reference
Create a virtual cluster with a config file
If you are moving from vCluster 0.19.x to 0.20+, see the conversion guide for how to automatically convert your existing values.yaml
configuration file to the new vcluster.yaml
format.
Configure your vCluster installation in a vcluster.yaml
configuration file. Then deploy your changes.
- vCluster CLI
- Helm
- kubectl
- Terraform
- Argo CD
- Cluster API
vcluster create --upgrade VCLUSTER_NAME -n VCLUSTER_NAMESPACE -f vcluster.yaml
Replace:
VCLUSTER_NAME
with your vCluster instance name.VCLUSTER_NAMESPACE
with the namespace where you deployed vCluster.
helm upgrade --install VCLUSTER_NAME vcluster \
--values vcluster.yaml \
--repo https://charts.loft.sh \
--namespace VCLUSTER_NAMESPACE \
--repository-config=''
Replace:
VCLUSTER_NAME
with your vCluster instance name.VCLUSTER_NAMESPACE
with the namespace where you deployed vCluster.
helm template VCLUSTER_NAME vcluster --repo https://charts.loft.sh -n VCLUSTER_NAMESPACE -f vcluster.yaml | kubectl apply -f -
Replace:
VCLUSTER_NAME
with your vCluster instance name.VCLUSTER_NAMESPACE
with the namespace where you deployed vCluster.
Apply vCluster config changes by editing the vcluster.yaml
file and running terraform plan
:
terraform plan
Review the planned changes and apply them if they look appropriate:
terraform apply
Add your vcluster.yaml
config file to the valueFiles
array in your ArgoCD Application
file.
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: VCLUSTER_NAME
namespace: argocd
spec:
project: default
source:
chart: vcluster
repoURL: https://charts.loft.sh
helm:
releaseName: VCLUSTER_NAME
valueFiles:
- vcluster.yaml
destination:
server: https://kubernetes.default.svc
namespace: VCLUSTER_NAMESPACE
Replace:
VCLUSTER_NAME
with your vCluster instance name.VCLUSTER_NAMESPACE
with the namespace where you deployed vCluster.
Apply Cluster API changes by regenerating the cluster custom resource using clusterctl
.
export CLUSTER_NAME=VCLUSTER_NAME
export CLUSTER_NAMESPACE=VCLUSTER_NAMESPACE
export KUBERNETES_VERSION=1.29.3
export HELM_VALUES=$(cat vcluster.yaml)
clusterctl generate cluster ${CLUSTER_NAME} \
--infrastructure vcluster \
--kubernetes-version ${KUBERNETES_VERSION} \
--target-namespace ${CLUSTER_NAMESPACE} | kubectl apply -f -
Replace:
VCLUSTER_NAME
with your vCluster instance name.VCLUSTER_NAMESPACE
with the namespace where you deployed vCluster.
After the changes have been applied, wait for the vCluster custom resource to report a ready status:
kubectl wait --for=condition=ready vcluster -n $CLUSTER_NAMESPACE $CLUSTER_NAME --timeout=300s
Config reference
exportKubeConfig
required object pro
ExportKubeConfig describes how vCluster should export the vCluster kubeConfig file.
exportKubeConfig
required object procontext
required string pro
Context is the name of the context within the generated kubeconfig to use.
context
required string proserver
required string pro
Override the default https://localhost:8443 and specify a custom hostname for the generated kubeconfig.
server
required string prosecret
required object pro
Declare in which host cluster secret vCluster should store the generated virtual cluster kubeconfig.
If this is not defined, vCluster create it with vc-NAME
. If you specify another name,
vCluster creates the config in this other secret.
secret
required object provc-NAME
. If you specify another name,
vCluster creates the config in this other secret.name
required string pro
Name is the name of the secret where the kubeconfig should get stored.
name
required string pronamespace
required string pro
Namespace where vCluster should store the kubeconfig secret. If this is not equal to the namespace
where you deployed vCluster, you need to make sure vCluster has access to this other namespace.
namespace
required string prosync
required object pro
Sync describes how to sync resources from the virtual cluster to host cluster and back.
sync
required object protoHost
required object pro
Configure resources to sync from the virtual cluster to the host cluster.
toHost
required object propods
required object pro
Pods defines if pods created within the virtual cluster should get synced to the host cluster.
pods
required object proenabled
required boolean false pro
Enabled defines if pod syncing should be enabled.
enabled
required boolean false protranslateImage
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
translateImage
required object proenforceTolerations
required string[] pro
EnforceTolerations will add the specified tolerations to all pods synced by the virtual cluster.
enforceTolerations
required string[] prouseSecretsForSATokens
required boolean false pro
UseSecretsForSATokens will use secrets to save the generated service account tokens by virtual cluster instead of using a
pod annotation.
useSecretsForSATokens
required boolean false prorewriteHosts
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.
rewriteHosts
required object proenabled
required boolean false pro
Enabled specifies if rewriting stateful set pods should be enabled.
enabled
required boolean false proinitContainer
required object pro
InitContainer holds extra options for the init container used by vCluster to rewrite the FQDN for stateful set pods.
initContainer
required object prosecrets
required object pro
Secrets defines if secrets created within the virtual cluster should get synced to the host cluster.
secrets
required object proconfigMaps
required object pro
ConfigMaps defines if config maps created within the virtual cluster should get synced to the host cluster.
configMaps
required object proingresses
required object pro
Ingresses defines if ingresses created within the virtual cluster should get synced to the host cluster.
ingresses
required object proenabled
required boolean false pro
Enabled defines if this option should be enabled.
enabled
required boolean false proservices
required object pro
Services defines if services created within the virtual cluster should get synced to the host cluster.
services
required object proenabled
required boolean false pro
Enabled defines if this option should be enabled.
enabled
required boolean false proendpoints
required object pro
Endpoints defines if endpoints created within the virtual cluster should get synced to the host cluster.
endpoints
required object proenabled
required boolean false pro
Enabled defines if this option should be enabled.
enabled
required boolean false pronetworkPolicies
required object pro
NetworkPolicies defines if network policies created within the virtual cluster should get synced to the host cluster.
networkPolicies
required object proenabled
required boolean false pro
Enabled defines if this option should be enabled.
enabled
required boolean false propersistentVolumeClaims
required object pro
PersistentVolumeClaims defines if persistent volume claims created within the virtual cluster should get synced to the host cluster.
persistentVolumeClaims
required object proenabled
required boolean false pro
Enabled defines if this option should be enabled.
enabled
required boolean false propersistentVolumes
required object pro
PersistentVolumes defines if persistent volumes created within the virtual cluster should get synced to the host cluster.
persistentVolumes
required object proenabled
required boolean false pro
Enabled defines if this option should be enabled.
enabled
required boolean false provolumeSnapshots
required object pro
VolumeSnapshots defines if volume snapshots created within the virtual cluster should get synced to the host cluster.
volumeSnapshots
required object proenabled
required boolean false pro
Enabled defines if this option should be enabled.
enabled
required boolean false prostorageClasses
required object pro
StorageClasses defines if storage classes created within the virtual cluster should get synced to the host cluster.
storageClasses
required object proenabled
required boolean false pro
Enabled defines if this option should be enabled.
enabled
required boolean false proserviceAccounts
required object pro
ServiceAccounts defines if service accounts created within the virtual cluster should get synced to the host cluster.
serviceAccounts
required object proenabled
required boolean false pro
Enabled defines if this option should be enabled.
enabled
required boolean false profromHost
required object pro
Configure what resources vCluster should sync from the host cluster to the virtual cluster.
fromHost
required object pronodes
required object pro
Nodes defines if nodes should get synced from the host cluster to the virtual cluster, but not back.
nodes
required object proenabled
required boolean false pro
Enabled specifies if syncing real nodes should be enabled. If this is disabled, vCluster will create fake nodes instead.
enabled
required boolean false prosyncBackChanges
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.
syncBackChanges
required boolean false proclearImageStatus
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.
clearImageStatus
required boolean false proselector
required object pro
Selector can be used to define more granular what nodes should get synced from the host cluster to the virtual cluster.
selector
required object proall
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.
all
required boolean false prolabels
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.
labels
required object proevents
required object pro
Events defines if events should get synced from the host cluster to the virtual cluster, but not back.
events
required object proenabled
required boolean false pro
Enabled defines if this option should be enabled.
enabled
required boolean false proingressClasses
required object pro
IngressClasses defines if ingress classes should get synced from the host cluster to the virtual cluster, but not back.
ingressClasses
required object proenabled
required boolean false pro
Enabled defines if this option should be enabled.
enabled
required boolean false prostorageClasses
required object pro
StorageClasses defines if storage classes should get synced from the host cluster to the virtual cluster, but not back. If auto, is automatically enabled when the virtual scheduler is enabled.
storageClasses
required object proenabled
required string|boolean pro
Enabled defines if this option should be enabled.
enabled
required string|boolean procsiNodes
required object pro
CSINodes defines if csi nodes should get synced from the host cluster to the virtual cluster, but not back. If auto, is automatically enabled when the virtual scheduler is enabled.
csiNodes
required object proenabled
required string|boolean pro
Enabled defines if this option should be enabled.
enabled
required string|boolean procsiDrivers
required object pro
CSIDrivers defines if csi drivers should get synced from the host cluster to the virtual cluster, but not back. If auto, is automatically enabled when the virtual scheduler is enabled.
csiDrivers
required object proenabled
required string|boolean pro
Enabled defines if this option should be enabled.
enabled
required string|boolean procsiStorageCapacities
required object pro
CSIStorageCapacities defines if csi storage capacities should get synced from the host cluster to the virtual cluster, but not back. If auto, is automatically enabled when the virtual scheduler is enabled.
csiStorageCapacities
required object proenabled
required string|boolean pro
Enabled defines if this option should be enabled.
enabled
required string|boolean pronetworking
required object pro
Networking options related to the virtual cluster.
networking
required object proreplicateServices
required object pro
ReplicateServices allows replicating services from the host within the virtual cluster or the other way around.
replicateServices
required object protoHost
required object[] pro
ToHost defines the services that should get synced from virtual cluster to the host cluster. If services are
synced to a different namespace than the virtual cluster is in, additional permissions for the other namespace
are required.
toHost
required object[] profromHost
required object[] pro
FromHost defines the services that should get synced from the host to the virtual cluster.
fromHost
required object[] proresolveDNS
required object[] pro
ResolveDNS allows to define extra DNS rules. This only works if embedded coredns is configured.
resolveDNS
required object[] prohostname
required string pro
Hostname is the hostname within the vCluster that should be resolved from.
hostname
required string proservice
required string pro
Service is the virtual cluster service that should be resolved from.
service
required string pronamespace
required string pro
Namespace is the virtual cluster namespace that should be resolved from.
namespace
required string protarget
required object pro
Target is the DNS target that should get mapped to
target
required object prohostname
required string pro
Hostname to use as a DNS target
hostname
required string proip
required string pro
IP to use as a DNS target
ip
required string prohostService
required string pro
HostService to target, format is hostNamespace/hostService
hostService
required string prohostNamespace
required string pro
HostNamespace to target
hostNamespace
required string provClusterService
required string pro
VClusterService format is hostNamespace/vClusterName/vClusterNamespace/vClusterService
vClusterService
required string proadvanced
required object pro
Advanced holds advanced network options.
advanced
required object proclusterDomain
required string pro
ClusterDomain is the Kubernetes cluster domain to use within the virtual cluster.
clusterDomain
required string profallbackHostCluster
required boolean false pro
FallbackHostCluster allows to fallback dns to the host cluster. This is useful if you want to reach host services without
any other modification. You will need to provide a namespace for the service, e.g. my-other-service.my-other-namespace
fallbackHostCluster
required boolean false proproxyKubelets
required object pro
ProxyKubelets allows rewriting certain metrics and stats from the Kubelet to "fake" this for applications such as
prometheus or other node exporters.
proxyKubelets
required object probyHostname
required boolean false pro
ByHostname will add a special vCluster hostname to the nodes where the node can be reached at. This doesn't work
for all applications, e.g. Prometheus requires a node IP.
byHostname
required boolean false probyIP
required boolean false pro
ByIP will create a separate service in the host cluster for every node that will point to virtual cluster and will be used to
route traffic.
byIP
required boolean false propolicies
required object pro
Policies to enforce for the virtual cluster deployment as well as within the virtual cluster.
policies
required object pronetworkPolicy
required object pro
NetworkPolicy specifies network policy options.
networkPolicy
required object proenabled
required boolean false pro
Enabled defines if the network policy should be deployed by vCluster.
enabled
required boolean false profallbackDns
required string pro
fallbackDns
required string prooutgoingConnections
required object pro
outgoingConnections
required object proipBlock
required object pro
IPBlock describes a particular CIDR (Ex. "192.168.1.0/24","2001:db8::/64") that is allowed
to the pods matched by a NetworkPolicySpec's podSelector. The except entry describes CIDRs
that should not be included within this rule.
ipBlock
required object procidr
required string pro
cidr is a string representing the IPBlock
Valid examples are "192.168.1.0/24" or "2001:db8::/64"
cidr
required string proexcept
required string[] pro
except is a slice of CIDRs that should not be included within an IPBlock
Valid examples are "192.168.1.0/24" or "2001:db8::/64"
Except values will be rejected if they are outside the cidr range
except
required string[] proannotations
required object pro
Annotations are extra annotations for this resource.
annotations
required object prolabels
required object pro
Labels are extra labels for this resource.
labels
required object propodSecurityStandard
required string pro
PodSecurityStandard that can be enforced can be one of: empty (""), baseline, restricted or privileged
podSecurityStandard
required string proresourceQuota
required object pro
ResourceQuota specifies resource quota options.
resourceQuota
required object proenabled
required boolean false pro
Enabled defines if the resource quota should be enabled.
enabled
required boolean false proquota
required object pro
Quota are the quota options
quota
required object proscopeSelector
required object pro
ScopeSelector is the resource quota scope selector
scopeSelector
required object proscopes
required string[] pro
Scopes are the resource quota scopes
scopes
required string[] proannotations
required object pro
Annotations are extra annotations for this resource.
annotations
required object prolabels
required object pro
Labels are extra labels for this resource.
labels
required object prolimitRange
required object pro
LimitRange specifies limit range options.
limitRange
required object proenabled
required boolean false pro
Enabled defines if the limit range should be deployed by vCluster.
enabled
required boolean false prodefault
required object pro
Default are the default limits for the limit range
default
required object prodefaultRequest
required object pro
DefaultRequest are the default request options for the limit range
defaultRequest
required object proannotations
required object pro
Annotations are extra annotations for this resource.
annotations
required object prolabels
required object pro
Labels are extra labels for this resource.
labels
required object procentralAdmission
required object pro
CentralAdmission defines what validating or mutating webhooks should be enforced within the virtual cluster.
centralAdmission
required object pro