implement guest manager interfaces for VM operations

Signed-off-by: Harsh Rawat <harshrawat@microsoft.com>

Author: rawahars

internal/vm/README.md

@@ -5,57 +5,83 @@ configuration, host-side management, and guest-side actions distinct so each lay
 
 1. **Builder**: constructs an HCS compute system configuration used to create a VM.
 2. **VM Manager**: manages host-side VM configuration and lifecycle (NICs, SCSI, VPMem, etc.).
-3. **Guest Manager**: intended for guest-side actions (for example, mounting a disk).
+3. **Guest Manager**: guest-side actions executed via the GCS connection (for example, mounting a mapped disk).
 
 **Note that** this layer does not store UVM host or guest side state. That will be part of the orchestration layer above it.
 
 ## Packages and Responsibilities
 
 - `internal/vm`
-  - Shared types used across layers (for example, `GuestOS`, `SCSIDisk`).
+  - Shared types used across layers (currently `GuestOS`).
 - `internal/vm/builder`
-  - Interface definitions for shaping the VM configuration (`Builder` interface).
-  - Concrete implementation of `Builder` for building `hcsschema.ComputeSystem` documents.
-  - Provides a fluent API for configuring all aspects of the VM document.
-  - Presently, this package is tightly coupled with HCS backend. 
+  - Interface definitions for shaping the VM configuration (`BootOptions`, `MemoryOptions`, `ProcessorOptions`, `DeviceOptions`,
+    `NumaOptions`, `StorageQoSOptions`).
+  - Concrete implementation of `UtilityVMBuilder` for building `hcsschema.ComputeSystem` documents (`UtilityVM`).
+  - Provies a fluent API for constructing the `hcsschema.ComputeSystem` document used to create a UVM.
+  - Presently, this package is tightly coupled with the HCS backend.
 - `internal/vm/vmmanager`
   - Interface definitions for UVM lifecycle and host-side management.
-  - Concrete implementation of `UVM` for running and managing a UVM instance.
-  - Presently, this package is tightly coupled with HCS backend and only runs HCS backed UVMs.
-  - Owns lifecycle calls (start/terminate/close) and host-side modifications (NICs, SCSI, VPMem, pipes, VSMB, Plan9).
-  - Allows creation of the UVM using `vmmanager.Create` which takes a `Builder` and produces a running UVM.
+  - Concrete implementation of `UtilityVM` for running and managing a UVM instance created from a builder document.
+  - Owns lifecycle calls (start/terminate/close/pause/resume/save/wait) and host-side modifications:
+    - Network adapters (`NetworkManager`), SCSI disks (`SCSIManager`), VPMem (`VPMemManager`), VSMB (`VSMBManager`), Plan9 (`Plan9Manager`).
+    - Named pipes (`PipeManager`), virtual PCI devices (`PCIManager`), HvSocket services (`VMSocketManager`).
+    - Resource updates such as CPU group/limits and memory (`ResourceManager`).
+  - Presently, this package is tightly coupled with the HCS backend and only runs HCS-backed UVMs.
 - `internal/vm/guestmanager`
-  - Reserved for guest-level actions such as mounting disks or performing in-guest configuration.
-  - Currently empty and intended to grow as guest actions are formalized.
+  - Interface definitions for guest-side operations executed via the GCS connection.
+  - Manages GCS connection lifecycle, including HvSocket setup and initial guest state.
+  - Implements operations for guest resources, split by LCOW/WCOW where needed:
+    - Network interfaces/namespaces, mapped directories, mapped virtual disks, combined layers, block CIMs (WCOW),
+      VPCI/VPMem devices (LCOW), and security policy operations.
+  - Translates guest operations into GCS modify requests.
 
 ## Typical Flow
 
-1. Build the config using the builder interfaces.
+1. Build the config using the builder options.
 2. Create the VM using the VM manager.
