Consolidate Windows snapshot coverage

Author: sjmiller609

.github/workflows/test.yml

@@ -150,29 +150,22 @@ jobs:
           done
           exit 1
 
-      - name: Test Windows snapshots and forks
+      - name: Test Windows stopped forks
         run: |
           TEST_PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:$PATH"
-          for test_name in \
-            TestWindowsStandbyRestoreIntegration \
-            TestWindowsStandbyForkIntegration \
-            TestWindowsForkIntegration; do
-            passed=false
-            for attempt in 1 2 3; do
-              if sudo env \
-                "PATH=$TEST_PATH" \
-                "CI=true" \
-                "HYPEMAN_RUN_WINDOWS_SNAPSHOT_INTEGRATION=1" \
-                "HYPEMAN_WINDOWS_OVMF_CODE=$HYPEMAN_WINDOWS_OVMF_CODE" \
-                "HYPEMAN_WINDOWS_OVMF_VARS=$HYPEMAN_WINDOWS_OVMF_VARS" \
-                go test -count=1 -run "^${test_name}$" -timeout 2m ./lib/instances; then
-                passed=true
-                break
-              fi
-              test "$attempt" = 3 || sleep 5
-            done
-            test "$passed" = true || exit 1
+          for attempt in 1 2 3; do
+            if sudo env \
+              "PATH=$TEST_PATH" \
+              "CI=true" \
+              "HYPEMAN_RUN_WINDOWS_LIFECYCLE_INTEGRATION=1" \
+              "HYPEMAN_WINDOWS_OVMF_CODE=$HYPEMAN_WINDOWS_OVMF_CODE" \
+              "HYPEMAN_WINDOWS_OVMF_VARS=$HYPEMAN_WINDOWS_OVMF_VARS" \
+              go test -count=1 -run '^TestWindowsStoppedForkIntegration$' -timeout 2m ./lib/instances; then
+              exit 0
+            fi
+            test "$attempt" = 3 || sleep 5
           done
+          exit 1
 
       # Slash-command runs are maintainer-approved and need authenticated pulls
       # for images that are not covered by the prewarm cache.

docs/windows-images.md

@@ -13,7 +13,7 @@ A machine image uses these OCI config labels:
 | `io.hypeman.machine-image.base` | omitted | digest-pinned base reference |
 | `io.hypeman.machine-image.tpm` | `2.0` | `2.0` |
 | `io.hypeman.machine-image.secure-boot` | `required` | `required` |
-| `io.hypeman.machine-image.bitlocker` | omitted | `disabled` for forkable personas; `reseal-required` otherwise |
+| `io.hypeman.machine-image.bitlocker` | omitted | `disabled` for forkable images; `reseal-required` otherwise |
 
 The base must be pulled before its dependent Windows images. A base cannot be deleted while any cached image references its digest. Instance references are not tracked by the image cache, matching existing Linux behavior: do not delete a base while a dependent Windows instance exists.
 

docs/windows-snapshots.md

@@ -12,20 +12,12 @@ A fork receives independent disk and NVRAM files. A stopped fork removes the cop
 
 The Windows guest agent writes a new `MachineGuid` and records the child instance ID before the child is returned. Memory forks retain the source SID and hostname, and services that cached `MachineGuid` before standby may observe the previous value until the next cold boot.
 
-Fork admission requires the persona OCI label:
+Fork admission requires the image OCI label:
 
 ```text
 io.hypeman.machine-image.bitlocker=disabled
 ```
 
-Personas marked `reseal-required`, unlabeled personas, and unknown policies can still use same-instance snapshots, but cannot be forked. Hypeman does not expose a child whose encrypted disk was cloned without resealing it to the child's TPM.
+Images marked `reseal-required`, unlabeled images, and unknown policies can still use same-instance snapshots, but cannot be forked. Hypeman does not expose a child whose encrypted disk was cloned without resealing it to the child's TPM.
 
 Stopped forks cold-boot with a unique vsock CID and can run concurrently. A standby snapshot contains the Windows VioSock driver's current CID in guest memory, so a memory-restored child initially retains that CID. The source and child must not be restored concurrently until the child has been stopped and cold-started; Hypeman reports a state error instead of allowing QEMU to fail with a CID collision. Creating a running fork directly from a running Windows source therefore requires `target_state=Stopped`.
