parity: add LCOW HCS document parity tests for v2 builder validation

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

Author: Shreyansh Sancheti

.github/workflows/ci.yml

@@ -318,7 +318,7 @@ jobs:
         run: ${{ env.GOTESTSUM_CMD }} -gcflags=all=-d=checkptr -tags admin -timeout=20m ./...
 
       - name: Run non-functional tests
-        run: ${{ env.GOTESTSUM_CMD }} -mod=mod -gcflags=all=-d=checkptr ./internal/... ./pkg/...
+        run: ${{ env.GOTESTSUM_CMD }} -mod=mod -gcflags=all=-d=checkptr ./internal/... ./pkg/... ./parity/...
         working-directory: test
 
       - name: Build and run containerd-shim-runhcs-v1 tests

internal/uvm/create.go

@@ -160,7 +160,7 @@ func verifyWCOWBootFiles(bootFiles *WCOWBootFiles) error {
 }
 
 // Verifies that the final UVM options are correct and supported.
-func verifyOptions(_ context.Context, options interface{}) error {
+func VerifyOptions(_ context.Context, options interface{}) error {
 	switch opts := options.(type) {
 	case *OptionsLCOW:
 		if opts.EnableDeferredCommit && !opts.AllowOvercommit {

internal/uvm/create_lcow.go

@@ -537,7 +537,7 @@ Example JSON document produced once the hcsschema.ComputeSytem returned by makeL
 */
 
 // Make the ComputeSystem document object that will be serialized to json to be presented to the HCS api.
-func makeLCOWDoc(ctx context.Context, opts *OptionsLCOW, uvm *UtilityVM) (_ *hcsschema.ComputeSystem, err error) {
+func MakeLCOWDoc(ctx context.Context, opts *OptionsLCOW, uvm *UtilityVM) (_ *hcsschema.ComputeSystem, err error) {
 	if logrus.IsLevelEnabled(logrus.TraceLevel) {
 		log.G(ctx).WithField("options", log.Format(ctx, opts)).Trace("makeLCOWDoc")
 	}
@@ -931,7 +931,7 @@ func CreateLCOW(ctx context.Context, opts *OptionsLCOW) (_ *UtilityVM, err error
 		uvm.scsiControllerCount = 4
 	}
 
-	if err = verifyOptions(ctx, opts); err != nil {
+	if err = VerifyOptions(ctx, opts); err != nil {
 		return nil, errors.Wrap(err, errBadUVMOpts.Error())
 	}
 
@@ -946,7 +946,7 @@ func CreateLCOW(ctx context.Context, opts *OptionsLCOW) (_ *UtilityVM, err error
 			}).Trace("create_lcow::CreateLCOW makeLCOWSecurityDoc result")
 		}
 	} else {
-		doc, err = makeLCOWDoc(ctx, opts, uvm)
+		doc, err = MakeLCOWDoc(ctx, opts, uvm)
 		if logrus.IsLevelEnabled(logrus.TraceLevel) {
 			log.G(ctx).WithFields(logrus.Fields{
 				"doc":           log.Format(ctx, doc),

internal/uvm/create_wcow.go

@@ -589,7 +589,7 @@ func CreateWCOW(ctx context.Context, opts *OptionsWCOW) (_ *UtilityVM, err error
 		}
 	}()
 
-	if err := verifyOptions(ctx, opts); err != nil {
+	if err := VerifyOptions(ctx, opts); err != nil {
 		return nil, errors.Wrap(err, errBadUVMOpts.Error())
 	}
 

internal/uvm/types.go

@@ -153,6 +153,22 @@ func (uvm *UtilityVM) ScratchEncryptionEnabled() bool {
 	return uvm.encryptScratch
 }
 
+// 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.
+func NewUtilityVMForDoc(id, owner string, scsiControllerCount, vpmemMaxCount uint32, vpmemMaxSizeBytes uint64, vpmemMultiMapping bool) *UtilityVM {
+	return &UtilityVM{
+		id:                  id,
+		owner:               owner,
+		operatingSystem:     "linux",
+		scsiControllerCount: scsiControllerCount,
+		vpmemMaxCount:       vpmemMaxCount,
+		vpmemMaxSizeBytes:   vpmemMaxSizeBytes,
+		vpciDevices:         make(map[VPCIDeviceID]*VPCIDevice),
+		vpmemMultiMapping:   vpmemMultiMapping,
+	}
+}
+
 type WCOWBootFilesType uint8
 
 const (

test/parity/vm/doc.go

@@ -0,0 +1,7 @@
+//go:build windows
+
+// Package vmparity validates that the v2 modular 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.
+package vmparity

test/parity/vm/hcs_lcow_document_creator_test.go

@@ -0,0 +1,113 @@
+//go:build windows
+
+package vmparity
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/opencontainers/runtime-spec/specs-go"
+
+	runhcsopts "github.com/Microsoft/hcsshim/cmd/containerd-shim-runhcs-v1/options"
+	lcowbuilder "github.com/Microsoft/hcsshim/internal/builder/vm/lcow"
+	hcsschema "github.com/Microsoft/hcsshim/internal/hcs/schema2"
+	"github.com/Microsoft/hcsshim/internal/oci"
+	"github.com/Microsoft/hcsshim/internal/uvm"
+	"github.com/Microsoft/hcsshim/internal/vm/vmutils"
+	"github.com/Microsoft/hcsshim/osversion"
+	vm "github.com/Microsoft/hcsshim/sandbox-spec/vm/v2"
+)
+
+// buildLegacyLCOWDocument creates the HCS document for an LCOW VM using the
+// legacy shim pipeline. It runs the same sequence as createInternal → createPod
+// → CreateLCOW: annotation processing, spec conversion, option verification,
+// and document generation.
+func buildLegacyLCOWDocument(
+	ctx context.Context,
+	spec specs.Spec,
+	shimOpts *runhcsopts.Options,
+	bundle string,
+) (*hcsschema.ComputeSystem, *uvm.OptionsLCOW, error) {
+	// Step 1: Merge shim options into the OCI spec annotations.
+	spec = oci.UpdateSpecFromOptions(spec, shimOpts)
+
+	// Step 2: Expand annotation groups (e.g., security toggles).
+	if err := oci.ProcessAnnotations(ctx, spec.Annotations); err != nil {
+		return nil, nil, fmt.Errorf("failed to expand OCI annotations: %w", err)
+	}
+
+	// Step 3: Convert OCI spec + annotations into OptionsLCOW.
+	rawOpts, err := oci.SpecToUVMCreateOpts(ctx, &spec, "test-parity@vm", "test-owner")
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to convert OCI spec to UVM create options: %w", err)
+	}
+	opts := rawOpts.(*uvm.OptionsLCOW)
+	opts.BundleDirectory = bundle
+
+	// Step 4: Verify options constraints (same as CreateLCOW).
+	if err := uvm.VerifyOptions(ctx, opts); err != nil {
+		return nil, nil, fmt.Errorf("option verification failed: %w", err)
+	}
+
+	// Step 5: Build the temporary UtilityVM with fields that MakeLCOWDoc reads.
+	scsiCount := opts.SCSIControllerCount
+	if osversion.Build() >= osversion.RS5 && opts.VPMemDeviceCount == 0 {
+		scsiCount = 4
+	}
+	tempUVM := uvm.NewUtilityVMForDoc(
+		opts.ID, opts.Owner,
+		scsiCount, opts.VPMemDeviceCount, opts.VPMemSizeBytes,
+		!opts.VPMemNoMultiMapping,
+	)
+
+	// Step 6: Generate the HCS document.
+	doc, err := uvm.MakeLCOWDoc(ctx, opts, tempUVM)
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to generate legacy LCOW HCS document: %w", err)
+	}
+
+	return doc, opts, nil
+}
+
+// buildV2LCOWDocument creates the HCS document and sandbox options from the
+// provided VM spec and runhcs options using the v2 modular builder.
+// The returned document can be used to create a VM directly via HCS.
+func buildV2LCOWDocument(
+	ctx context.Context,
+	shimOpts *runhcsopts.Options,
+	spec *vm.Spec,
+	bundle string,
+) (*hcsschema.ComputeSystem, *lcowbuilder.SandboxOptions, error) {
+	return lcowbuilder.BuildSandboxConfig(ctx, "test-owner", bundle, shimOpts, spec)
+}
+
+// setupBootFiles creates a temporary directory containing the kernel and rootfs
+// files that both document builders probe during boot configuration resolution.
+func setupBootFiles(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	for _, name := range []string{
+		vmutils.KernelFile,
+		vmutils.UncompressedKernelFile,
+		vmutils.InitrdFile,
+		vmutils.VhdFile,
+	} {
+		if err := os.WriteFile(filepath.Join(dir, name), []byte("test"), 0644); err != nil {
+			t.Fatalf("failed to create boot file %s: %v", name, err)
+		}
+	}
+	return dir
+}
+
+// jsonToString serializes v to indented JSON for test log output.
+func jsonToString(v interface{}) string {
+	b, err := json.MarshalIndent(v, "", "  ")
+	if err != nil {
+		panic(err)
+	}
+	return string(b)
+}