Pause & Resume

Pause virtual clusters to save resources and resume them when needed

Overview

Pausing a virtual cluster stops it and frees all computing resources while preserving the cluster state. This is useful for:

• Cost savings: Stop development/test clusters outside business hours
• Resource management: Free up cluster capacity temporarily
• Environment control: Prevent accidental changes during maintenance

Persistent data (PVCs, ConfigMaps, Secrets) is preserved during pause. Only running workloads are stopped.

Pausing a Virtual Cluster

Basic Pause Command

vcluster pause my-vcluster --namespace team-dev

What happens during pause:

1. Scale Down

   The virtual cluster control plane is scaled down to zero replicas.

2. Delete Workloads

   All workloads created through the virtual cluster (Pods, Deployments, etc.) are deleted from the host cluster.

3. Preserve State

   Persistent resources remain:

   • Persistent Volume Claims
   • Services
   • ConfigMaps and Secrets
   • Network policies
4. Release Resources

   Computing resources (CPU, memory) are freed and returned to the host cluster.

Pause Alias

You can also use the sleep alias:

vcluster sleep my-vcluster --namespace team-dev

Resuming a Virtual Cluster

Basic Resume Command

vcluster resume my-vcluster --namespace team-dev

What happens during resume:

1. Scale Up

   The virtual cluster control plane is scaled back to its configured replica count.

2. Restore API Server

   The virtual Kubernetes API server becomes available.

3. Recreate Workloads

   All workloads are automatically recreated from the stored state.

4. Resume Operations

   The virtual cluster is fully operational and ready to accept requests.

Resume Alias

You can also use the wakeup alias:

vcluster wakeup my-vcluster --namespace team-dev

Platform-Managed Sleep

When using vCluster Platform, you can configure automatic sleep policies.

Prevent Wake-up

Pause a virtual cluster and prevent automatic wake-up for a specific duration:

vcluster pause my-vcluster --namespace team-dev --prevent-wakeup 3600

This pauses the virtual cluster for 3600 seconds (1 hour). During this time, it can only be woken up by:

• Running vcluster resume manually
• Removing the sleep annotation from the namespace
• Using the vCluster Platform UI

Infinite Sleep

To pause indefinitely until manually resumed:

vcluster pause my-vcluster --namespace team-dev --prevent-wakeup 0

Driver-Specific Behavior

Helm Driver

vcluster pause my-vcluster --driver helm

• Pauses locally managed virtual clusters
• Scales StatefulSet to zero
• Removes synced workloads from host namespace

Platform Driver

vcluster pause my-vcluster --driver platform --project my-project

• Integrates with Platform sleep policies
• Supports automatic wake-up schedules
• Tracks sleep time for billing/reporting

Docker Driver

vcluster pause my-vcluster --driver docker

• Stops Docker containers
• Preserves container state
• Faster resume times for local development

Verification

Check Sleep Status

After pausing, verify the virtual cluster is sleeping:

vcluster list

Look for status indicators showing the cluster is paused/sleeping.

Verify Resource Release

Check that pods are scaled down:

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

You should see no running pods for the virtual cluster.

Verify State Preservation

Check that persistent resources remain:

kubectl get pvc,svc,configmap -n team-dev

Use Cases

Development Environment Management

Scenario: Pause dev environments outside working hours to save costs.

Implementation:

Create a scheduled job to pause clusters at end of day:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: pause-dev-clusters
spec:
  schedule: "0 18 * * 1-5"  # 6 PM, weekdays
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: pause
            image: loftsh/vcluster-cli:latest
            command:
            - /bin/sh
            - -c
            - |
              vcluster pause dev-cluster-1 --namespace dev-team-1
              vcluster pause dev-cluster-2 --namespace dev-team-2
          restartPolicy: OnFailure

Resume in the morning:

schedule: "0 8 * * 1-5"  # 8 AM, weekdays

Staging Environment Control

Scenario: Keep staging environments paused until deployment time.

Implementation:

Integrate with CI/CD pipeline:

# .gitlab-ci.yml / .github/workflows/deploy.yml
deploy-to-staging:
  script:
    - vcluster resume staging-vcluster --namespace staging
    - kubectl config use-context vcluster_staging-vcluster_staging
    - kubectl apply -f deployment.yaml
    - # Run tests
    - vcluster pause staging-vcluster --namespace staging

Resource Quota Management

Scenario: Temporarily free resources during peak usage times.

Implementation:

# Pause non-critical clusters during production deployment
vcluster pause test-cluster-1 --namespace testing
vcluster pause demo-cluster --namespace demos

# Perform production deployment
kubectl apply -f production-deployment.yaml

# Resume after deployment
vcluster resume test-cluster-1 --namespace testing
vcluster resume demo-cluster --namespace demos

Cost Optimization

Scenario: Automatically pause idle clusters to reduce cloud costs.

Implementation:

Use vCluster Platform’s automatic sleep feature based on inactivity:

Configure in vcluster.yaml:

sleep:
  afterInactivity: 1800  # Sleep after 30 minutes of inactivity
  schedule:
    - from: "18:00"
      to: "08:00"
      weekdays:
        - monday
        - tuesday
        - wednesday
        - thursday
        - friday

Troubleshooting

Resume Fails with Platform Driver Required Error

Error Message:

cannot resume a virtual cluster that is paused by the platform, 
please run 'vcluster use driver platform' or use the '--driver platform' flag

Cause: The virtual cluster was paused by vCluster Platform, not locally.

Solution:

Resume using the platform driver:

vcluster resume my-vcluster --driver platform --project my-project

Or set platform as default driver:

vcluster use driver platform
vcluster resume my-vcluster

Workloads Not Recreating After Resume

Symptoms: Virtual cluster resumes but workloads don’t start.

Diagnosis:

1. Check virtual cluster pod status:

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

2. Check virtual cluster logs:

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

3. Connect to virtual cluster and check:

   vcluster connect my-vcluster --namespace team-dev
   kubectl get pods --all-namespaces
   

Solutions:

• Wait a few minutes for synchronization to complete
• Check for resource quota issues in the host namespace
• Verify network policies aren’t blocking synced resources

Pause Command Hangs

Symptoms: vcluster pause command doesn’t complete.

Diagnosis:

Check if the virtual cluster is accessible:

kubectl get vcluster my-vcluster -n team-dev

Solutions:

1. Force delete workloads manually:

   kubectl delete pods -n team-dev -l vcluster.loft.sh/managed-by=my-vcluster --force
   

2. Scale down the StatefulSet:

   kubectl scale statefulset my-vcluster -n team-dev --replicas=0
   

3. Use platform UI if using platform driver

Best Practices

Automate Sleep Schedules

Use Platform sleep policies or cron jobs to automatically pause clusters during off-hours.

Test Resume Process

Regularly test the resume process to ensure workloads recreate correctly.

Monitor Resume Times

Track how long it takes for clusters to fully resume and optimize as needed.

Document Dependencies

Document any external dependencies that need special handling during pause/resume cycles.

Next Steps

Snapshots

Learn how to create snapshots before pausing for additional safety.