-
-## Integration gates
-
-- `TestWindowsStandbyRestoreIntegration` verifies identity-preserving standby/restore and the stopped snapshot restore/fork APIs.
-- `TestWindowsStandbyForkIntegration` verifies a captured desktop memory fork, inherited guest and TPM endorsement-key state, a fresh `MachineGuid`, and independent NVRAM/disk files.
-- `TestWindowsForkIntegration` verifies independent guest writes and a fresh TPM endorsement key for cold-booted stopped forks.
-
-The private Windows fixture and its license are not stored in this repository.

lib/instances/README.md

@@ -36,6 +36,14 @@ Windows uses the same host-side TAP allocation as Linux. Once the guest agent is
 
 Create treats network configuration as part of readiness and tears down a VM if it fails. Start reapplies the current allocation because a stopped instance may receive a different address or MAC before its next boot.
 
+### Windows snapshots and forks
+
+A Windows machine consists of its writable qcow2 disk, Secure Boot NVRAM, software TPM state, saved QEMU configuration, and—while in standby—memory and device state. Same-instance restore keeps these components together so Windows identity and TPM state remain stable.
+
+Forking separates identity according to the boot path. A stopped fork receives independent disk and NVRAM files, clears copied TPM state, cold-boots with a new VioSock CID, and asks the guest agent to assign a new `MachineGuid`. A memory fork must retain the captured TPM and VioSock state from QEMU's migration stream; it receives independent files and a new `MachineGuid`, but inherits the TPM endorsement key until its next cold boot. The source and memory-restored child cannot run concurrently with the same captured CID.
+
+Fork admission requires the image to declare `io.hypeman.machine-image.bitlocker=disabled`. Other policies remain valid for same-instance snapshots but are rejected for forks because Hypeman does not reseal BitLocker keys to a child TPM.
+
 ### Why Config Disk? (configdisk.go)
 
 **What:** Read-only erofs disk with instance configuration

lib/instances/windows.go

