Skip to main content
Version: v0.33 Stable

Shared Nodes Quick Start

You have a Kubernetes cluster. You want to give teams or CI pipelines isolated Kubernetes environments without provisioning additional infrastructure.

Each tenant cluster runs a dedicated control plane as a pod on your cluster. Tenant workloads sync into a dedicated namespace on the Control Plane Cluster — isolated from every other tenant, and presented to the tenant under clean, familiar names. The tenant sees a standard Kubernetes cluster. You see one namespace per tenant.

Prerequisites​

  • A Kubernetes cluster with kubectl configured to access it
  • At least 2 vCPU and 2 GB RAM available on the cluster

Install the vCluster CLI​

brew install loft-sh/tap/vcluster

The binaries in the tap are signed using the Sigstore framework for enhanced security.

Verify the CLI installed successfully.

vcluster --version

Output is similar to:

vCluster version 0.x.x

Deploy a tenant cluster​

  1. Deploy a tenant cluster named my-vcluster into a new namespace team-x.

    vcluster create my-vcluster --namespace team-x

    When the deployment finishes, the CLI automatically connects and switches your kube context into the tenant cluster.

  2. Confirm you are inside the tenant cluster.

    kubectl get namespaces

    You see standard Kubernetes system namespaces — this is the tenant cluster's own namespace view, separate from the Control Plane Cluster.

See the isolation​

  1. Deploy a test workload inside the tenant cluster.

    kubectl create deployment nginx --image=nginx
    kubectl get pods

    The pod is running inside the tenant cluster.

  2. Disconnect from the tenant cluster and inspect the same namespace from the Control Plane Cluster.

    vcluster disconnect
    kubectl get pods -n team-x

    Output is similar to:

    NAME                                                     READY   STATUS    RESTARTS   AGE
    coredns-79cf5f4c56-nkgdr-x-kube-system-x-my-vcluster   1/1     Running   0          4m
    my-vcluster-0                                           1/1     Running   0          5m
    nginx-56c45fd5ff-kp74s-x-default-x-my-vcluster          1/1     Running   0          2m

    The nginx pod is here, but with a rewritten name. vCluster syncs tenant workloads into this namespace so the underlying cluster can schedule them — the suffix (-x-default-x-my-vcluster) encodes the source namespace and cluster. From inside the tenant cluster, the pod appeared as plain nginx in namespace default.

    This is the isolation boundary: the tenant gets a clean Kubernetes API with no visibility into the Control Plane Cluster's structure. Other tenant clusters have their own dedicated namespaces — neither tenant can see the other's workloads.

Add management with vCluster Platform​

The cluster you just deployed works standalone. Connect it to vCluster Platform to add a self-service layer for your team: auto-sleep, access controls, and lifecycle management across your entire fleet.

Auto-sleep pauses tenant clusters when idle and wakes them on access. For internal developer platforms, this eliminates idle resource consumption without requiring any action from tenants. Clusters wake in seconds when someone connects.

vcluster platform add vcluster my-vcluster --namespace team-x

Once connected to Platform:

  • Tenant clusters appear in the Platform UI — your team accesses them without needing kubectl access to the Control Plane Cluster
  • Auto-sleep activates based on inactivity, cutting resource usage during off-hours
  • Access controls, templates, and project quotas apply across the full fleet

Install vCluster Platform → Configure auto-sleep →

Delete the tenant cluster​

warning

Deleting a tenant cluster removes all resources within it. This cannot be undone.

vcluster delete my-vcluster --namespace team-x

If the namespace was created by the vCluster CLI, it is also deleted.

Next steps​

  • Private nodes — dedicated infrastructure for GPU tenants and regulated workloads
  • Architecture — control plane internals, syncer behavior, and networking
  • Deploy with Helm — production deployment options including Helm, Terraform, and ArgoCD
  • vcluster.yaml reference — full configuration reference