vind - vCluster in Docker

---

🎯 What is vind?

vind (vCluster in Docker) is an open-source way to run Kubernetes clusters directly as Docker containers. Built on top of vCluster, vind combines the power of virtual Kubernetes clusters with the simplicity of Docker, creating isolated Kubernetes environments that are perfect for development, testing, and CI/CD pipelines.

Note: vind uses vCluster's Private Nodes mode internally. This is automatically enabled when using the Docker driver and is required for proper operation. This is expected behavior, not a configuration issue.

Why vind?

• 🚀 Faster than KinD - Optimized container-based architecture
• 💤 Sleep & Wake - Pause clusters to save resources, resume in under 3 seconds
• 🎨 Built-in UI - Free vCluster Platform UI for cluster management
• ⚡ Load Balancers OOB - Automatic LoadBalancer services without extra setup
• 🐳 Docker Native - Leverages Docker's networking and storage
• 🔄 Pull-through Cache - Faster image pulls via local Docker daemon
• 🌐 Hybrid Nodes - Join external nodes (even cloud instances) via VPN
• 📸 Snapshots - Save cluster state to OCI registries, S3, or local files and restore them
• 🔧 In-Place K8s Upgrades - Upgrade Kubernetes version without deleting the cluster

---

🚀 Quick Start

Prerequisites

• Docker installed and running
• vCluster CLI v0.34.0 or later

Installation

# Upgrade vCluster CLI to the latest version
vcluster upgrade --version v0.34.0

# Set Docker as the default driver
vcluster use driver docker

Optional: Start vCluster Platform UI

# Start vCluster Platform (optional but recommended)
vcluster platform start

This gives you a beautiful web UI to manage your clusters!

Important: If you plan to use the Platform UI, start it before creating clusters. Clusters created before the platform is started will not be automatically synced to the UI. Only clusters created after vcluster platform start will appear in the dashboard.

Create Your First Cluster

# Create a vCluster in Docker (automatically connects)
vcluster create my-cluster

# Verify it's working
kubectl get nodes
kubectl get namespaces

---

✨ Key Features

🎮 Kubernetes UI via vCluster Platform

Integrated management and visibility with a beautiful web interface - no need for external tools!

💤 Sleep and Wakeup

Pause your clusters when not in use and resume them instantly. Perfect for saving resources during development breaks.

# Pause a cluster
vcluster pause my-cluster

# Resume a cluster
vcluster resume my-cluster

⚡ Automatic Load Balancers

Hassle-free service exposure with automatic LoadBalancer support - works out of the box! (Enabled by default)

🐳 Pull-through Cache via Local Docker Daemon

Faster image pulls and reduced bandwidth by leveraging your local Docker daemon's image cache. (Enabled by default)

🌐 Join External Nodes

Connect real cloud instances (like EC2, GCP, Azure) as nodes to your local cluster via built-in Tailscale VPN.

📸 Snapshots and Restore

Save your entire cluster state to an OCI registry, S3 bucket, or local file — then restore it on any vind cluster. Perfect for sharing reproducible environments or safeguarding demo setups.

# Snapshot to an OCI registry
vcluster snapshot create my-cluster oci://ghcr.io/my-user/my-repo:my-tag

# Snapshot to a local file inside the cluster container
vcluster snapshot create my-cluster container:///data/my-snapshot.tar.gz

# Restore from an OCI registry
vcluster restore my-cluster oci://ghcr.io/my-user/my-repo:my-tag

🔧 Flexible CNI and CSI

Choose your own Container Network Interface and Container Storage Interface plugins.

---

📖 Documentation

• Getting Started Guide - Detailed setup and first steps
• Configuration Guide - All configuration options explained
• Advanced Features - Sleep/wake, load balancers, snapshots, external nodes
• vind vs KinD - Detailed comparison
• Examples - Real-world examples and use cases
• Troubleshooting - Common issues and solutions

---

🎨 vind vs KinD

👉 See detailed comparison

---

🔧 Configuration

vind supports extensive configuration options. Here's a quick example:

experimental:
  docker:
    # Custom network
    network: "my-custom-network"
    
    # Additional nodes (only name required)
    nodes:
      - name: worker-1
        env:
          - "CUSTOM_VAR=value"
    
    # Load balancer and registry proxy are enabled by default
    
    # Custom ports
    ports:
      - "8080:80"
    
    # Custom volumes
    volumes:
      - "/host/path:/container/path"
    
    # Extra Docker args
    args:
      - "--cap-add=SYS_ADMIN"

👉 Full configuration reference

---

📚 Examples

Check out our examples directory for:

• Basic cluster setup
• Multi-node cluster
• Multi-node cluster (simple)
• With custom CNI
• Load balancer services
• Node affinity
• Pod anti-affinity / topology spread
• Snapshot and restore
• External node joining

---

🎯 Use Cases

Development Environments

Create isolated Kubernetes environments for each developer or feature branch.

CI/CD Pipelines

Spin up temporary clusters for testing and tear them down when done. Use the official setup-vind GitHub Action to integrate vind into your workflows.

Learning Kubernetes

Perfect for learning K8s without the overhead of managing a full cluster.

Local Testing

Test your applications in a real Kubernetes environment before deploying.

Hybrid Development

Join cloud resources to your local cluster for hybrid development scenarios.

---

🛠️ Common Commands

# Create a cluster (automatically connects)
vcluster create my-cluster

# List clusters
vcluster list

# Connect to a cluster
vcluster connect my-cluster

# Disconnect from a cluster
vcluster disconnect my-cluster

# Pause a cluster (save resources)
vcluster pause my-cluster

# Resume a cluster
vcluster resume my-cluster

# Delete a cluster
vcluster delete my-cluster

# Describe cluster
vcluster describe my-cluster

# Snapshot cluster state (OCI, S3, or local)
vcluster snapshot create my-cluster oci://ghcr.io/my-user/my-repo:my-tag
vcluster snapshot create my-cluster s3://my-bucket/my-key
vcluster snapshot create my-cluster container:///data/my-snapshot.tar.gz

# Restore cluster from snapshot
vcluster restore my-cluster oci://ghcr.io/my-user/my-repo:my-tag

# View control plane logs
docker exec vcluster.cp.my-cluster journalctl -u vcluster --nopager

# View node logs (for node named worker-1)
docker exec vcluster.node.my-cluster.worker-1 journalctl -u kubelet --nopager

---

🔗 Related Projects

• vCluster - The underlying virtual cluster technology
• vCluster Platform - Management platform for vClusters
• setup-vind GitHub Action - GitHub Action for using vind in CI/CD pipelines
• KinD - Kubernetes in Docker (alternative)

Community Articles

• Replacing KinD with vind - Deep Dive - Complete walkthrough with GCP external node example
• vCluster in Docker Has Changed the Way We Build and Share Local Kubernetes Developer Environments - By Artem
• Multiple PodCIDR Pools with Cilium and vCluster - By Shubham Katara

---

🤝 Contributing

vind is built on top of vCluster. The core code lives in the vCluster repository.

This repository serves as:

• Documentation and guides for the Docker driver feature
• Examples and use cases
• Community resources

To contribute to the core feature, please see the vCluster contributing guide.

---

📝 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

---

📞 Support

• 📖 Documentation
• 💬 Slack Community
• 🐛 Issue Tracker
• 💡 Discussions

---