-3. Use manager interfaces for lifecycle and host-side changes.
-4. Use guest manager interfaces for in-guest actions (when available).
+3. Use manager methods for lifecycle and host-side changes.
+4. Establish a GCS connection and use guest manager interfaces for in-guest actions.
 
 ## Example (High Level)
 
 ```
-builder, _ := builder.New("owner", vm.Linux)
+b, _ := builder.New("owner", vm.Linux)
+
+// Parse into the correct builder option.
+memoryOpts := builder.MemoryOptions(b)
+processorOpts := builder.ProcessorOptions(b)
 
 // Configure the VM document.
-builder.Memory().SetMemoryLimit(1024)
-builder.Processor().SetProcessorConfig(&vm.ProcessorConfig{Count: 2})
+memoryOpts.SetMemoryLimit(1024)
+processorOpts.SetProcessorLimits(&hcsschema.VirtualMachineProcessor{Count: 2})
 // ... other builder configuration
 
-// Create and start the VM.
-uvm, _ := vmmanager.Create(ctx, "uvm-id", builder)
-_ = uvm.LifetimeManager().Start(ctx)
+// Create the VM.
+uvm, _ := vmmanager.Create(ctx, "uvm-id", b)
+_ = uvm.Start(ctx)
+
+// Create the Guest Connection.
+g, _ := guestmanager.New(ctx, uvm)
+
+// Start the UVM.
+lifetime := vmmanager.LifetimeManager(uvm)
+_ = lifetime.Start(ctx)
+
+// Create the connection.
+guest := guestmanager.Manager(g)
+_ = guest.CreateConnection(ctx)
 
 // Apply host-side updates.
-_ = uvm.NetworkManager().AddNIC(ctx, nicID, endpointID, macAddr)
+network := vmmanager.NetworkManager(uvm)
+_ = network.AddNIC(ctx, nicID, &hcsschema.NetworkAdapter{})
+
+// Apply guest-side updates.
+guestNetwork := guestmanager.LCOWNetworkManager(g)
+_ = guestNetwork.AddLCOWNetworkInterface(ctx, &guestresource.LCOWNetworkAdapter{})
 ```
 
 ## Layer Boundaries (Quick Reference)
 
 - **Builder**: static, pre-create configuration only. No host mutations.
 - **VM Manager**: host-side changes and lifecycle operations on an existing UVM.
-- **Guest Manager**: guest-side actions, scoped to work that requires in-guest context.
-
+- **Guest Manager**: guest-side actions, scoped to work that requires in-guest context (GCS-backed).

internal/vm/guestmanager/block_cims.go

@@ -0,0 +1,59 @@
+//go:build windows
+
+package guestmanager
+
+import (
+	"context"
+
+	hcsschema "github.com/Microsoft/hcsshim/internal/hcs/schema2"
+	"github.com/Microsoft/hcsshim/internal/protocol/guestrequest"
+	"github.com/Microsoft/hcsshim/internal/protocol/guestresource"
+
+	"github.com/pkg/errors"
+)
+
+// CIMsManager exposes guest WCOW block CIM operations.
+type CIMsManager interface {
+	// AddWCOWBlockCIMs adds WCOW block CIM mounts in the guest.
+	AddWCOWBlockCIMs(ctx context.Context, settings *guestresource.CWCOWBlockCIMMounts) error
+	// RemoveWCOWBlockCIMs removes WCOW block CIM mounts from the guest.
+	RemoveWCOWBlockCIMs(ctx context.Context, settings *guestresource.CWCOWBlockCIMMounts) error
+}
+
+var _ CIMsManager = (*Guest)(nil)
+
+// AddWCOWBlockCIMs adds WCOW block CIM mounts in the guest.
+func (gm *Guest) AddWCOWBlockCIMs(ctx context.Context, settings *guestresource.CWCOWBlockCIMMounts) error {
+	request := &hcsschema.ModifySettingRequest{
+		GuestRequest: guestrequest.ModificationRequest{
+			ResourceType: guestresource.ResourceTypeWCOWBlockCims,
+			RequestType:  guestrequest.RequestTypeAdd,
+			Settings:     settings,
+		},
+	}
+
+	err := gm.modify(ctx, request.GuestRequest)
+	if err != nil {
+		return errors.Wrap(err, "failed to add WCOW block CIMs")
+	}
+
+	return nil
+}
+
+// RemoveWCOWBlockCIMs removes WCOW block CIM mounts in the guest.
+func (gm *Guest) RemoveWCOWBlockCIMs(ctx context.Context, settings *guestresource.CWCOWBlockCIMMounts) error {
+	request := &hcsschema.ModifySettingRequest{
+		GuestRequest: guestrequest.ModificationRequest{
+			ResourceType: guestresource.ResourceTypeWCOWBlockCims,
+			RequestType:  guestrequest.RequestTypeRemove,
+			Settings:     settings,
+		},
+	}
+
+	err := gm.modify(ctx, request.GuestRequest)
+	if err != nil {
+		return errors.Wrap(err, "failed to remove WCOW block CIMs")
+	}
+
+	return nil
+}

internal/vm/guestmanager/combinedlayers_lcow.go

