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`
+  - Interface definitions and shared types.
+  - `UVM` interface exposes APIs for lifecycle, resources, and device management of running VM.
+  - `Builder` exposes APIs for shaping the configuration used to create a VM.
+  - `GuestOps` defines guest-side operations executed via the GCS connection.
+- `internal/vm/builder`
+  - 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`
+  - 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`
+  - Guest-side actions executed via the GCS connection.
+  - Implements `vm.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/guest.go

@@ -0,0 +1,107 @@
+package vm
+
+import (
+	"context"
+
+	"github.com/Microsoft/hcsshim/internal/cow"
+	"github.com/Microsoft/hcsshim/internal/gcs"
+	hcsschema "github.com/Microsoft/hcsshim/internal/hcs/schema2"
+	"github.com/Microsoft/hcsshim/internal/protocol/guestrequest"
+	"github.com/Microsoft/hcsshim/internal/protocol/guestresource"
+)
+
+// ConfigOption defines a function that modifies the GCS connection config.
+type ConfigOption func(*gcs.GuestConnectionConfig) error
+
+// GuestOps is an interface to interact with
+type GuestOps interface {
+	// CreateConnection creates a connection to the guest.
+	CreateConnection(ctx context.Context, opts ...ConfigOption) error
+	// CloseConnection closes the connection to the guest.
+	CloseConnection() error
+	// Manager returns an interface to manage general operations in the guest.
+	Manager() Manager
+	// LayersManager returns an interface to manage combined layers in the guest.
+	LayersManager() LayersManager
+	// GuestNetworkManager returns an interface to manage networking in the guest.
+	GuestNetworkManager() GuestNetworkManager
+	// DirectoryManager returns an interface to manage mapped directories in the guest.
+	DirectoryManager() DirectoryManager
+	// SecurityPolicyManager returns an interface to manage guest security policy operations.
+	SecurityPolicyManager() SecurityPolicyManager
+	// GuestDeviceManager returns an interface to manage device operations in the guest.
+	GuestDeviceManager() GuestDeviceManager
+	// BlockCIMsManager returns an interface to manage WCOW block CIMs in the guest.
+	BlockCIMsManager() BlockCIMsManager
+	// ScsiManager returns an interface to manage SCSI-related operations in the guest.
+	ScsiManager() ScsiManager
+}
+
+type Manager interface {
+	// Capabilities returns the guest's declared capabilities.
+	Capabilities() gcs.GuestDefinedCapabilities
+	// CreateContainer creates a container within guest using ID `cid` and `config`.
+	// Once the container is created, it can be managed using the returned `gcs.Container` interface.
+	// `gcs.Container` uses the underlying guest connection to issue commands to the guest.
+	CreateContainer(ctx context.Context, cid string, config interface{}) (*gcs.Container, error)
+	// CreateProcess creates a process in the guest.
+	// Once the process is created, it can be managed using the returned `cow.Process` interface.
+	// `cow.Process` uses the underlying guest connection to issue commands to the guest.
+	CreateProcess(ctx context.Context, settings interface{}) (cow.Process, error)
+	// DumpStacks requests a stack dump from the guest and returns it as a string.
+	DumpStacks(ctx context.Context) (string, error)
+	// DeleteContainerState removes persisted state for the container identified by `cid` from the guest.
+	DeleteContainerState(ctx context.Context, cid string) error
+}
+
+// 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
+}
+
+// GuestNetworkManager exposes guest network operations.
+type GuestNetworkManager interface {
+	AddNetworkNamespace(ctx context.Context, settings interface{}) error
+	RemoveNetworkNamespace(ctx context.Context, settings interface{}) error
+	AddNetworkInterface(ctx context.Context, adapterID string, requestType guestrequest.RequestType, settings interface{}) error
+	AddNetworkInterfaceLCOW(ctx context.Context, settings *guestresource.LCOWNetworkAdapter) error
+	RemoveNetworkInterface(ctx context.Context, adapterID string, requestType guestrequest.RequestType, settings interface{}) error
+	RemoveNetworkInterfaceLCOW(ctx context.Context, settings *guestresource.LCOWNetworkAdapter) error
+}
+
+// DirectoryManager exposes mapped directory operations in the guest.
+type DirectoryManager interface {
+	AddMappedDirectory(ctx context.Context, settings *hcsschema.MappedDirectory) error
+	AddMappedDirectoryLCOW(ctx context.Context, settings guestresource.LCOWMappedDirectory) error
+	RemoveMappedDirectoryLCOW(ctx context.Context, settings guestresource.LCOWMappedDirectory) error
+}
+
+// SecurityPolicyManager exposes guest security policy operations.
+type SecurityPolicyManager interface {
+	AddSecurityPolicy(ctx context.Context, settings interface{}) error
+	InjectPolicyFragment(ctx context.Context, settings guestresource.SecurityPolicyFragment) error
+}
+
+// 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
+}
+
+// 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
+}
+
+// ScsiManager exposes guest SCSI operations.
+type ScsiManager interface {
+	AddMappedVirtualDisk(ctx context.Context, settings interface{}) error
+	AddMappedVirtualDiskForContainerScratch(ctx context.Context, settings interface{}) error
+	RemoveMappedVirtualDisk(ctx context.Context, settings interface{}) error
+	RemoveSCSIDevice(ctx context.Context, settings guestresource.SCSIDevice) error
+}

internal/vm/guestmanager/block_cims.go

@@ -0,0 +1,54 @@
+//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/Microsoft/hcsshim/internal/vm"
+	"github.com/pkg/errors"
+)
+
+// BlockCIMsManager returns the guest block CIMs manager.
+func (gm *guestManager) BlockCIMsManager() vm.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,87 @@
+//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/Microsoft/hcsshim/internal/vm"
+
+	"github.com/pkg/errors"
+)
+
+// LayersManager returns the guest layers manager.
+func (gm *guestManager) LayersManager() vm.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,71 @@
+//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/Microsoft/hcsshim/internal/vm"
+	"github.com/pkg/errors"
+)
+
+// GuestDeviceManager returns the guest device manager.
+func (gm *guestManager) GuestDeviceManager() vm.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
+}