Troubleshooting vCluster Standalone Control Plane Nodes

Supported Configurations

Running the control plane as a binary with vCluster Standalone. When scaling with additional worker nodes, they are joined as private nodes.

Bringing up a Kubernetes cluster can face challenges, so here are some troubleshooting tips to help get you started.

Check vCluster logs

All vCluster logs are located in the control plane, view service logs using journalctl.

View vCluster service logs

journalctl -u vcluster.service --since="2 minutes ago" -f

Common Issues

Network connectivity

Ensure ports 6443 (API Server) and other required ports are accessible

SystemD service

The vCluster service needs to be running at all times.

systemctl status vcluster.service

Node join failures

Check that join tokens haven't expired and network connectivity exists between nodes.

When running the join node script, if a 400 status code is received, check the URL directly to see if an error message exists. Alternatively you can pipe the entire response to the terminal and print it:

curl -sSLk "https://<endpoint>/node/join?token=<token>" | { response=$(cat); echo "$response" | sh - 2>/dev/null || echo "Error: $response"; }

Resource constraints

Ensure adequate CPU, memory, and disk space on nodes.