Skip to main content
Version: main 🚧

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.

Unsupported configuration options​

Other vCluster feature limitations​

Certain vCluster features are automatically disabled or unavailable. If you include these options in your vcluster.yaml, they are ignored or might cause configuration errors.

The following features are not available:

  • sync.* - No resource syncing between virtual and host clusters
  • integrations.* - Integrations depend on syncing functionality
  • networking.replicateServices - Services are not replicated to host
  • controlPlane.distro.k3s - Only standard Kubernetes (k8s) is supported
  • controlPlane.coredns.embedded: true - Embedded CoreDNS conflicts with custom CNI
  • controlPlane.advanced.virtualScheduler.enabled: false - Virtual scheduler cannot be disabled
  • sleep.* - No ability to use auto sleep for workloads or control plane
Unsupported vcluster.yaml options with private nodes
# These configurations are NOT supported with private nodes

# Resource syncing between virtual and host clusters is disabled
sync:
  services:
    enabled: false  # Services cannot be synced to host cluster
  secrets:
    enabled: false  # Secrets cannot be synced to host cluster
                    # All other sync options (pods, configmaps, etc.) are also disabled

# Platform integrations require syncing functionality
integrations:
  metricsServer:
    enabled: false  # Metrics server integration not supported
                    # All other integrations are disabled due to sync dependency

# Service replication to host cluster is not available
networking:
  replicateServices:
    enabled: false  # Services run entirely within virtual cluster

# Distribution restrictions
controlPlane:
  distro:
    k3s:
      enabled: false  # k3s distribution not supported
    k8s:
      enabled: true   # Only standard Kubernetes works

  # DNS configuration limitations
  coredns:
    embedded: false   # Embedded CoreDNS conflicts with custom CNI options
  advanced:
    # Virtual scheduler is required for workload placement
    virtualScheduler:
      enabled: true   # Always enabled (cannot be disabled)
  # Host Path Mapper is not supported
  hostPathMapper:
    enabled: false

# Sleep mode is not available
sleep:
  enabled: false