Skip to main content
Version: v0.36 (EOS)

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​

Clients and worker nodes access the cluster API through the vCluster proxy on port 8443, not on port 6443. The Kubernetes API server only listens on 127.0.0.1:6443, so opening port 6443 isn't necessary.

If kubectl or a node join can't connect, confirm that port 8443 on the control plane node is open to your workstation and all worker nodes. To check the listening addresses on the control plane node, run:

Check the API listeners
sudo ss -tlnp | grep -E ':(6443|8443)\b'

In the output, expect 0.0.0.0:8443 or *:8443 for the vCluster proxy and 127.0.0.1:6443 for the API server. For the full list of ports, see Required ports.

The systemd service​

The vCluster service needs to be running at all times.

Verify the vCluster service is running
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:

Print node join response
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.