Getting Started with 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 run inside Docker containers instead of requiring a host cluster. KSail uses the Vind Docker driver to run VCluster directly on Docker, making it perfect for development and CI/CD without the overhead of a full Kubernetes cluster.

Key Benefits

• Lightweight: Control plane runs in a single Docker container
• Fast startup: Clusters ready in seconds
• Isolated: Each VCluster is completely isolated
• Cost-effective: Share Docker infrastructure across multiple clusters
• CI/CD friendly: Perfect for ephemeral test environments
• Multi-tenancy: Run multiple isolated clusters on one machine

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

What happens:

1. Docker containers are created for the VCluster control plane
2. Optional worker nodes are started (if configured)
3. GitOps engine (Flux or ArgoCD) is bootstrapped
4. Kubeconfig is automatically configured

Expected output:

✓ Creating VCluster cluster 'dev-cluster'...
✓ Waiting for control plane to be ready...
✓ Cluster created successfully
✓ Kubeconfig updated: kubectl config use-context dev-cluster

3. Verify the Cluster

# Check cluster info
ksail cluster info

# List running containers
docker ps | grep dev-cluster

# Test kubectl access
kubectl get nodes
kubectl get pods --all-namespaces

4. Deploy an Application

# Create a simple deployment
kubectl create deployment nginx --image=nginx:1.25
kubectl expose deployment nginx --port=80 --type=NodePort

# Check the service
kubectl get svc nginx

5. Clean Up

# Delete the cluster when done
ksail cluster delete

# Verify containers are removed
docker ps | grep dev-cluster

Configuration Options

Basic Configuration

The generated ksail.yaml controls cluster behavior:

apiVersion: ksail.io/v1alpha1
kind: Cluster
spec:
  cluster:
    distribution: VCluster
    gitOpsEngine: Flux  # or ArgoCD

VCluster-Specific Configuration

Customize VCluster behavior in vcluster.yaml:

# Control plane configuration
controlPlane:
  distro:
    k3s:
      enabled: true
  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

How VCluster Works

┌─────────────────────────────────────────────┐
│          Your Host Machine                  │
│                                             │
│  ┌────────────────────────────────────┐   │
│  │  Docker Engine                     │   │
│  │                                    │   │
│  │  ┌──────────────────────────┐     │   │
│  │  │  VCluster Control Plane  │     │   │
│  │  │  (Docker Container)      │     │   │
│  │  │                          │     │   │
│  │  │  • API Server            │     │   │
│  │  │  • Controller Manager    │     │   │
│  │  │  • Scheduler             │     │   │
│  │  │  • etcd                  │     │   │
│  │  └──────────────────────────┘     │   │
│  │                                    │   │
│  │  ┌──────────────────────────┐     │   │
│  │  │  Worker Nodes (Optional) │     │   │
│  │  │  (Docker Containers)     │     │   │
│  │  └──────────────────────────┘     │   │
│  └────────────────────────────────────┘   │
│                                             │
│  Your applications run in the VCluster     │
│  and appear as normal pods from the        │
│  virtual cluster's perspective             │
└─────────────────────────────────────────────┘

Components

The VCluster control plane runs in a Docker container and includes a Kubernetes API server, scheduler, controller manager, and etcd. Pods are scheduled to worker node containers (optional) or directly within the control plane container. When VCluster is used in a host-cluster deployment mode (outside KSail’s Docker/Vind setup), selected resources can be synced between the virtual cluster and its 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.

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

Worker Nodes

By default, VCluster runs workload pods inside the control plane container. For more realistic multi-node scenarios, enable worker nodes:

vcluster.yaml

nodes:
  enabled: true
  count: 3

This creates separate Docker containers acting as worker nodes.

Custom Distributions

VCluster can run different Kubernetes distributions internally:

vcluster.yaml

controlPlane:
  distro:
    k3s:
      enabled: true  # Default, lightweight
    # OR
    k8s:
      enabled: true  # Standard Kubernetes
    # OR
    k0s:
      enabled: true  # K0s distribution

Resource Limits

Control resource consumption:

vcluster.yaml

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

Next Steps

Explore KSail Features

• GitOps Integration: Bootstrap Flux or ArgoCD
• Secret Management: Encrypt secrets with SOPS
• AI Chat: Interactive cluster management with GitHub Copilot
• VSCode Extension: Manage clusters from your editor

Try Other Distributions

• Vanilla (Kind): Upstream Kubernetes for maximum compatibility
• K3s (K3d): Lightweight K3s for resource-constrained environments and CI/CD
• Talos: Immutable infrastructure for production

Learn More

• Installation Guide: Install KSail on your system
• CLI Flags: Comprehensive command documentation
• Configuration Reference: Detailed YAML options
• Support Matrix: Detailed VCluster capabilities
• Use Cases: More real-world scenarios
• vCluster Documentation: Upstream VCluster docs
• Contributing: Contribute to KSail development