VCluster

VCluster creates lightweight, isolated virtual Kubernetes clusters that run as Docker containers. This guide walks you through creating your first VCluster, understanding when to use it, and exploring common use cases.

What is VCluster?

VCluster provides virtual Kubernetes clusters—fully functional Kubernetes control planes that ordinarily run as pods inside a host Kubernetes cluster. KSail uses the Vind Docker driver to run VCluster directly on Docker instead, without requiring a host cluster. Each VCluster is isolated, starts in seconds, and shares Docker infrastructure—making it ideal for CI/CD and local multi-environment development.

When to Use VCluster

VCluster excels at CI/CD pipelines (ephemeral per-PR clusters, parallel test execution on shared runners), local multi-environment development (isolated environments per feature branch or team member), and learning (safe, disposable Kubernetes sandboxes).

Consider other distributions for production workloads (Talos), cloud deployment (Talos with Hetzner Cloud or Omni), standard upstream Kubernetes testing (Vanilla), low-resource devices (K3s), or advanced CNI control (Vanilla or Talos).

Quick Start

1. Initialize a VCluster Project

Create a new VCluster configuration:

mkdir my-vcluster
cd my-vcluster

ksail cluster init \
  --name dev-cluster \
  --distribution VCluster \
  --gitops-engine Flux

This generates:

• ksail.yaml — KSail cluster configuration
• vcluster.yaml — VCluster Helm values (native configuration)
• k8s/kustomization.yaml — Directory for Kubernetes manifests

2. Create the Cluster

ksail cluster create

KSail creates Docker containers for the control plane, bootstraps the GitOps engine, and configures kubectl automatically.

3. Verify the Cluster

ksail cluster info
kubectl get nodes
kubectl get pods --all-namespaces

4. Deploy Workloads

See Workload Management for applying manifests, Helm charts, and managing resources.

5. Clean Up

ksail cluster delete

Configuration

For general KSail YAML options, see the Configuration Reference. Customize VCluster-specific behavior in vcluster.yaml:

# Control plane configuration
controlPlane:
  distro:
    k8s:
      image:
        tag: v1.35.3
  statefulSet:
    resources:
      limits:
        memory: 2Gi
      requests:
        memory: 256Mi

# Sync options - what gets synced from virtual to host
sync:
  persistentVolumes:
    enabled: true
  storageClasses:
    enabled: true
  nodes:
    enabled: true

# Networking
networking:
  replicateServices:
    toHost:
      - from: default
        to: vcluster-default

See the vCluster configuration documentation for all options.

Common Use Cases

For real-world VCluster workflow examples — CI/CD pipelines, multi-environment development, feature branch testing, and microservices isolation — see Use Cases.

Architecture

VCluster runs a full Kubernetes control plane (API server, scheduler, controller manager, etcd) as pods inside a host Kubernetes cluster. In KSail, the Vind driver runs these components as Docker containers instead. Pods are scheduled onto cluster nodes (the control-plane node or optional worker nodes), each of which runs as a Docker container. When using host-cluster deployment mode, selected resources can be synced between the virtual and host cluster.

Comparison with Other Distributions

For a full comparison across all distributions and supported components, see the Support Matrix.

Troubleshooting

Cluster Won’t Start

Symptom: ksail cluster create hangs or fails.

KSail automatically retries transient VCluster startup failures: up to 5 attempts (5-second delays) during create, and up to 3 attempts (3-minute timeout each) during the readiness check. Log messages like Retrying vCluster create (attempt 2/5)... are expected — wait for completion before investigating.

D-Bus startup errors (Failed to connect to bus) are a known race condition in which systemd inside the VCluster container hasn’t finished initializing D-Bus before the install script runs. KSail detects this error, waits up to 30 seconds for D-Bus to become available, then retries. This is common on CI runners (GitHub Actions) and is handled automatically — no user action is required.

Persistent failures — common causes:

docker ps          # Docker must be running
lsof -i :6443      # Check for port 6443 conflicts
docker info | grep -i memory  # Ensure 2GB+ RAM allocated to Docker

If all retries fail, run ksail cluster delete && ksail cluster create.

kubectl Commands Fail

Symptom: kubectl get nodes returns connection errors.

kubectl config current-context    # Should show your VCluster name
kubectl config use-context dev-cluster  # Switch if needed

If the context is missing, delete and recreate the cluster.

Pod Scheduling Issues

Symptom: Pods remain in Pending state.

kubectl describe pod <pod-name>  # Check scheduling errors
kubectl top nodes                # Check resource availability
kubectl get nodes                # All nodes should show Ready

Slow Performance

Increase Docker resources (4 GB RAM, 2 CPUs minimum) in Docker Desktop settings, and delete unused clusters with ksail cluster list / ksail cluster delete.

Advanced Topics

Multiple Control-Plane Replicas

For high-availability scenarios, run multiple control-plane replicas:

vcluster.yaml

controlPlane:
  statefulSet:
    highAvailability:
      replicas: 3

See the vCluster high-availability docs for details.

Custom Distributions

VCluster supports k8s (default), k0s, and k3s as internal distributions. Set the active distro under controlPlane.distro in vcluster.yaml:

# vcluster.yaml — switch to k0s
controlPlane:
  distro:
    k0s:
      enabled: true

Resource Limits

Control resource consumption:

vcluster.yaml

controlPlane:
  statefulSet:
    resources:
      limits:
        cpu: "1"
        memory: 2Gi
      requests:
        cpu: "100m"
        memory: 256Mi