Skip to main content

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​

Air-gapped environments

If your Docker containers cannot reach public registries or GitHub, complete the air-gapped setup before running these steps.

  1. Configure vCluster to use the Docker driver.

    vcluster use driver docker

  2. Deploy a cluster.

    vcluster create my-vcluster
    note

    vCluster deploys Kubernetes v1.35.0 by default. To use a different version, set controlPlane.distro.k8s.image.tag in your vcluster.yaml.

    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​

Ready for production?

See Build for Production to find the path that matches what you're building.