Skip to main content

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 functionality without requiring a host Kubernetes 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​

  • Docker installed and running
  • vCluster CLI installed

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, 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"

Use vCluster VPN​

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​

docker required object ​

Docker allows you to configure Docker related settings when deploying a vCluster using Docker.

image required string ​

Image defines the image to use for the container. Defaults to ghcr.io/loft-sh/vm-container.

ports required string[] ​

Ports defines extra port mappings to be added to the container.

volumes required string[] ​

Volumes defines extra volumes to be added to the container.

env required string[] ​

Env defines extra environment variables to be added to the container. Use key=value.

args required string[] ​

Args defines extra arguments to be added to the docker run command of the container.

enabled required boolean ​

Enabled defines if the vCluster was deployed using Docker. This is automatically set by vCluster and should not be set by the user.

network required string ​

Network defines the network to use for the vCluster. If not specified, the a network will be created for the vCluster.

nodes required object[] ​

Nodes defines the nodes of the vCluster.

image required string ​

Image defines the image to use for the container. Defaults to ghcr.io/loft-sh/vm-container.

ports required string[] ​

Ports defines extra port mappings to be added to the container.

volumes required string[] ​

Volumes defines extra volumes to be added to the container.

env required string[] ​

Env defines extra environment variables to be added to the container. Use key=value.

args required string[] ​

Args defines extra arguments to be added to the docker run command of the container.

name required string ​

Name defines the name of the node. If not specified, a random name will be generated.

registryProxy required object ​

Defines if docker images should be pulled from the host docker daemon. This prevents pulling images again and allows to use purely local images. Only works if containerd image storage is used. For more information, see https://docs.docker.com/engine/storage/containerd

enabled required boolean true ​

Enabled defines if this option should be enabled.

loadBalancer required object ​

Defines if vCluster should configure load balancer services inside the vCluster. This might require sudo access on the host cluster for docker desktop or rancher desktop on macos.

enabled required boolean true ​

Enabled defines if this option should be enabled.

forwardPorts required boolean true ​

ForwardPorts defines if the load balancer ips should be made available locally via port forwarding. This will be only done if necessary for example on macos when using docker desktop.