Skip to main content
Version: v0.35 Stable

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 tenant and control plane clusters
  • integrations.* - Integrations depend on syncing functionality
  • networking.replicateServices - Services are not replicated to host
  • controlPlane.coredns.embedded: true - Embedded CoreDNS conflicts with custom CNI
  • controlPlane.distro.k8s.scheduler.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 tenant and control plane clusters is disabled
sync:
  toHost:
    services:
      enabled: false  # Services cannot be synced to the control plane cluster
    secrets:
      enabled: false  # Secrets cannot be synced to the control plane 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

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

# Service replication (networking.replicateServices) and sleep mode
# (sleep.*) are also unavailable; see the list above.