adds guest manager interfaces + implementation for guest operations

internal/vm/README.md

@@ -0,0 +1,62 @@
+# VM Package
+
+This directory defines the utility VM (UVM) contracts and separates responsibilities into three layers. The goal is to keep
+configuration, host-side management, and guest-side actions distinct so each layer can evolve independently.
+
+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).
+
+**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`).
+- `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. 
+- `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.
+- `internal/vm/guestmanager`
+  - Interface definitions for guest-side operations executed via the GCS connection.
+  - Guest-side actions executed via the GCS connection.
+  - Implements `GuestOps` which provides APIs for network, storage, devices, security policy, and layers management within guest.
+  - Translates guest operations into GCS modify requests.
+
+## Typical Flow
+
+1. Build the config using the builder interfaces.
+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.
+
+## Example (High Level)
+
+```
+builder, _ := builder.New("owner", vm.Linux)
+
+// Configure the VM document.
+builder.Memory().SetMemoryLimit(1024)
+builder.Processor().SetProcessorConfig(&vm.ProcessorConfig{Count: 2})
+// ... other builder configuration
+
+// Create and start the VM.
+uvm, _ := vmmanager.Create(ctx, "uvm-id", builder)
+_ = uvm.LifetimeManager().Start(ctx)
+
+// Apply host-side updates.
+_ = uvm.NetworkManager().AddNIC(ctx, nicID, endpointID, macAddr)
+```
+
+## 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 (GCS-backed).

internal/vm/guestmanager/block_cims.go

@@ -0,0 +1,61 @@
+//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"
+)
+
+// BlockCIMsManager exposes guest WCOW block CIM operations.
+type BlockCIMsManager interface {
+	AddWCOWBlockCIMs(ctx context.Context, settings *guestresource.CWCOWBlockCIMMounts) error
+	RemoveWCOWBlockCIMs(ctx context.Context, settings *guestresource.CWCOWBlockCIMMounts) error
+}
+
+var _ BlockCIMsManager = (*guestManager)(nil)
+
+// BlockCIMsManager returns the guest block CIMs manager.
+func (gm *guestManager) BlockCIMsManager() BlockCIMsManager {
+	return gm
+}
+
+// AddWCOWBlockCIMs adds WCOW block CIM mounts in the guest.
+func (gm *guestManager) 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 *guestManager) 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.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"
+)
+
+// LayersManager exposes combined layer operations in the guest.
+type LayersManager interface {
+	AddCombinedLayers(ctx context.Context, settings interface{}) error
+	AddCWCOWCombinedLayers(ctx context.Context, settings interface{}) error
+	RemoveCombinedLayers(ctx context.Context, settings interface{}) error
+	RemoveCWCOWCombinedLayers(ctx context.Context, settings interface{}) error
+}
+
+var _ LayersManager = (*guestManager)(nil)
+
+// LayersManager returns the guest layers manager.
+func (gm *guestManager) LayersManager() LayersManager {
+	return gm
+}
+
+// AddCombinedLayers adds combined layers in the guest.
+func (gm *guestManager) AddCombinedLayers(ctx context.Context, settings interface{}) 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, "AddCombinedLayers failed")
+	}
+	return nil
+}
+
+// AddCWCOWCombinedLayers adds combined layers in CWCOW guest.
+func (gm *guestManager) AddCWCOWCombinedLayers(ctx context.Context, settings interface{}) 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, "AddCWCOWCombinedLayers failed")
+	}
+	return nil
+}
+
+// RemoveCombinedLayers removes combined layers in the guest.
+func (gm *guestManager) RemoveCombinedLayers(ctx context.Context, settings interface{}) 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, "RemoveCombinedLayers failed")
+	}
+	return nil
+}
+
+// RemoveCWCOWCombinedLayers removes combined layers in CWCOW guest.
+func (gm *guestManager) RemoveCWCOWCombinedLayers(ctx context.Context, settings interface{}) 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, "RemoveCWCOWCombinedLayers failed")
+	}
+	return nil
+}

internal/vm/guestmanager/device.go

@@ -0,0 +1,79 @@
+//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"
+)
+
+// GuestDeviceManager exposes guest device operations.
+type GuestDeviceManager interface {
+	AddVPCIDevice(ctx context.Context, vmBusGUID string) error
+	AddVPMemDevice(ctx context.Context, settings guestresource.LCOWMappedVPMemDevice) error
+	RemoveVPMemDevice(ctx context.Context, settings guestresource.LCOWMappedVPMemDevice) error
+}
+
+var _ GuestDeviceManager = (*guestManager)(nil)
+
+// GuestDeviceManager returns the guest device manager.
+func (gm *guestManager) GuestDeviceManager() GuestDeviceManager {
+	return gm
+}
+
+// AddVPCIDevice adds a VPCI device in the guest.
+func (gm *guestManager) AddVPCIDevice(ctx context.Context, vmBusGUID string) error {
+	request := &hcsschema.ModifySettingRequest{
+		GuestRequest: guestrequest.ModificationRequest{
+			ResourceType: guestresource.ResourceTypeVPCIDevice,
+			RequestType:  guestrequest.RequestTypeAdd,
+			Settings: guestresource.LCOWMappedVPCIDevice{
+				VMBusGUID: vmBusGUID,
+			},
+		},
+	}
+
+	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 *guestManager) 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 *guestManager) 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
+}