fix(snapshot): refuse standalone restore while vcluster.service is active

cmd/vcluster/cmd/snapshot/restore.go

@@ -5,7 +5,9 @@ import (
 	"os"
 
 	"github.com/loft-sh/vcluster/pkg/config"
+	"github.com/loft-sh/vcluster/pkg/constants"
 	"github.com/loft-sh/vcluster/pkg/snapshot"
+	standaloneutil "github.com/loft-sh/vcluster/pkg/util/standalone"
 	"github.com/spf13/cobra"
 )
 
@@ -17,8 +19,34 @@ func NewRestoreCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "restore",
 		Short: "Restore a vCluster",
-		Args:  cobra.NoArgs,
+		Long: `Restores the vCluster backing store from a snapshot. This is an internal
+command: it must only run while the vCluster control plane is down, and it is
+normally invoked by the vcluster CLI or by the snapshot pod.
+
+On a standalone host, use "vcluster restore --standalone <snapshot-url>" (the
+vcluster CLI) instead of calling this command directly: the CLI stops
+vcluster.service, runs this command, and restarts the service afterwards.
+Direct invocations while vcluster.service is active are refused to protect
+the backing store.`,
+		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
+			// A restore rewrites the backing store and must never run while the
+			// standalone control plane is up: it would race the live kine/etcd,
+			// and the unit's Restart=always re-spawns a crashed server
+			// mid-restore. The vcluster CLI ("vcluster restore --standalone")
+			// stops and restarts the service around this command; refuse direct
+			// invocations that skipped that envelope. On hosts without systemd
+			// (e.g. the in-pod restore path) this reports not-active and the
+			// restore proceeds.
+			if standaloneutil.IsServiceActive() {
+				return fmt.Errorf(
+					"refusing to restore: %s.service is active on this host; use the vcluster CLI (%q), which stops and restarts the service around the restore, or stop it first with %q",
+					constants.VClusterStandaloneSystemdServiceName,
+					"vcluster restore --standalone <snapshot-url>",
+					"systemctl stop "+constants.VClusterStandaloneSystemdServiceName,
+				)
+			}
+
 			vConfig, err := config.LoadConfig(os.Getenv("VCLUSTER_NAME"))
 			if err != nil {
 				return err

cmd/vclusterctl/cmd/restore.go

@@ -55,6 +55,8 @@ vcluster restore my-vcluster container:///data/my-local-snapshot.tar.gz
 vcluster restore my-vcluster ./my-snapshot.tar.gz --driver docker
 # Restore with a different name
 vcluster restore my-new-name ./my-snapshot.tar.gz --driver docker
+# Restore the standalone vCluster on this host (stops and restarts vcluster.service)
+vcluster restore --standalone s3://my-bucket/my-bucket-key
 #######################################################
 	`,
 		Args: func(cobraCmd *cobra.Command, args []string) error {

pkg/util/standalone/service_manager.go

@@ -40,6 +40,25 @@ func NewServiceManager() (ServiceManager, error) {
 	return newServiceManager(defaultSystemctlRunner)
 }
 
+// IsServiceActive reports whether the standalone vCluster systemd unit is
+// currently active on this host. It reports false wherever systemd cannot
+// answer affirmatively (non-Linux, no systemctl binary, systemd not running,
+// unit stopped or not installed), so callers can use it as a guard that only
+// engages on a standalone host with a running control plane.
+func IsServiceActive() bool {
+	if runtime.GOOS != "linux" {
+		return false
+	}
+	return isServiceActive(defaultSystemctlRunner)
+}
+
+func isServiceActive(run systemctlRunner) bool {
+	// "systemctl is-active" exits zero only when the unit is active; a missing
+	// systemctl binary, an unreachable systemd, a stopped unit, and an unknown
+	// unit all exit non-zero and therefore report not-active.
+	return run("is-active", "--quiet", constants.VClusterStandaloneSystemdServiceName) == nil
+}
+
 func newServiceManager(run systemctlRunner) (ServiceManager, error) {
 	if runtime.GOOS != "linux" {
 		return nil, fmt.Errorf("systemd manager is only supported on Linux (current OS: %s)", runtime.GOOS)

pkg/util/standalone/service_manager_test.go

@@ -3,7 +3,10 @@ package standalone
 import (
 	"errors"
 	"runtime"
+	"slices"
 	"testing"
+
+	"github.com/loft-sh/vcluster/pkg/constants"
 )
 
 func fakeRunner(catErr, stopErr, startErr error) systemctlRunner {
@@ -74,6 +77,28 @@ func TestServiceManager_StopStart(t *testing.T) {
 	}
 }
 
+// TestIsServiceActive verifies the is-active probe: an affirmative systemctl
+// exit reports active, any failure (stopped unit, unknown unit, no systemd)
+// reports not-active. isServiceActive has no GOOS gate, so this runs anywhere.
+func TestIsServiceActive(t *testing.T) {
+	var gotArgs []string
+	active := isServiceActive(func(args ...string) error {
+		gotArgs = args
+		return nil
+	})
+	if !active {
+		t.Fatal("expected active when systemctl is-active succeeds")
+	}
+	wantArgs := []string{"is-active", "--quiet", constants.VClusterStandaloneSystemdServiceName}
+	if !slices.Equal(gotArgs, wantArgs) {
+		t.Fatalf("systemctl args = %v, want %v", gotArgs, wantArgs)
+	}
+
+	if isServiceActive(func(...string) error { return errors.New("inactive") }) {
+		t.Fatal("expected not-active when systemctl is-active fails")
+	}
+}
+
 // TestNewServiceManager_ServiceDown verifies that NewServiceManager succeeds even
 // when the service exists but is not active (the restore scenario).
 func TestNewServiceManager_ServiceDown(t *testing.T) {