Skip to main content
Version: main 🚧
Limited vCluster Tenancy Configuration Support

This feature is only available for the following:

Running the control plane as a container and the following worker node types:

Sleep and wakeup vCluster

This page describes how to manually put a virtual cluster to sleep and wake it up using CLI commands. This is different from automatic sleep mode, which automatically manages sleep and wake operations based on activity detection or schedules.

Manual vs automatic sleep mode​

There are two ways to manage sleep for virtual clusters:

  • Manual sleep (this page): Use CLI commands to manually put a vCluster to sleep or wake it up. This is a free feature available to all users.
  • Automatic sleep mode: Configure the vCluster to automatically sleep and wake based on inactivity detection, schedules, or ingress activity. This is an enterprise feature. For details, see the Sleep mode configuration documentation.

When you manually put a virtual cluster to sleep, it temporarily scales down the cluster and deletes all its created workloads on the host cluster. This approach helps save computing resources used by virtual cluster workloads in the host cluster. For example, sleeping development clusters during non-working hours can significantly reduce infrastructure costs.

Prerequisites​

  • Administrator access to a Kubernetes cluster: See Accessing Clusters with kubectl for more information. Run the command kubectl auth can-i create clusterrole -A to verify that your current kube-context has administrative privileges.

    info

    To obtain a kube-context with admin access, ensure you have the necessary credentials and permissions for your Kubernetes cluster. This typically involves using kubectl config commands or authenticating through your cloud provider's CLI tools.

  • helm: Helm v3.10 is required for deploying the platform. Refer to the Helm Installation Guide if you need to install it.

  • kubectl: Kubernetes command-line tool for interacting with the cluster. See Install and Set Up kubectl for installation instructions.

  • vCluster CLI 
    brew install loft-sh/tap/vcluster

    The binaries in the tap are signed using the Sigstore framework for enhanced security.

    Confirm that you've installed the correct version of the vCluster CLI.

    vcluster --version

Put a vCluster to sleep​

Put a virtual cluster to sleep manually with the vCluster CLI:

Sleep a virtual cluster
vcluster platform sleep my-vcluster -n my-vcluster-namespace
CLI reference

Read about using the vcluster platform sleep command.

What happens during manual sleep​

This command performs the following actions:

  • Scales down any StatefulSets or Deployments in the virtual cluster
  • Deletes all workloads created by the virtual cluster on the host cluster

While the command preserves object definitions within the virtual cluster, any standalone pods (those without a controlling replica set or StatefulSet) need to be restarted when the cluster wakes up.

Restarting pods

When pods are restarted:

  • The temporary filesystem is erased
  • Pod IP addresses change

Differences from automatic sleep mode​

Manual sleep differs from automatic sleep mode in several ways:

  • Control: Manual sleep requires explicit CLI commands; automatic sleep mode manages sleep and wake operations automatically based on configuration.
  • Activity detection: Manual sleep doesn't detect activity or wake automatically; automatic sleep mode can detect API calls, ingress traffic, and other activity to wake the cluster.
  • Scheduling: Manual sleep doesn't support schedules; automatic sleep mode can sleep and wake on specific schedules (for example, weekends or off-hours).
  • Resource management: Manual sleep scales down workloads but keeps the control plane active; automatic sleep mode (when connected to the platform via agent) can shut down the control plane completely for greater resource savings.

For automatic sleep mode with activity detection, scheduling, and other advanced features, see the Sleep mode configuration documentation.

Wake up a vCluster​

You can wake up a manually sleeping virtual cluster with two different vCluster CLI commands.

As soon as the virtual cluster is woken up, vCluster scales up any paused StatefulSets or Deployments and the vCluster syncer recreates the vCluster pods onto the host cluster.

Direct wake up​

Wake up the virtual cluster explicitly with a vCluster CLI command:

Wake up a virtual cluster
vcluster platform wakeup my-vcluster -n my-vcluster-namespace
CLI reference

Read about using the vcluster platform wakeup command.

Connect to wake up​

Connect to the virtual cluster with a vCluster CLI command, which automatically wakes up the virtual cluster if it's sleeping:

Connect to wake up a virtual cluster
vcluster connect my-vcluster -n my-vcluster-namespace

When to use manual vs automatic sleep mode​

Choose the approach that best fits your use case:

Use manual sleep when:

  • You want simple, on-demand control over when clusters sleep
  • You don't need automatic activity detection or scheduling
  • You're using the free version of vCluster
  • You prefer explicit control over sleep and wake operations

Use automatic sleep mode when:

  • You want clusters to sleep automatically based on inactivity
  • You need scheduled sleep and wake operations (for example, weekends or off-hours)
  • You want activity detection to automatically wake clusters when needed
  • You want to integrate with platform features like auto-deletion
  • You need advanced configuration options for resource exemptions and request filtering

For automatic sleep mode configuration, see the Sleep mode configuration documentation.