Joining External Nodes to vind (Private Nodes)

March 3, 2026 ยท View on GitHub

Important: This guide is for Private Nodes mode, which is different from Docker experimental nodes. Private Nodes allows you to join real worker nodes (like EC2 instances) to your vCluster control plane using VPN.

Prerequisites

  1. Private Nodes enabled in your vCluster
  2. vCluster Platform running (required for VPN)
  3. External node with network access

Step 1: Start vCluster Platform

# Start the platform
vcluster platform start

Step 2: Create Your vind Cluster with Private Nodes

# Create cluster with private nodes and VPN enabled
vcluster create my-cluster \
  --set privateNodes.vpn.enabled=true \
  --set privateNodes.vpn.nodeToNode.enabled=true

Step 3: Get Join Token

# Get the join token
vcluster token create

Save this command.

Step 4: Install vCluster on External Node

On your external node (e.g., EC2 instance) run the command from the previous step:

curl ...

Note: If the join script does not execute directly via curl | bash, download it first and then run it with sudo:

curl -L -o join-script.sh "<join-script-url>"
chmod +x join-script.sh
sudo ./join-script.sh

Real-World Example: GCP Node as External Node

For a complete working example of joining a GCP instance as an external node, see: Replacing KinD with vind - Deep Dive

Step 5: Verify

Back on your local machine:

# Check nodes
kubectl get nodes

# You should see your external node listed!
# NAME           STATUS   ROLES    AGE   VERSION
# my-cluster     Ready    master   5m    v1.28.0
# ec2-instance   Ready    <none>   2m    v1.28.0