vcluster Learning¶
A vcluster is a full Kubernetes API server running as a pod inside a namespace of a host cluster. Workloads you create in it are synced down and scheduled as real pods on the host. You get cluster-level objects (namespaces, CRDs, RBAC, your own API server version) without a second real cluster to pay for and operate.
Everything here uses the official vcluster Helm chart from https://charts.loft.sh, distro k8s, chart version 0.37.2.
Learning¶
- One values file drives everything. The chart reads
vcluster.yaml(passed as Helm-f values.yaml), so every option below is a block in the same file. - Pick the distro once.
controlPlane.distro.k8s.enabled: trueruns vanilla Kubernetes (the default). Only one distro can be enabled at a time. - The API server listens on
https://localhost:8443inside the pod. Anything reaching it under a different hostname needs that hostname in the certificate (controlPlane.proxy.extraSANs) and in the exported kubeconfig (exportKubeConfig.server). - vcluster always writes a kubeconfig secret
vc-<name>in the host namespace. SetexportKubeConfig.secret.nameto also write a second one with your own server URL for CI or GitOps. - A ResourceQuota only counts pods that declare requests. Enable
policies.limitRangealongsidepolicies.resourceQuotaso pods without requests still get defaults and still count. experimental.deployruns manifests and Helm charts inside the vcluster at startup. It is flagged experimental by vcluster: breaking changes can land between releases.- The virtual control plane is a single pod by default. Back it with embedded etcd or an external database if you need HA.
- OSS vcluster is controllers, not CRDs. A vcluster is a Helm release of plain objects (StatefulSet + Service + RBAC + Secret); the syncer is the controller, running inside the pod. A CRD that represents a vcluster exists only on the vCluster Platform (paid) or via the Cluster API provider (free).
Creating a vcluster¶
OSS vcluster has controllers but no CRDs: the syncer (inside the control-plane pod) reconciles built-in objects across the virtual and host API servers, so no custom resource type is needed. A CRD that represents a vcluster only appears when you add a layer on top.
| Create a vcluster via | CRD? | Cost | Fit |
|---|---|---|---|
Helm chart / vcluster create CLI |
No — plain StatefulSet + Service + RBAC + Secret | OSS, free | Default; what ArgoCD deploys |
vCluster Platform (VirtualClusterInstance) |
Yes — management-plane CRDs + controller, templates | Free tier; paid at scale | Fleets, multi-tenant management |
Cluster API provider (cluster-api-provider-vcluster) |
Yes — vcluster as a CAPI Cluster |
OSS, free | CRD-driven creation without the Platform |
Deployed through an ArgoCD Application pointing at the chart, the declarative/GitOps property comes from Argo tracking that Helm release — not from any vcluster CRD.
Cheatsheet¶
Install or upgrade¶
helm upgrade --install my-vcluster vcluster \
--repo https://charts.loft.sh \
--version 0.37.2 \
-n my-vcluster --create-namespace \
-f values.yaml
Connect with the CLI¶
Connect without the CLI (read the exported secret)¶
kubectl -n my-vcluster get secret vc-my-vcluster \
-o jsonpath='{.data.config}' | base64 -d > kubeconfig.yaml
export KUBECONFIG=$(pwd)/kubeconfig.yaml
kubectl get namespaces
List and delete¶
https://www.vcluster.com/docs/vcluster/ https://www.vcluster.com/docs/vcluster/configure/vcluster-yaml/ https://vcluster.com/docs/vcluster/introduction/oss-vs-free https://github.com/loft-sh/cluster-api-provider-vcluster