Docker Machine Driver for VergeOS

A Docker Machine driver for VergeOS. Works as a standalone Docker Machine driver and as a Rancher node driver for provisioning RKE2/K3s clusters.

The driver clones a template VM, injects SSH keys via cloud-init, and manages the full VM lifecycle through the VergeOS API.

Requirements

• Go 1.24+ (to build from source)
• Docker Machine
• A VergeOS environment with:
  • API access (API key or username/password)
  • A template VM with cloud-init installed (see Template VM Preparation)
  • A virtual network for the VM to attach to

Installation

From source

git clone https://github.com/verge-io/docker-machine-driver-vergeos.git
cd docker-machine-driver-vergeos
make install

This builds the binary and copies it to $(go env GOPATH)/bin/.

Pre-built binaries

Download from the Releases page and place the binary in your $PATH.

Rancher Node Driver

The driver must be registered via kubectl — the Rancher UI's "Add Node Driver" form does not support the required credential field annotations.

Host the driver binary on an HTTP/HTTPS server accessible from the Rancher cluster, then apply:

kubectl apply -f - <<'EOF'
apiVersion: management.cattle.io/v3
kind: NodeDriver
metadata:
  annotations:
    lifecycle.cattle.io/create.node-driver-controller: "true"
    privateCredentialFields: "apiKey"
    publicCredentialFields: "host,insecure"
  finalizers:
  - controller.cattle.io/node-driver-controller
  labels:
    cattle.io/creator: norman
  name: vergeos
spec:
  active: true
  displayName: vergeos
  url: "http://<hostname-or-ip>/docker-machine-driver-vergeos-linux-amd64"
EOF

Replace the url with the location of your hosted binary.

After applying, restart Rancher so it picks up the new driver schema:

kubectl rollout restart deployment rancher -n cattle-system

Once Rancher restarts, "VergeOS" will appear as a node driver option when creating clusters. Cloud credentials will prompt for host, API key, and insecure fields.

Usage

docker-machine create \
  --driver vergeos \
  --vergeos-host vergeos.example.com \
  --vergeos-api-key your-api-key \
  --vergeos-insecure \
  --vergeos-template-vm ubuntu-2404 \
  --vergeos-network your-network-name \
  --vergeos-ssh-user ubuntu \
  --vergeos-cpu-cores 2 \
  --vergeos-ram 4096 \
  --vergeos-disk-size 30 \
  my-docker-host

Then use it like any Docker Machine host:

eval $(docker-machine env my-docker-host)
docker ps

Options

Flag	Env Variable	Default	Description
--vergeos-host	VERGEOS_HOST	—	VergeOS host or URL (e.g., vergeos.example.com; defaults to https://)
--vergeos-api-key	VERGEOS_API_KEY	—	API key for authentication (required)
--vergeos-insecure	VERGEOS_INSECURE	false	Skip TLS certificate verification
--vergeos-template-vm	VERGEOS_TEMPLATE_VM	—	Name or ID of the template VM to clone (required)
--vergeos-network	VERGEOS_NETWORK	—	Name or ID of the network to attach to (required)
--vergeos-cpu-cores	VERGEOS_CPU_CORES	2	Number of CPU cores
--vergeos-ram	VERGEOS_RAM	2048	RAM in MB
--vergeos-disk-size	VERGEOS_DISK_SIZE	0	Primary disk size in GB (0 = keep template size)
--vergeos-cloudinit	VERGEOS_CLOUDINIT	—	Path to cloud-init user-data file, or inline cloud-config
--vergeos-ssh-user	VERGEOS_SSH_USER	root	SSH username
--vergeos-ssh-port	VERGEOS_SSH_PORT	22	SSH port

Authentication requires --vergeos-api-key. Generate an API key in the VergeOS UI under User Settings.

Template VM Preparation

Minimum requirements

1. cloud-init installed and enabled — the driver injects SSH keys and sets the hostname via a multi-part MIME cloud-init payload
2. QEMU guest agent (recommended) — enables accurate IP discovery; without it the driver falls back to NIC DHCP lease IPs

Standalone Docker Machine

When used as a standalone docker-machine driver, the template VM also needs Docker installed (or use --vergeos-cloudinit to install it on first boot). Docker Machine's built-in provisioner configures Docker over SSH after the VM boots.

Rancher Node Driver

When used as a Rancher node driver for RKE2/K3s clusters, Docker is not required — Rancher installs its own container runtime (containerd) via the system agent. The template only needs cloud-init and the guest agent.

Ubuntu 24.04

Ubuntu 24.04 (Noble Numbat) is the recommended template OS. The driver automatically handles the following Ubuntu 24.04 specifics via cloud-init:

• Netplan DHCP configuration — writes a netplan config matching en* interfaces with dhcp4: true, handling PCI slot name changes (ens0/ens1/etc) across clones
• Machine-ID regeneration — regenerates /etc/machine-id on each clone so that each VM gets a unique DHCP client identifier (DUID). Without this, cloned VMs share the template's DUID and DHCP servers assign them identical IPs.
• Cached DHCP lease cleanup — removes stale DHCP leases inherited from the template

For Rancher use, allocate at least 4 GB RAM per node (8 GB recommended). A single-node RKE2 cluster with Calico CNI will OOM with 2 GB.

Custom User Data

You can provide additional cloud-init configuration that gets merged with the driver's SSH key injection:

# From a file
docker-machine create --driver vergeos \
  --vergeos-cloudinit /path/to/userdata.yaml \
  ...

# Inline
docker-machine create --driver vergeos \
  --vergeos-cloudinit '#cloud-config
packages:
  - nginx' \
  ...

The driver auto-detects the content type (#cloud-config, #!/bin/bash, #include, #cloud-boothook) and wraps everything in a multi-part MIME envelope so SSH keys are always injected regardless of user-data format.

How It Works

1. Clone the template VM with the requested machine name
2. Configure CPU cores, RAM, and cloud-init (SSH keys + hostname + optional user-data)
3. Resize the primary disk if --vergeos-disk-size is set
4. Attach the VM to the specified network
5. Power on and wait for an IP address (guest agent preferred, NIC DHCP fallback)

If any step fails, the driver cleans up the partially-created VM automatically.

Building

make build       # Build for current platform
make install     # Build and install to $GOPATH/bin
make dist        # Cross-compile for linux/darwin amd64/arm64
make clean       # Remove build artifacts

License

See LICENSE.