Skip to main content

Deployment basics

vCluster in Docker (vind) allows you to deploy a complete Kubernetes cluster using Docker containers without requiring a host Kubernetes cluster. This deployment method is ideal for local development, testing, and CI/CD scenarios.

Overview​

When deploying vCluster as Docker containers:

  • Control plane: Runs as Docker containers (API server, etcd, controller manager, scheduler)
  • Worker nodes: Simulated as additional Docker containers
  • Networking: Uses Docker networking for inter-container communication
  • Storage: Uses Docker volumes for persistent data
  • No host cluster required: Complete independence from existing Kubernetes infrastructure

Prerequisites​

System requirements​

  • Docker: Docker Desktop, Docker Engine or similar installed and running
  • Operating System: Linux, macOS, or Windows with Docker support
  • Resources: Minimum 2GB RAM and 2 CPU cores available to Docker
  • Network: Docker daemon accessible and able to create networks

Docker configuration​

Ensure Docker is properly configured:

docker --version
docker info

For optimal performance, consider:

  • Enabling containerd image storage for better registry proxy performance
  • Allocating sufficient resources in Docker Desktop preferences

Deploy vCluster​

Step 1: Install vCluster CLI​

brew install loft-sh/tap/vcluster

The binaries in the tap are signed using the Sigstore framework for enhanced security.

Confirm that you've installed the correct version of the vCluster CLI.

vcluster --version

Step 2: Configure Docker Driver​

Set vCluster to use the Docker driver:

vcluster use driver docker

Step 3: Create vCluster configuration (optional)​

Create a vcluster.yaml file to customize your Docker deployment:

experimental:
  docker:
    # Expose additional ports
    ports:
    - "8080:80"
    - "8443:443"
  
    # Mount host directories
    volumes:
    - "/host/data:/data"
    - "/var/run/docker.sock:/var/run/docker.sock"
  
    # Set environment variables
    env:
    - "DEBUG=true"
    - "LOG_LEVEL=info"
  
    # Add additional worker nodes
    nodes:
    - name: "worker-1"
      ports:
        - "9090:9090"
    - name: "worker-2"
      volumes:
        - "/host/logs:/logs"
  
    # Configure registry proxy (enabled by default)
    registryProxy:
      enabled: true
  
    # Configure load balancer (enabled by default)
    loadBalancer:
      enabled: true
      forwardPorts: true

Step 4: Deploy the vCluster​

Deploy with default configuration:

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

Or deploy with custom configuration:

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

Step 5: Verify Deployment​

Check that your vCluster is running:

kubectl get nodes
kubectl get namespaces

Verify Docker containers:

Modify the following with your specific values to generate a copyable command:
docker ps --filter name=my-vcluster

Configuration options​

Container customization​

  • Image: Specify custom container images for control plane and worker nodes
  • Ports: Expose additional ports from containers to the host
  • Volumes: Mount host directories or Docker volumes
  • Environment Variables: Set custom environment variables
  • Docker Arguments: Pass additional arguments to Docker run commands

Multi-node setup​

Configure multiple worker nodes with individual settings:

experimental:
  docker:
    nodes:
    - name: "worker-1"
      image: "custom-registry/worker:latest"
      ports:
        - "3000:3000"
      volumes:
        - "/host/app:/app"
    - name: "worker-2"
      env:
        - "NODE_ENV=production"
      args:
        - "--privileged"

vCluster VPN​

You can join external nodes to your Docker-based vCluster using the vCluster VPN feature. This requires vCluster Platform to be installed. For detailed setup instructions, see the vCluster VPN documentation.

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

Troubleshoot​

Common issues​

  1. Docker daemon not accessible:

    docker info

  2. Resource constraints: Ensure Docker has sufficient CPU and memory allocated

  3. Permission issues on macOS: Load balancer features may require running Docker with elevated privileges. Try running your terminal as an administrator or ensure Docker Desktop has the necessary permissions in System Preferences > Security & Privacy

Debug​

Modify the following with your specific values to generate a copyable command:
# Check vCluster status
vcluster list

# Show all docker containers
docker ps -a

# View control plane logs
docker exec -it vcluster.cp.my-vcluster journalctl -u vcluster --no-pager

# View kubelet logs
docker exec -it vcluster.node.my-vcluster.my-node journalctl -u kubelet --no-pager

# View containerd logs
docker exec -it vcluster.node.my-vcluster.my-node journalctl -u containerd --no-pager

# View vcluster-vpn logs
docker exec -it vcluster.node.my-vcluster.my-node journalctl -u vcluster-vpn --no-pager

Delete a Docker vCluster​

To remove a Docker-based vCluster and clean up all associated resources:

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

This command removes all Docker containers and networks created for the vCluster. Any data stored in Docker volumes is also deleted.

Next steps​

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.