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
• 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

How to use

Prerequisites

• Docker installed and running
• vCluster CLI installed

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_NAME

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.