@@ -0,0 +1,56 @@
+//go:build windows
+
+package guestmanager
+
+import (
+	"context"
+
+	hcsschema "github.com/Microsoft/hcsshim/internal/hcs/schema2"
+	"github.com/Microsoft/hcsshim/internal/protocol/guestrequest"
+	"github.com/Microsoft/hcsshim/internal/protocol/guestresource"
+	"github.com/pkg/errors"
+)
+
+// LCOWLayersManager exposes combined layer operations in the LCOW guest.
+type LCOWLayersManager interface {
+	// AddLCOWCombinedLayers adds combined layers to the LCOW guest.
+	AddLCOWCombinedLayers(ctx context.Context, settings guestresource.LCOWCombinedLayers) error
+	// RemoveLCOWCombinedLayers removes combined layers from the LCOW guest.
+	RemoveLCOWCombinedLayers(ctx context.Context, settings guestresource.LCOWCombinedLayers) error
+}
+
+var _ LCOWLayersManager = (*Guest)(nil)
+
+// AddLCOWCombinedLayers adds LCOW combined layers in the guest.
+func (gm *Guest) AddLCOWCombinedLayers(ctx context.Context, settings guestresource.LCOWCombinedLayers) error {
+	modifyRequest := &hcsschema.ModifySettingRequest{
+		GuestRequest: guestrequest.ModificationRequest{
+			ResourceType: guestresource.ResourceTypeCombinedLayers,
+			RequestType:  guestrequest.RequestTypeAdd,
+			Settings:     settings,
+		},
+	}
+
+	err := gm.modify(ctx, modifyRequest.GuestRequest)
+	if err != nil {
+		return errors.Wrap(err, "failed to add LCOW combined layers")
+	}
+	return nil
+}
+
+// RemoveLCOWCombinedLayers removes LCOW combined layers in the guest.
+func (gm *Guest) RemoveLCOWCombinedLayers(ctx context.Context, settings guestresource.LCOWCombinedLayers) error {
+	modifyRequest := &hcsschema.ModifySettingRequest{
+		GuestRequest: guestrequest.ModificationRequest{
+			ResourceType: guestresource.ResourceTypeCombinedLayers,
+			RequestType:  guestrequest.RequestTypeRemove,
+			Settings:     settings,
+		},
+	}
+
+	err := gm.modify(ctx, modifyRequest.GuestRequest)
+	if err != nil {
+		return errors.Wrap(err, "failed to remove LCOW combined layers")
+	}
+	return nil
+}

internal/vm/guestmanager/combinedlayers_wcow.go

@@ -0,0 +1,95 @@
+//go:build windows
+
+package guestmanager
+
+import (
+	"context"
+
+	hcsschema "github.com/Microsoft/hcsshim/internal/hcs/schema2"
+	"github.com/Microsoft/hcsshim/internal/protocol/guestrequest"
+	"github.com/Microsoft/hcsshim/internal/protocol/guestresource"
+
+	"github.com/pkg/errors"
+)
+
+// WCOWLayersManager exposes combined layer operations in the WCOW guest.
+type WCOWLayersManager interface {
+	// AddWCOWCombinedLayers adds combined layers to the WCOW guest.
+	AddWCOWCombinedLayers(ctx context.Context, settings guestresource.WCOWCombinedLayers) error
+	// AddCWCOWCombinedLayers adds combined layers to the CWCOW guest.
+	AddCWCOWCombinedLayers(ctx context.Context, settings guestresource.CWCOWCombinedLayers) error
+	// RemoveWCOWCombinedLayers removes combined layers from the WCOW guest.
+	RemoveWCOWCombinedLayers(ctx context.Context, settings guestresource.WCOWCombinedLayers) error
+	// RemoveCWCOWCombinedLayers removes combined layers from the CWCOW guest.
+	RemoveCWCOWCombinedLayers(ctx context.Context, settings guestresource.CWCOWCombinedLayers) error
+}
+
+var _ WCOWLayersManager = (*Guest)(nil)
+
+// AddWCOWCombinedLayers adds WCOW combined layers in the guest.
+func (gm *Guest) AddWCOWCombinedLayers(ctx context.Context, settings guestresource.WCOWCombinedLayers) error {
+	modifyRequest := &hcsschema.ModifySettingRequest{
+		GuestRequest: guestrequest.ModificationRequest{
+			ResourceType: guestresource.ResourceTypeCombinedLayers,
+			RequestType:  guestrequest.RequestTypeAdd,
+			Settings:     settings,
+		},
+	}
+
+	err := gm.modify(ctx, modifyRequest.GuestRequest)
+	if err != nil {
+		return errors.Wrap(err, "failed to add WCOW combined layers")
+	}
+	return nil
+}
+
+// AddCWCOWCombinedLayers adds combined layers in CWCOW guest.
+func (gm *Guest) AddCWCOWCombinedLayers(ctx context.Context, settings guestresource.CWCOWCombinedLayers) error {
+	modifyRequest := &hcsschema.ModifySettingRequest{
+		GuestRequest: guestrequest.ModificationRequest{
+			ResourceType: guestresource.ResourceTypeCWCOWCombinedLayers,
+			RequestType:  guestrequest.RequestTypeAdd,
+			Settings:     settings,
+		},
+	}
+
+	err := gm.modify(ctx, modifyRequest.GuestRequest)
+	if err != nil {
+		return errors.Wrap(err, "failed to add CWCOW combined layers")
+	}
+	return nil
+}
+
+// RemoveWCOWCombinedLayers removes WCOW combined layers in the guest.
+func (gm *Guest) RemoveWCOWCombinedLayers(ctx context.Context, settings guestresource.WCOWCombinedLayers) error {
+	modifyRequest := &hcsschema.ModifySettingRequest{
+		GuestRequest: guestrequest.ModificationRequest{
+			ResourceType: guestresource.ResourceTypeCombinedLayers,
+			RequestType:  guestrequest.RequestTypeRemove,
+			Settings:     settings,
+		},
+	}
+
+	err := gm.modify(ctx, modifyRequest.GuestRequest)
+	if err != nil {
+		return errors.Wrap(err, "failed to remove WCOW combined layers")
+	}
+	return nil
+}
+
+// RemoveCWCOWCombinedLayers removes combined layers in CWCOW guest.
+func (gm *Guest) RemoveCWCOWCombinedLayers(ctx context.Context, settings guestresource.CWCOWCombinedLayers) error {
+	modifyRequest := &hcsschema.ModifySettingRequest{
+		GuestRequest: guestrequest.ModificationRequest{
+			ResourceType: guestresource.ResourceTypeCWCOWCombinedLayers,
+			RequestType:  guestrequest.RequestTypeRemove,
+			Settings:     settings,
+		},
+	}
+
+	err := gm.modify(ctx, modifyRequest.GuestRequest)
+	if err != nil {
+		return errors.Wrap(err, "failed to remove CWCOW combined layers")
+	}
+	return nil
+}

