Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/loft-sh/vcluster/llms.txt

Use this file to discover all available pages before exploring further.

​
Synopsis

Debug and troubleshoot virtual cluster issues. 
vcluster debug [command] [flags]

​
Subcommands

  • collect - Collect debug information
  • logs - View vCluster logs

​
vcluster debug collect

Collect comprehensive debug information about a virtual cluster.

​
Synopsis

vcluster debug collect VCLUSTER_NAME [flags]

​
Examples

# Collect debug info
vcluster debug collect my-vcluster -n team-x

# Save to custom location
vcluster debug collect my-vcluster -n team-x --output debug-info.tar.gz

# Include pod logs
vcluster debug collect my-vcluster -n team-x --include-logs

​
Flags

​
--namespace
string
required
The namespace where the vCluster is running.
​
--output
string
Output file path for debug information.
​
--include-logs
boolean
Include pod logs in the debug bundle.
​
--driver
string
default:"helm"
The driver to use.

​
What Gets Collected

The debug collect command gathers:
  • vCluster resources - StatefulSets, Services, ConfigMaps
  • Pod status - Current state of all pods
  • Events - Recent Kubernetes events
  • Logs (if --include-logs is set) - Control plane logs
  • Configuration - Helm values and configuration
  • Version information - vCluster and Kubernetes versions

​
vcluster debug logs

View logs from vCluster control plane.

​
Synopsis

vcluster debug logs VCLUSTER_NAME [flags]

​
Examples

# View logs
vcluster debug logs my-vcluster -n team-x

# Follow logs
vcluster debug logs my-vcluster -n team-x --follow

# Filter by component
vcluster debug logs my-vcluster -n team-x --container syncer

​
Flags

​
--namespace
string
required
The namespace where the vCluster is running.
​
--follow
boolean
Stream logs in real-time.
​
--container
string
Specific container to view logs from.
​
--tail
int
default:"100"
Number of lines to show from the end.

​
Complete Example

troubleshoot.sh
#!/bin/bash
VCLUSTER="problematic-vcluster"
NAMESPACE="team-x"

# Check status
echo "Checking vCluster status..."
vcluster list -n $NAMESPACE

# View logs
echo "Viewing control plane logs..."
vcluster debug logs $VCLUSTER -n $NAMESPACE --tail 50

# Collect debug info
echo "Collecting debug information..."
vcluster debug collect $VCLUSTER -n $NAMESPACE \
  --output debug-$(date +%Y%m%d-%H%M%S).tar.gz \
  --include-logs

echo "Debug information collected."

​
Manual Debugging

For deeper debugging, you can inspect resources directly: 
# Check pod status
kubectl get pods -n team-x

# Describe vCluster pod
kubectl describe pod my-vcluster-0 -n team-x

# Check events
kubectl get events -n team-x --sort-by='.lastTimestamp'

# View syncer logs
kubectl logs -n team-x my-vcluster-0 -c syncer

# Check etcd logs (if deployed)
kubectl logs -n team-x my-vcluster-etcd-0

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us