@@ -57,7 +57,7 @@ func validateWindowsCreate(req CreateInstanceRequest, image *images.Image, caps
 
 func validateWindowsForkPolicy(stored *StoredMetadata) error {
 	if stored != nil && isWindowsPlatform(stored.Platform) && stored.WindowsBitLockerPolicy != "disabled" {
-		return fmt.Errorf("%w: Windows forks require a persona declared with %s=disabled", ErrNotSupported, images.MachineImageBitLockerLabel)
+		return fmt.Errorf("%w: Windows forks require an image declared with %s=disabled", ErrNotSupported, images.MachineImageBitLockerLabel)
 	}
 	return nil
 }

…ows_networking_integration_linux_test.go …dows_lifecycle_integration_linux_test.golib/instances/windows_networking_integration_linux_test.go renamed to lib/instances/windows_lifecycle_integration_linux_test.go lib/instances/windows_networking_integration_linux_test.go renamed to lib/instances/windows_lifecycle_integration_linux_test.go

@@ -24,26 +24,97 @@ import (
 )
 
 func TestWindowsLifecycleIntegration(t *testing.T) {
+	manager, p, image := setupWindowsLifecycleIntegration(t)
+	ctx := context.Background()
+	source := createWindowsLifecycleInstance(t, ctx, manager, image, "windows-lifecycle-source", true)
+
+	assertWindowsGuestControl(t, ctx, manager, source.Id)
+	assertWindowsNetworkReady(t, ctx, manager, source.Id, source.IP)
+	sourceMachineID := windowsMachineID(t, ctx, manager, source.Id)
+	sourceTPMEK := windowsTPMEK(t, ctx, manager, source.Id)
+	windowsPowerShell(t, ctx, manager, source.Id, `New-Item -ItemType Directory -Force C:\ProgramData\Hypeman | Out-Null; Set-Content C:\ProgramData\Hypeman\standby.txt inherited`)
+
+	standby, err := manager.StandbyInstance(ctx, source.Id, StandbyInstanceRequest{})
+	require.NoError(t, err)
+	require.Equal(t, StateStandby, standby.State)
+	forked, err := manager.ForkInstance(ctx, source.Id, ForkInstanceRequest{
+		Name:        "windows-standby-child",
+		TargetState: StateRunning,
+	})
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = deleteTestInstanceNow(context.Background(), manager, forked.Id) })
+	assert.Equal(t, source.VsockCID, forked.VsockCID, "memory-restored Windows forks retain the captured VioSock CID until cold boot")
+	assert.NotEqual(t, sourceMachineID, windowsMachineID(t, ctx, manager, forked.Id))
+	assert.Equal(t, sourceTPMEK, windowsTPMEK(t, ctx, manager, forked.Id), "memory forks inherit TPM state from the QEMU migration stream")
+	assert.Equal(t, "inherited", windowsPowerShell(t, ctx, manager, forked.Id, `Get-Content C:\ProgramData\Hypeman\standby.txt`))
+	assertIndependentFile(t, p.InstanceOVMFVars(source.Id), p.InstanceOVMFVars(forked.Id))
+	assertIndependentFile(t, p.InstanceWindowsDisk(source.Id), p.InstanceWindowsDisk(forked.Id))
+
+	stoppedFork, err := manager.StopInstance(ctx, forked.Id)
+	require.NoError(t, err)
+	require.Equal(t, StateStopped, stoppedFork.State)
+	restored, err := manager.RestoreInstance(ctx, source.Id)
+	require.NoError(t, err)
+	waitForWindowsRunning(t, ctx, manager, restored.Id)
+	assert.Equal(t, sourceMachineID, windowsMachineID(t, ctx, manager, restored.Id), "same-instance restore must preserve Windows identity")
+	assertWindowsNetworkReady(t, ctx, manager, restored.Id, source.IP)
+}
+
+func TestWindowsStoppedForkIntegration(t *testing.T) {
+	manager, p, image := setupWindowsLifecycleIntegration(t)
+	ctx := context.Background()
+	source := createWindowsLifecycleInstance(t, ctx, manager, image, "windows-stopped-fork-source", false)
+	sourceMachineID := windowsMachineID(t, ctx, manager, source.Id)
+	sourceTPMEK := windowsTPMEK(t, ctx, manager, source.Id)
+	windowsPowerShell(t, ctx, manager, source.Id, `New-Item -ItemType Directory -Force C:\ProgramData\Hypeman | Out-Null; Set-Content C:\ProgramData\Hypeman\identity.txt source`)
+
+	stopped, err := manager.StopInstance(ctx, source.Id)
+	require.NoError(t, err)
+	require.Equal(t, StateStopped, stopped.State)
+	forked, err := manager.ForkInstance(ctx, source.Id, ForkInstanceRequest{
+		Name:        "windows-stopped-child",
+		TargetState: StateRunning,
+	})
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = deleteTestInstanceNow(context.Background(), manager, forked.Id) })
+	assert.NotEqual(t, sourceMachineID, windowsMachineID(t, ctx, manager, forked.Id), "fork must receive a new Windows machine identity")
+	assert.NotEqual(t, sourceTPMEK, windowsTPMEK(t, ctx, manager, forked.Id), "cold forks must initialize a fresh TPM")
+	assert.NotEqual(t, source.VsockCID, forked.VsockCID, "forks need unique vsock CIDs")
+	assertIndependentFile(t, p.InstanceOVMFVars(source.Id), p.InstanceOVMFVars(forked.Id))
+	assertIndependentFile(t, p.InstanceWindowsDisk(source.Id), p.InstanceWindowsDisk(forked.Id))
+	require.DirExists(t, p.InstanceTPMDir(forked.Id))
+
+	sourceDiskBefore, err := os.Stat(p.InstanceWindowsDisk(source.Id))
+	require.NoError(t, err)
+	windowsPowerShell(t, ctx, manager, forked.Id, `Set-Content C:\ProgramData\Hypeman\identity.txt child`)
+	assert.Equal(t, "child", windowsPowerShell(t, ctx, manager, forked.Id, `Get-Content C:\ProgramData\Hypeman\identity.txt`))
+	sourceDiskAfter, err := os.Stat(p.InstanceWindowsDisk(source.Id))
+	require.NoError(t, err)
+	assert.Equal(t, sourceDiskBefore.ModTime(), sourceDiskAfter.ModTime(), "child writes must not modify the stopped source disk")
+}
+
+func setupWindowsLifecycleIntegration(t *testing.T) (*manager, *paths.Paths, *images.Image) {
+	t.Helper()
 	if os.Getenv("HYPEMAN_RUN_WINDOWS_LIFECYCLE_INTEGRATION") != "1" {
-		t.Skip("run by the dedicated Windows networking CI gate")
+		t.Skip("run by the dedicated Windows lifecycle CI gates")
 	}
 	fixture := os.Getenv("HYPEMAN_WINDOWS_TEST_AGENT_IMAGE")
 	if fixture == "" {
 		fixture = "/ci/windows/image-agent.qcow2"
 	}
 	if _, err := os.Stat(fixture); err != nil {
 		if os.Getenv("CI") == "true" {
-			t.Fatalf("required Windows networking fixture is missing: %s", fixture)
+			t.Fatalf("required Windows lifecycle fixture is missing: %s", fixture)
 		}
-		t.Skipf("Windows networking fixture is unavailable: %s", fixture)
+		t.Skipf("Windows lifecycle fixture is unavailable: %s", fixture)
 	}
 	acquireHeavyIO(t)
 
 	manager, dataDir := setupTestManagerForQEMU(t)
 	p := paths.New(dataDir)
-	const digestHex = "abababababababababababababababababababababababababababababababab"
+	const digestHex = "acacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacac"
 	image := &images.Image{
-		Name:     "registry.example/windows/image:networking-integration",
+		Name:     "registry.example/windows/image:lifecycle-integration",
 		Digest:   "sha256:" + digestHex,
 		Platform: "windows/amd64",
 		Status:   images.StatusReady,
@@ -52,6 +123,7 @@ func TestWindowsLifecycleIntegration(t *testing.T) {
 			Base:        "registry.example/windows/base@sha256:cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
 			TPM:         "2.0",
 			SecureBoot:  "required",
+			BitLocker:   "disabled",
 			VirtualSize: 80 << 30,
 		},
 	}
@@ -60,28 +132,32 @@ func TestWindowsLifecycleIntegration(t *testing.T) {
 	require.NoError(t, err)
 	require.NoError(t, forkvm.CopyRegularFile(fixture, imagePath))
 	require.NoError(t, os.Chmod(imagePath, 0444))
+	return manager, p, image
+}
 
-	ctx := context.Background()
+func createWindowsLifecycleInstance(t *testing.T, ctx context.Context, manager *manager, image *images.Image, name string, networkEnabled bool) *Instance {
+	t.Helper()
 	instance, err := manager.CreateInstance(ctx, CreateInstanceRequest{
-		Name:           "windows-networking-integration",
+		Name:           name,
 		Image:          image.Name,
 		Platform:       "windows/amd64",
-		Size:           8 << 30,
+		Size:           4 << 30,
 		Vcpus:          4,
-		NetworkEnabled: true,
+		NetworkEnabled: networkEnabled,
 		Hypervisor:     hypervisor.TypeQEMU,
 	})
 	require.NoError(t, err)
 	t.Cleanup(func() { _ = deleteTestInstanceNow(context.Background(), manager, instance.Id) })
-	require.NotEmpty(t, instance.IP)
-	require.NotEmpty(t, instance.MAC)
+	waitForWindowsRunning(t, ctx, manager, instance.Id)
+	return instance
+}
+
+func waitForWindowsRunning(t *testing.T, ctx context.Context, manager *manager, instanceID string) {
+	t.Helper()
 	require.Eventually(t, func() bool {
-		current, err := manager.GetInstance(ctx, instance.Id)
+		current, err := manager.GetInstance(ctx, instanceID)
 		return err == nil && current.State == StateRunning
-	}, 4*time.Minute, time.Second)
-
-	assertWindowsGuestControl(t, ctx, manager, instance.Id)
-	assertWindowsNetworkReady(t, ctx, manager, instance.Id, instance.IP)
+	}, 75*time.Second, 500*time.Millisecond)
 }
 
 func assertWindowsGuestControl(t *testing.T, ctx context.Context, manager *manager, instanceID string) {
@@ -100,7 +176,7 @@ func assertWindowsGuestControl(t *testing.T, ctx context.Context, manager *manag
 	require.NoError(t, err, stderr.String())
 	assert.Less(t, time.Since(jobStart), 10*time.Second)
 
-	time.Sleep(5 * time.Second)
+	time.Sleep(time.Second)
 	stdout.Reset()
 	stderr.Reset()
 	exit, err = guest.ExecIntoInstance(ctx, dialer, guest.ExecOptions{
@@ -201,3 +277,41 @@ func assertWindowsNetworkReady(t *testing.T, ctx context.Context, manager *manag
 	ping := exec.Command("ping", "-c", "3", "-W", "2", expectedIP)
 	require.NoError(t, ping.Run(), "allocated Windows IP did not answer ICMP")
 }
+
+func windowsMachineID(t *testing.T, ctx context.Context, manager *manager, instanceID string) string {
+	t.Helper()
+	return windowsPowerShell(t, ctx, manager, instanceID, `(Get-ItemProperty 'HKLM:\SOFTWARE\Microsoft\Cryptography').MachineGuid`)
+}
+
+func windowsTPMEK(t *testing.T, ctx context.Context, manager *manager, instanceID string) string {
+	t.Helper()
+	hash := windowsPowerShell(t, ctx, manager, instanceID, `(Get-TpmEndorsementKeyInfo -HashAlgorithm Sha256).PublicKeyHash`)
+	require.NotEmpty(t, hash, "TPM endorsement key hash")
+	return hash
+}
+
+func windowsPowerShell(t *testing.T, ctx context.Context, manager *manager, instanceID, command string) string {
+	t.Helper()
+	dialer, err := manager.GetVsockDialer(ctx, instanceID)
+	require.NoError(t, err)
+	var stdout, stderr bytes.Buffer
+	exit, err := guest.ExecIntoInstance(ctx, dialer, guest.ExecOptions{
+		Command:      []string{"powershell.exe", "-NoProfile", "-NonInteractive", "-Command", command},
+		Stdout:       &stdout,
+		Stderr:       &stderr,
+		WaitForAgent: 30 * time.Second,
+		Timeout:      30,
+	})
+	require.NoError(t, err, stderr.String())
+	require.Equal(t, 0, exit.Code, stderr.String())
+	return string(bytes.TrimSpace(stdout.Bytes()))
+}
+
+func assertIndependentFile(t *testing.T, source, fork string) {
+	t.Helper()
+	sourceInfo, err := os.Stat(source)
+	require.NoError(t, err)
+	forkInfo, err := os.Stat(fork)
+	require.NoError(t, err)
+	assert.False(t, os.SameFile(sourceInfo, forkInfo), "%s and %s must not share an inode", source, fork)
+}