Managing Virtual Clusters

Day-to-day operations for managing your virtual clusters

Overview

vCluster provides a comprehensive CLI for managing the lifecycle of your virtual clusters. This guide covers the essential day-to-day operations you’ll need to effectively manage your vClusters.

Listing Virtual Clusters

View all virtual clusters in your environment to get an overview of your deployment.

Basic List Command

vcluster list

This command displays all virtual clusters across all namespaces in a table format with key information:

• Virtual cluster name
• Namespace
• Status (Running, Sleeping, etc.)
• Age
• Connection status

List Options

JSON Output

vcluster list --output json

Returns structured JSON output for programmatic access or integration with other tools.

Specific Namespace

vcluster list --namespace team-dev

Filter results to a specific namespace.

Specific Driver

vcluster list --driver helm

List virtual clusters managed by a specific driver (helm, platform, or docker).

Describing a Virtual Cluster

Get detailed information about a specific virtual cluster.

vcluster describe my-vcluster

Output Formats

1. YAML Output

   Get the full configuration in YAML format:

   vcluster describe my-vcluster -o yaml
   

   This shows the complete vCluster configuration including all runtime settings.

2. JSON Output

   For programmatic access:

   vcluster describe my-vcluster -o json
   
3. Configuration Only

   Extract just the vcluster.yaml configuration:

   vcluster describe my-vcluster --config-only
   

   Useful for backing up or comparing configurations.

Connecting to a Virtual Cluster

Switch your kubectl context to interact with a virtual cluster.

vcluster connect my-vcluster --namespace team-dev

What happens:

1. Creates a port-forward to the virtual cluster’s API server
2. Updates your kubeconfig with a new context
3. Switches to the new context automatically
4. You can now use kubectl commands against the virtual cluster

The connection requires the port-forward to remain active. Keep the terminal window open or run with --background flag.

Disconnecting from a Virtual Cluster

Return to your host cluster context.

vcluster disconnect

This removes the virtual cluster context and closes any active port-forwards.

Deleting a Virtual Cluster

Remove a virtual cluster and its resources.

Deletion is permanent. Ensure you have backups of any important data before proceeding.

Standard Deletion

vcluster delete my-vcluster --namespace team-dev

Force Deletion

If a virtual cluster is stuck or not responding:

vcluster delete my-vcluster --namespace team-dev --force

Deletion with Cleanup

vcluster delete my-vcluster --namespace team-dev --delete-namespace

This also removes the host namespace after deleting the virtual cluster.

Platform Integration

When using vCluster Platform, specify the project context:

vcluster list --project my-project
vcluster describe my-vcluster --project my-project
vcluster delete my-vcluster --project my-project

Driver Selection

vCluster supports multiple drivers for different deployment modes:

• helm: Direct Helm-based deployment (default)
• platform: vCluster Platform-managed deployment
• docker: Docker-based local development

Set the default driver in your config:

vcluster use driver platform

Or specify per-command:

vcluster list --driver helm

Common Management Tasks

Check Virtual Cluster Status

vcluster list | grep my-vcluster

Or for detailed status:

kubectl get vcluster my-vcluster -n team-dev

View Virtual Cluster Logs

kubectl logs -n team-dev -l app=vcluster,release=my-vcluster

For continuous streaming:

kubectl logs -n team-dev -l app=vcluster,release=my-vcluster -f

Update Virtual Cluster Configuration

1. Export current configuration:

   vcluster describe my-vcluster --config-only > vcluster.yaml
   

2. Edit the configuration file

3. Apply changes:

   helm upgrade my-vcluster vcluster -n team-dev -f vcluster.yaml
   

Check Resource Usage

View pods in the host namespace:

kubectl top pods -n team-dev

View resource requests/limits:

kubectl describe statefulset -n team-dev my-vcluster

Troubleshooting

Virtual Cluster Not Responding

Symptoms: Commands hang or timeout

Solutions:

1. Check pod status:

   kubectl get pods -n team-dev -l release=my-vcluster
   

2. Check logs for errors:

   kubectl logs -n team-dev -l app=vcluster,release=my-vcluster
   

3. Restart the virtual cluster:

   kubectl rollout restart statefulset -n team-dev my-vcluster
   

Next Steps

Pause & Resume

Learn how to pause virtual clusters to save resources

Snapshots

Create point-in-time snapshots of your virtual clusters

Monitoring

Set up monitoring for your virtual clusters

Troubleshooting

Resolve common issues