parity: add LCOW document permutation tests

Restructure parity test framework and add permutation-based tests for
LCOW HCS document creation comparing legacy and v2 builder outputs.

Signed-off-by: Shreyansh Sancheti <shreyanshjain7174@gmail.com>
Signed-off-by: Shreyansh Sancheti <shsancheti@microsoft.com>

Author: Shreyansh Sancheti

internal/uvm/create_lcow.go

@@ -458,7 +458,7 @@ func makeLCOWVMGSDoc(ctx context.Context, opts *OptionsLCOW, uvm *UtilityVM) (_
 // This is done prior to json seriaisation and sending to the HCS layer to actually do the work of creating the VM.
 // Many details are quite different (see the typical JSON examples), in particular it boots from a VMGS file
 // which contains both the kernel and initrd as well as kernel boot options.
-func makeLCOWSecurityDoc(ctx context.Context, opts *OptionsLCOW, uvm *UtilityVM) (_ *hcsschema.ComputeSystem, err error) {
+func MakeLCOWSecurityDoc(ctx context.Context, opts *OptionsLCOW, uvm *UtilityVM) (_ *hcsschema.ComputeSystem, err error) {
 	doc, vmgsErr := makeLCOWVMGSDoc(ctx, opts, uvm)
 	if vmgsErr != nil {
 		return nil, vmgsErr
@@ -938,7 +938,7 @@ func CreateLCOW(ctx context.Context, opts *OptionsLCOW) (_ *UtilityVM, err error
 	// HCS config for SNP isolated vm is quite different to the usual case
 	var doc *hcsschema.ComputeSystem
 	if opts.SecurityPolicyEnabled {
-		doc, err = makeLCOWSecurityDoc(ctx, opts, uvm)
+		doc, err = MakeLCOWSecurityDoc(ctx, opts, uvm)
 		if logrus.IsLevelEnabled(logrus.TraceLevel) {
 			log.G(ctx).WithFields(logrus.Fields{
 				"doc":           log.Format(ctx, doc),

internal/uvm/types.go

@@ -154,8 +154,8 @@ func (uvm *UtilityVM) ScratchEncryptionEnabled() bool {
 }
 
 // NewUtilityVMForDoc creates a minimal UtilityVM with the fields needed by
-// MakeLCOWDoc for HCS document generation in parity tests.
-// UtilityVM fields are unexported, so this constructor must live in the uvm package.
+// MakeLCOWDoc and MakeLCOWSecurityDoc for HCS document generation. This is
+// not a runnable VM — it exists only for parity testing.
 func NewUtilityVMForDoc(id, owner string, scsiControllerCount, vpmemMaxCount uint32, vpmemMaxSizeBytes uint64, vpmemMultiMapping bool) *UtilityVM {
 	return &UtilityVM{
 		id:                  id,

test/parity/vm/doc.go

@@ -1,7 +1,13 @@
 //go:build windows
 
-// Package vmparity validates that the v2 modular VM document builders produce
-// HCS ComputeSystem documents equivalent to the legacy shim pipelines.
+// Package vm validates that the v2 VM document builders produce HCS
+// ComputeSystem documents equivalent to the legacy shim pipelines.
 //
-// Currently covers LCOW; WCOW parity will be added in a future PR.
+// Currently covers LCOW parity between:
+//   - Legacy: OCI spec → oci.UpdateSpecFromOptions → oci.ProcessAnnotations →
+//     oci.SpecToUVMCreateOpts → uvm.MakeLCOWDoc → *hcsschema.ComputeSystem
+//   - V2: vm.Spec + runhcsopts.Options → lcow.BuildSandboxConfig →
+//     *hcsschema.ComputeSystem + *SandboxOptions
+//
+// WCOW parity will be added in a future PR.
 package vmparity

test/parity/vm/hcs_lcow_document_creator_test.go

@@ -8,8 +8,10 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 
+	"github.com/google/go-cmp/cmp"
 	"github.com/opencontainers/runtime-spec/specs-go"
 
 	runhcsopts "github.com/Microsoft/hcsshim/cmd/containerd-shim-runhcs-v1/options"
@@ -111,3 +113,70 @@ func jsonToString(v interface{}) string {
 	}
 	return string(b)
 }
+
+// normalizeKernelCmdLine trims leading/trailing whitespace from the kernel
+// command line in the document. The legacy builder has a minor quirk that
+// produces a leading space for initrd+KernelDirect boot. The v2 builder
+// does not. Since HCS trims whitespace from kernel args, this difference
+// is harmless and we normalize it away.
+func normalizeKernelCmdLine(doc *hcsschema.ComputeSystem) {
+	if doc == nil || doc.VirtualMachine == nil || doc.VirtualMachine.Chipset == nil {
+		return
+	}
+	if kd := doc.VirtualMachine.Chipset.LinuxKernelDirect; kd != nil {
+		kd.KernelCmdLine = strings.TrimSpace(kd.KernelCmdLine)
+	}
+	if uefi := doc.VirtualMachine.Chipset.Uefi; uefi != nil && uefi.BootThis != nil {
+		uefi.BootThis.OptionalData = strings.TrimSpace(uefi.BootThis.OptionalData)
+	}
+}
+
+// isOnlyKernelCmdLineWhitespaceDiff returns true if the only difference between
+// two documents is leading/trailing whitespace in the kernel command line.
+func isOnlyKernelCmdLineWhitespaceDiff(legacy, v2 *hcsschema.ComputeSystem) bool {
+	legacyCopy := *legacy
+	v2Copy := *v2
+	if legacyCopy.VirtualMachine != nil {
+		vmCopy := *legacyCopy.VirtualMachine
+		legacyCopy.VirtualMachine = &vmCopy
+		if vmCopy.Chipset != nil {
+			chipCopy := *vmCopy.Chipset
+			legacyCopy.VirtualMachine.Chipset = &chipCopy
+			if chipCopy.LinuxKernelDirect != nil {
+				lkdCopy := *chipCopy.LinuxKernelDirect
+				legacyCopy.VirtualMachine.Chipset.LinuxKernelDirect = &lkdCopy
+			}
+			if chipCopy.Uefi != nil {
+				uefiCopy := *chipCopy.Uefi
+				legacyCopy.VirtualMachine.Chipset.Uefi = &uefiCopy
+				if uefiCopy.BootThis != nil {
+					btCopy := *uefiCopy.BootThis
+					legacyCopy.VirtualMachine.Chipset.Uefi.BootThis = &btCopy
+				}
+			}
+		}
+	}
+	if v2Copy.VirtualMachine != nil {
+		vmCopy := *v2Copy.VirtualMachine
+		v2Copy.VirtualMachine = &vmCopy
+		if vmCopy.Chipset != nil {
+			chipCopy := *vmCopy.Chipset
+			v2Copy.VirtualMachine.Chipset = &chipCopy
+			if chipCopy.LinuxKernelDirect != nil {
+				lkdCopy := *chipCopy.LinuxKernelDirect
+				v2Copy.VirtualMachine.Chipset.LinuxKernelDirect = &lkdCopy
+			}
+			if chipCopy.Uefi != nil {
+				uefiCopy := *chipCopy.Uefi
+				v2Copy.VirtualMachine.Chipset.Uefi = &uefiCopy
+				if uefiCopy.BootThis != nil {
+					btCopy := *uefiCopy.BootThis
+					v2Copy.VirtualMachine.Chipset.Uefi.BootThis = &btCopy
+				}
+			}
+		}
+	}
+	normalizeKernelCmdLine(&legacyCopy)
+	normalizeKernelCmdLine(&v2Copy)
+	return cmp.Diff(&legacyCopy, &v2Copy) == ""
+}