Virtual Cluster Auto Sleep and Auto Delete

Overview #

Your virtual cluster automatically puts itself to sleep when inactive to save costs, and gets deleted if it stays inactive for too long. This is already enabled on your virtual cluster.

Prerequisites #

This feature is only available on the vcluster-pro template, starting from v1.3.0. Virtual clusters on older template versions or the OSS/community template will not have this behavior.

Current settings #

• Auto-sleep: the virtual cluster goes to sleep after 3 days of no activity.
• Auto-delete: the virtual cluster is deleted after 15 days of no activity (sleeping or not).

What happens when your virtual cluster sleeps #

• All pods inside the virtual cluster are stopped (replicas are scaled to 0 for Deployments, StatefulSets, etc.).
• Nothing is deleted — all your resource configurations (Deployments, Services, ConfigMaps, PVCs, etc.) stay exactly as they are.
• The virtual cluster can be brought back with no data loss.

Step 1: Wake up a sleeping virtual cluster #

A sleeping virtual cluster wakes up automatically as soon as there’s activity against it, such as:

• Running any kubectl command against the virtual cluster.
• Any Kubernetes API request targeting the virtual cluster.
• An incoming request through an nginx-based ingress.
• Manually triggering a wakeup from the UI or CLI.

Note: only ingress-nginx automatically counts incoming traffic as activity. If you use a different ingress controller, incoming requests won’t wake the virtual cluster on their own — use kubectl or the UI/CLI instead.

Step 2: Understand what counts as activity #

The 3-day and 15-day timers are both driven by the same definition of “activity,” per the platform docs:

• Any request made through the platform counts as activity: If your kubeconfig context points at the platform’s API server (which proxies to your virtual cluster), every kubectl command — or any tool making a Kubernetes API request — resets the inactivity timer.
• Ingress traffic counts too, for nginx-based ingresses: The platform adds a tracking annotation to each ingress so that incoming requests reset the timer automatically.
• Open connections count as ongoing activity by default: A kubectl exec or port-forward session left open is treated as continuous activity and, by default, is not timed out — so it will keep resetting the clock for as long as it stays open, unless an idle timeout has been configured for the cluster.

In short: as long as something is interacting with your virtual cluster through the platform, the inactivity clock keeps resetting — it only starts counting down once everything goes quiet.

Step 3: Know when auto-delete kicks in #

If the virtual cluster has had no activity for 15 days, it is automatically deleted — this is independent of whether it’s currently asleep or awake. If you have work in a virtual cluster you don’t want deleted, interact with it (or explicitly wake/use it) before the 15-day mark.

Step 4: Prevent auto-delete entirely #

If you have a virtual cluster that must never be auto-deleted — regardless of how long it sits inactive — add this annotation to its VirtualClusterInstance:

loft.sh/non-deletable: "true"

Important: this doesn’t just block auto-delete — it blocks all deletion, including a manual/deliberate delete. If you later do want to delete the virtual cluster, you must first remove the annotation (or turn the toggle back off in the UI), then delete it as usual. It also has no effect on auto-sleep — a protected virtual cluster can still go to sleep after 3 days of inactivity, it just won’t be deleted at the 15-day mark.

Good to know #

• Leaving a kubectl exec or port-forward session open will keep the virtual cluster from sleeping for as long as that session is open, since it counts as ongoing activity by default.
• Sleep and delete timers are based on inactivity, not wall-clock schedules — as long as something is generating activity, the virtual cluster stays awake and the inactivity clock keeps resetting.
• If your kubectl context talks directly to the underlying cluster instead of through the platform’s API server, those requests won’t be seen as activity — make sure you’re using the platform-provided context.

Summary: dos and don’ts #

Edit this page on GitHub