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 in these scenarios:

✅ Use VCluster For

CI/CD Pipelines

• Ephemeral test clusters per PR or test suite
• Fast creation/deletion without infrastructure overhead
• Complete isolation between test runs
• Parallel test execution on shared runners

Development Workflows

• Quick feature branch testing
• Local integration testing
• Microservices development with isolated environments
• Rapid cluster recreation during development

Multi-Tenancy

• Multiple isolated environments on one machine
• Team collaboration without cluster conflicts
• Demo environments for each customer or project
• Sandbox environments for experimentation

Learning and Experimentation

• Safe environment for Kubernetes learning
• Test manifests without affecting other projects
• Experiment with cluster configurations
• Quick reset to clean state

❌ Consider Other Distributions For

• Production workloads → Use Talos (security-focused) or K3s (resource-efficient)
• Bare metal or cloud deployment → Use Talos with Hetzner provider
• Upstream Kubernetes testing → Use Vanilla (Kind) for standard Kubernetes
• Low-resource devices → Use K3s for minimal memory footprint
• Advanced networking features → Use Vanilla or Talos with full CNI control

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

Use Case 1: CI/CD Test Clusters

Create isolated clusters for each test run:

# In CI pipeline
BRANCH=$(git rev-parse --short HEAD)
ksail cluster init --name "test-${BRANCH}" --distribution VCluster
ksail cluster create

# Run tests
kubectl apply -f test-manifests/
pytest integration/

# Cleanup
ksail cluster delete

Benefits:

• Each test run gets a fresh, isolated cluster
• No cross-contamination between runs
• Fast creation/deletion (seconds vs minutes)
• Parallel test execution on same runner

Use Case 2: Multi-Environment Development

Maintain separate environments on one machine:

# Create dev environment
ksail cluster init --name dev --distribution VCluster
ksail cluster create

# Create staging environment
ksail cluster init --name staging --distribution VCluster
ksail cluster create

# Create production-like environment
ksail cluster init --name prod-sim --distribution VCluster
ksail cluster create

# Switch between environments
kubectl config use-context dev
kubectl config use-context staging
kubectl config use-context prod-sim

Use Case 3: Microservices Development

Each team member can have isolated services:

# Developer 1
ksail cluster init --name alice-services --distribution VCluster
ksail cluster create
kubectl apply -f alice-manifests/

# Developer 2
ksail cluster init --name bob-services --distribution VCluster
ksail cluster create
kubectl apply -f bob-manifests/

# No conflicts - completely isolated!

Use Case 4: Feature Branch Testing

Test features in isolation before merging:

# Create cluster per feature branch
git checkout feature/new-api
ksail cluster init --name feature-new-api --distribution VCluster
ksail cluster create
kubectl apply -f manifests/

# Test the feature
curl http://localhost:8080/api/v2

# When done, delete and switch branches
ksail cluster delete
git checkout feature/ui-updates
ksail cluster init --name feature-ui --distribution VCluster
ksail cluster create

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

1. Virtual Control Plane: Runs in a Docker container with Kubernetes API server, scheduler, controller manager, and etcd
2. Networking: Uses Docker networking for pod-to-pod communication
3. Storage: Volumes are managed within the virtual cluster
4. Syncing: Selected resources (pods, services, configmaps) are synced to host cluster if needed

Comparison with Other Distributions

Feature	VCluster	Vanilla (Kind)	K3s	Talos
Startup Time	~10s	~30s	~20s	~60s
Resource Usage	Low	Medium	Low	Medium
Multi-Tenancy	✅	❌	❌	❌
Production Ready	No	No	Yes	Yes
Security Isolation	High	Medium	Medium	High
Worker Nodes	Optional	Required	Req’d	Req’d
GitOps Support	✅	✅	✅	✅
Best For	CI/CD	Testing	Prod	Prod
Upstream Kubernetes	No (K3s)	Yes	No	Yes

Troubleshooting

Cluster Won’t Start

Symptom: ksail cluster create hangs or fails

Automatic retry (create phase): KSail automatically retries transient startup failures up to 3 times (with 5-second delays between attempts). If you see log messages like Retrying vCluster create (attempt 2/3)..., this is expected — KSail is recovering from a transient Docker or D-Bus error without any action needed from you.

Automatic retry (connect phase): After the cluster is created, KSail also retries the readiness check up to 3 times. Each attempt allows up to 3 minutes for the cluster to become ready, giving an effective timeout of ~9 minutes. If you see log messages like Retrying vCluster connect (attempt 2/3)..., this is expected behavior on slower machines or CI runners — KSail will keep waiting without any action needed from you.

Common causes for persistent failures:

1. Docker not running

   docker ps  # Should list containers

2. Port conflicts

   # Check if port 6443 is in use
   lsof -i :6443

3. Insufficient resources

   # Ensure Docker has enough memory (2GB+ recommended)
   docker info | grep -i memory

Fix (if all retry attempts fail):

# Delete and recreate
ksail cluster delete
ksail cluster create

Transient Startup Failures on CI Runners

Symptom: ksail cluster create fails with exit status 22 (EINVAL) on CI runners.

KSail automatically retries transient VCluster startup failures with up to 3 attempts and a 5-second delay between attempts, cleaning up partial state between retries. If the issue persists after automatic retries, check Docker resource limits and D-Bus availability on the runner.

kubectl Commands Fail

Symptom: kubectl get nodes returns connection errors

Fix:

# Verify kubeconfig context
kubectl config current-context

# Should show your VCluster name
# If not, switch contexts:
kubectl config use-context dev-cluster

# Or regenerate kubeconfig
ksail cluster delete
ksail cluster create

Pod Scheduling Issues

Symptom: Pods remain in Pending state

Diagnosis:

kubectl describe pod <pod-name>
# Look for scheduling errors

Common fixes:

1. Check resources

   kubectl top nodes

2. Verify node readiness

   kubectl get nodes
   # All nodes should show Ready

Slow Performance

Symptom: Operations are slower than expected

Possible causes:

• Docker resource limits too low
• Too many clusters running simultaneously
• System under heavy load

Optimization:

# Increase Docker resources in Docker Desktop settings
# Recommended: 4GB RAM, 2 CPUs minimum

# Delete unused clusters
ksail cluster list
ksail cluster delete unused-cluster

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