Skip to main content
Version: main 🚧

Docker (vind) Quick Start

You want a full Kubernetes cluster running locally for development, testing, or CI. You don't want the setup overhead of a cloud environment or the limitations of KinD.

vind (vCluster in Docker) runs a complete Kubernetes cluster in Docker containers. No cloud account, no existing Kubernetes cluster, no kubeadm. If Docker is running, you can have a cluster in under a minute. When you're ready to test against real cloud hardware, vind clusters can also accept actual EC2 or GCP instances as worker nodes through vCluster VPN. That's a hybrid setup that KinD simply can't do.

This guide covers deployment, pause and resume, LoadBalancer services, and virtual worker nodes. Here's how vind compares to KinD:

FeaturevindKinD
Pause and resume without losing stateYesNo — must delete and recreate
LoadBalancer servicesAutomatic (Linux); port-forward on macOSManual setup required
Virtual worker nodesYesLimited
Join real cloud instancesYes, via VPNNo
Pull-through image cacheUses host Docker daemonDirect registry pulls

Prerequisites​

  • Docker installed and running
  • At least 4 GB RAM available to Docker (Rancher Desktop or Docker Desktop VM size)

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 cluster​

  1. Configure vCluster to use the Docker driver.

    vcluster use driver docker

  2. Deploy a cluster.

    vcluster create my-vcluster

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

  3. Verify the cluster is running.

    kubectl get nodes

Pause and resume​

A vind cluster can pause and resume without losing state. A KinD cluster requires a full delete and recreate.

# Pause the cluster — frees Docker resources immediately
vcluster pause my-vcluster

# Check the status
vcluster list

Output is similar to:

      NAME     | STATUS | CONNECTED | AGE
 --------------+--------+-----------+-----
  my-vcluster  | exited | True      | 5m
# Resume — cluster is back in seconds
vcluster resume my-vcluster
vcluster connect my-vcluster

Paused clusters retain all their state. After resume, workloads restart where they left off.

If vcluster disconnect prompts you to select a context, choose your previous cluster context (for example rancher-desktop or docker-desktop).

LoadBalancer services​

On Linux, LoadBalancer services get an external IP automatically. No MetalLB or extra configuration required.

kubectl create deployment hello --image=nginx
kubectl expose deployment hello --port=80 --type=LoadBalancer
kubectl get service hello --watch

Output on Linux is similar to:

NAME    TYPE           CLUSTER-IP    EXTERNAL-IP   PORT(S)        AGE
hello   LoadBalancer   10.96.x.x     127.0.0.1     80:31234/TCP   5s
curl http://localhost
macOS limitation

On macOS with Docker Desktop or Rancher Desktop, the LoadBalancer IP will not be assigned. Docker runs inside a Linux VM and the bridge network IP is not routable on the macOS host. Use kubectl port-forward instead:

kubectl port-forward deployment/hello 8080:80
curl http://localhost:8080

Add virtual worker nodes​

Test node affinity rules, DaemonSet scheduling, or topology spread constraints without real hardware. Add virtual worker nodes by configuring them in a vcluster.yaml at creation time.

Delete the current cluster first to free resources. Running two clusters simultaneously requires at least 4 GB RAM in your Docker VM.

vcluster delete my-vcluster
vcluster.yaml
experimental:
  docker:
    nodes:
      - name: worker-1
      - name: worker-2
vcluster create my-cluster --values vcluster.yaml
kubectl get nodes

Output is similar to:

NAME        STATUS   ROLES           AGE
my-cluster  Ready    control-plane   30s
worker-1    Ready    <none>          25s
worker-2    Ready    <none>          25s

Schedule workloads to specific nodes, add labels and taints, or simulate a realistic multi-node topology. All from a single Docker host.

Join real cloud nodes​

vind clusters accept real cloud instances as worker nodes through vCluster VPN. An EC2 instance, GCP VM, or any Linux machine can join your local vind cluster through a VPN tunnel. The result is a hybrid cluster with a local control plane and real remote compute.

This requires vCluster Platform. See vCluster VPN documentation for setup instructions.

Clean up​

vcluster delete my-cluster

All Docker containers and networks created for the cluster are removed. On macOS you may see a permission denied warning about a leftover file in ~/.vcluster/docker/. This is benign. The cluster is fully deleted.

Next steps​