internal/vm/guestmanager/device_lcow.go

@@ -0,0 +1,75 @@
+//go:build windows
+
+package guestmanager
+
+import (
+	"context"
+
+	hcsschema "github.com/Microsoft/hcsshim/internal/hcs/schema2"
+	"github.com/Microsoft/hcsshim/internal/protocol/guestrequest"
+	"github.com/Microsoft/hcsshim/internal/protocol/guestresource"
+	"github.com/pkg/errors"
+)
+
+// LCOWDeviceManager exposes guest device operations.
+type LCOWDeviceManager interface {
+	// AddVPCIDevice adds a VPCI device to the guest.
+	AddVPCIDevice(ctx context.Context, settings guestresource.LCOWMappedVPCIDevice) error
+	// AddVPMemDevice adds a VPMem device to the guest.
+	AddVPMemDevice(ctx context.Context, settings guestresource.LCOWMappedVPMemDevice) error
+	// RemoveVPMemDevice removes a VPMem device from the guest.
+	RemoveVPMemDevice(ctx context.Context, settings guestresource.LCOWMappedVPMemDevice) error
+}
+
+var _ LCOWDeviceManager = (*Guest)(nil)
+
+// AddVPCIDevice adds a VPCI device in the guest.
+func (gm *Guest) AddVPCIDevice(ctx context.Context, settings guestresource.LCOWMappedVPCIDevice) error {
+	request := &hcsschema.ModifySettingRequest{
+		GuestRequest: guestrequest.ModificationRequest{
+			ResourceType: guestresource.ResourceTypeVPCIDevice,
+			RequestType:  guestrequest.RequestTypeAdd,
+			Settings:     settings,
+		},
+	}
+
+	err := gm.modify(ctx, request.GuestRequest)
+	if err != nil {
+		return errors.Wrap(err, "failed to add VPCI device")
+	}
+	return nil
+}
+
+// AddVPMemDevice adds a VPMem device in the guest.
+func (gm *Guest) AddVPMemDevice(ctx context.Context, settings guestresource.LCOWMappedVPMemDevice) error {
+	request := &hcsschema.ModifySettingRequest{
+		GuestRequest: guestrequest.ModificationRequest{
+			ResourceType: guestresource.ResourceTypeVPMemDevice,
+			RequestType:  guestrequest.RequestTypeAdd,
+			Settings:     settings,
+		},
+	}
+
+	err := gm.modify(ctx, request.GuestRequest)
+	if err != nil {
+		return errors.Wrap(err, "failed to add VPMem device")
+	}
+	return nil
+}
+
+// RemoveVPMemDevice removes a VPMem device in the guest.
+func (gm *Guest) RemoveVPMemDevice(ctx context.Context, settings guestresource.LCOWMappedVPMemDevice) error {
+	request := &hcsschema.ModifySettingRequest{
+		GuestRequest: guestrequest.ModificationRequest{
+			ResourceType: guestresource.ResourceTypeVPMemDevice,
+			RequestType:  guestrequest.RequestTypeRemove,
+			Settings:     settings,
+		},
+	}
+
+	err := gm.modify(ctx, request.GuestRequest)
+	if err != nil {
+		return errors.Wrap(err, "failed to remove VPMem device")
+	}
+	return nil
+}