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-imageor 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-vindGitHub Action to provision clusters in GitHub Actions workflows
How to use​
Prerequisites​
- Docker installed and running
- vCluster CLI installed
Permissions​
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.
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:
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.