Skip to main content
Version: v0.36

Pause and resume a tenant cluster

Supported Configurations
Running the control plane as a container with:

Pause a tenant clusterTenant clusterA fully isolated Kubernetes environment provisioned for a single tenant. Each tenant cluster has its own API server, controller manager, and resource namespace, backed by a virtualized control plane hosted on a control plane cluster. From the tenant's perspective it behaves exactly like a standard Kubernetes cluster.Related: Control plane cluster, Tenant cluster when you want to stop it on demand and free its compute resources. Resume it when you need it again. Manual pause doesn't start from an inactivity timeout or schedule.

For automatic behavior, see Configure auto sleep.

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.

    Verify the CLI installed successfully.

    vcluster --version

    Output is similar to:

    vCluster version 0.x.x

Pause a tenant cluster​

Run the following command against the Kubernetes context that contains the tenant cluster:

Pause a tenant cluster
vcluster pause <vcluster-name> --namespace <vcluster-namespace>

The command uses the driver in the vcluster CLI configuration. The default is helm. Select a different driver with --driver; supported values are helm, platform, and docker.

For a platform-managed tenant cluster, you can identify it by project instead:

Pause a platform-managed tenant cluster
vcluster pause <vcluster-name> --driver platform --project <project-name>

With the Platform driver, add --prevent-wakeup <seconds> to prevent automatic wakeup for a period. Use --prevent-wakeup 0 to require an explicit wakeup through the CLI or Platform UI. This flag doesn't apply to the Helm or Docker drivers. Without this flag, Kubernetes API requests routed through the platform and supported HTTP traffic can wake the tenant cluster.

CLI reference

See the vcluster pause CLI reference for all flags.

What pause changes​

The effect of pause depends on the deployment driver:

  • The Helm driver scales down the tenant cluster control planeControl PlaneThe container orchestration layer that exposes the API and interfaces to define, deploy, and manage the lifecycle of containers. In vCluster, each tenant cluster has its own control plane components.Related: API Server, vCluster and deletes its synced physical workload Pods from the control plane clusterControl plane clusterThe Kubernetes cluster that hosts the virtualized control planes for tenant clusters. The control plane cluster is operated by the platform provider and is completely invisible to tenants. There are no shared control plane nodes, no in-cluster agent pods, and no lateral path between tenant environments. With shared nodes, this cluster also runs tenant workloads alongside the control plane pods — the same node pool is used for both.Related: Tenant cluster, Control plane cluster, Tenant cluster.
  • The Platform driver puts the tenant cluster instance to sleep. The platform can scale down both its control plane and physical workloads.
  • The Docker driver stops the tenant cluster control plane, node, and load balancer containers.

The tenant cluster's Kubernetes API objects remain, and PersistentVolumeClaims, Services, and other non-workload resources aren't deleted by pause. With the Helm and Platform drivers, resume recreates physical workload Pods the same way as platform-managed auto sleep, including Pods without a Kubernetes workload controller.

Resume a tenant cluster​

Resume a paused tenant cluster with the same name and deployment context:

Resume a tenant cluster
vcluster resume <vcluster-name> --namespace <vcluster-namespace>

For a platform-managed tenant cluster identified by project, run:

Resume a platform-managed tenant cluster
vcluster resume <vcluster-name> --driver platform --project <project-name>

With the Helm or Platform driver, you can also connect to a paused tenant cluster. Unless wakeup is currently prevented, the connection resumes the tenant cluster automatically.

For the Helm driver, run:

Connect and resume
vcluster connect <vcluster-name> --namespace <vcluster-namespace>

For the Platform driver, run:

Connect to and resume a platform-managed tenant cluster
vcluster connect <vcluster-name> --driver platform --project <project-name>

The Docker driver requires vcluster resume before vcluster connect.

CLI reference

See the vcluster resume CLI reference for all flags.

Manual pause compared with auto sleep​

CapabilityManual pauseAuto sleep
Start conditionCLI commandInactivity timeout, schedule, or manual action
Automatic wakeup from activityHelm: CLI connection. Platform: platform-proxied API, supported HTTP traffic, or CLI connection. Docker: none.Inactivity sleep: Kubernetes API or supported HTTP traffic. Platform-scheduled sleep waits for its wakeup schedule or a manual wakeup.
Scheduled sleep and wakeupNoYes
Auto-delete after inactivityNot configured by pause; available separately for platform-managed tenant clusters.Not configured by auto sleep; available separately for platform-managed tenant clusters.

See Sleep tenant clusters for an overview of the available sleep methods.