Skip to main content
Version: v0.38 Stable

Configure vCluster in Docker (vind)

vCluster in Docker (vind) allows you to run virtual Kubernetes clusters directly in Docker containers instead of deploying them to an existing Kubernetes cluster. This provides a lightweight, isolated environment perfect for development, testing, and CI/CD scenarios.

Overview​

What is vind? vind creates a complete Kubernetes cluster that runs entirely within Docker containers on your local machine or any Docker-enabled environment. Each vCluster instance gets its own set of containers that simulate Kubernetes nodes, providing full cluster capabilities without requiring a control plane cluster.

Why use vind?

  • Local Development: Quickly spin up isolated Kubernetes environments for development and testing
  • Pull through cache: No kind load docker-image or importing of images needed. vind uses your local docker daemon to pull images
  • Automatic load balancers: Kubernetes LoadBalancer services work out of the box and are reachable locally as well as within the cluster. Requires sudo on some platforms. See Permissions.
  • External nodes: Use vCluster VPN and the vCluster Platform to join external nodes into the vCluster
  • Isolation: Complete separation between different vCluster instances
  • Portability: Works consistently across different Docker environments
  • CI/CD: Use the setup-vind GitHub Action to provision clusters in GitHub Actions workflows

How to use​

Prerequisites​

Permissions​

Sudo required for load balancer services

Creating a vCluster with load balancer support requires elevated privileges. Without sudo, the CLI outputs this warning:

warn Load balancer type services are not supported inside the vCluster because
this command was executed with insufficient privileges. To enable load balancer
type services, run this command with sudo

Run the vcluster create command with sudo to enable load balancer services. This is most commonly required on Docker Desktop and Rancher Desktop on macOS.

Modify the following with your specific values to generate a copyable command:
sudo vcluster create my-vcluster --values values.yaml

If you don't need load balancer services, you can disable load balancer services and run without sudo.

Basic usage​

First, run vcluster use driver to configure vCluster to use the Docker driver:

vcluster use driver docker

Then create a vCluster with Docker-specific configuration:

Modify the following with your specific values to generate a copyable command:
vcluster create my-vcluster --values values.yaml

Configuration options​

The experimental.docker section in your vCluster configuration allows you to customize various Docker-specific settings:

Container customization​

  • Image: Specify custom container images for the vCluster nodes
  • Ports: Expose additional ports from the containers to the host
  • Volumes: Mount host directories or Docker volumes into the containers
  • Environment Variables: Set custom environment variables in the containers
  • Docker Arguments: Pass additional arguments to the Docker run command

Multi-node setup​

  • Additional Nodes: Configure multiple worker nodes for your vCluster
  • Node-Specific Settings: Customize individual nodes with different images, ports, or volumes

Advanced features​

  • Registry Proxy: Enable pull-through caching to reuse images from the host Docker daemon
  • Load Balancer: Configure automatic load balancer services (may require elevated privileges on some platforms)
  • Custom Networks: Specify Docker networks for inter-container communication

Examples​

Basic vCluster with extra ports​

experimental:
docker:
ports:
- "8080:80"
- "8443:443"
env:
- "DEBUG=true"
- "LOG_LEVEL=info"

Multi-node vCluster​

experimental:
docker:
nodes:
- name: "worker-1"
ports:
- "9090:9090"
- name: "worker-2"
volumes:
- "/host/data:/data"
env:
- "NODE_ROLE=worker"

Enable vCluster VPN between nodes​

experimental:
docker:
nodes:
- name: my-node
privateNodes:
vpn:
enabled: true
nodeToNode:
enabled: true

Set up with volume mounts​

experimental:
docker:
volumes:
- "/home/user/projects:/workspace"

Disable registry proxy and load balancer​

experimental:
docker:
registryProxy:
enabled: false
loadBalancer:
enabled: false

Config reference​

For every field under experimental.docker, see the experimental reference.