Adds Builder and VM Manager interfaces + implementation for UVM by rawahars · Pull Request #2597 · microsoft/hcsshim

rawahars · 2026-02-10T11:06:19Z

This pull request introduces a major refactor and formalization of the Utility VM (UVM) builder and management interfaces. It separates the responsibilities for VM configuration, host-side management, and guest-side actions into clear, testable layers. The changes include a new, well-documented builder interface, VM manager interface, concrete builder and VM manager implementations, along with comprehensive unit tests for the builder's functionality.

The most important changes are:

Architectural Refactor and Documentation

Added a detailed README.md to the internal/vm package, clearly explaining the separation of concerns between the Builder, VM Manager, and Guest Manager layers, and documenting the responsibilities and flow for each layer.

Builder Interface and Implementation

Replaced the old UVMBuilder interface with a new, comprehensive Builder interface in internal/vm/builder.go, providing modular access to memory, processor, NUMA, device, boot, and storage QoS configuration managers.
Introduced a concrete implementation of the Builder interface in internal/vm/builder/builder.go for creating and configuring hcsschema.ComputeSystem documents.

VM Manager Interface and Implementation

Created a new comprehensive UVM interface which corresponds to VM manager functionality.
All the VM host side modification are responsibility of this interface.

Testing

Added comprehensive unit tests for builder verification.

These changes establish a foundation for future VM configuration and management features.

internal/vm/vm.go

internal/vm/vmmanager/scsi.go

internal/vm/vmmanager/interface.go

internal/vm/vmmanager/vpmem.go

Refactor UVM responsibilities into clear builder vs vmmanager packages and document the intended 3-layer VM model. Key changes: - Introduce internal/vm/builder for HCS compute system construction. - Introduce internal/vm/vmmanager for host-side lifecycle/resource control. - Move UVM interfaces and shared types into focused locations. - Add internal/vm/README.md describing layer boundaries and usage flow. - Remove legacy internal/vm/hcs files and rename/move implementations. Signed-off-by: Harsh Rawat <harshrawat@microsoft.com>

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

jterry75 · 2026-02-19T17:19:34Z

internal/vm/vmmanager/vmsocket.go

+
+var _ VMSocketManager = (*UtilityVM)(nil)
+
+func (uvm *UtilityVM) VMSocketListen(connID guid.GUID) (net.Listener, error) {


This is in the wrong spot. Should be a higher level package IMO

Yes, that sounds good. We can implement this in VM Controller too since we can extract the VM's ID via this interface.

jterry75 · 2026-02-19T17:21:12Z

internal/vm/vmmanager/scsi.go

+	request := &hcsschema.ModifySettingRequest{
+		RequestType: guestrequest.RequestTypeAdd,
+		Settings: hcsschema.Attachment{
+			Path:                      disk.Path,


Why do we copy the disk? Why cant we just assign it to settings?

I’ve updated this to assign the disk directly. I avoided this before because the old shim only set specific fields, but since we can move that logic to the upper layer, we can pass the whole object.

jterry75 · 2026-02-19T17:23:42Z

internal/vm/vmmanager/uvm.go

+	}
+
+	// Cache the VM ID of the utility VM.
+	properties, err := cs.Properties(ctx)


Do the properties return in any compute system state?

In this specific method, the properties are queried to get the RuntimeID.
For higher layers, we have a method PropertiesV2 under LifetimeManager which can be used to query properties.

jterry75 · 2026-02-19T17:24:32Z

internal/vm/vmmanager/uvm.go

+
+	defer func() {
+		if cs != nil {
+			_ = cs.Terminate(ctx)


We dont start it why do we need terminate? Just delete right?

No at the point when this defer is registered, we would have started the compute system. If there is a failure in Properties call, we move to terminate it.

jterry75 · 2026-02-19T20:47:37Z

internal/vm/vmmanager/pci.go

+	request := &hcsschema.ModifySettingRequest{
+		ResourcePath: fmt.Sprintf(resourcepaths.VirtualPCIResourceFormat, vmbusGUID),
+		RequestType:  guestrequest.RequestTypeAdd,
+		Settings: hcsschema.VirtualPciDevice{


Seems like we should actually have the API for the PCI device, and then this one is actually add function

jterry75 · 2026-02-19T20:54:03Z

internal/vm/builder/scsi.go

+	}
+
+	ctrl.Attachments[lun] = disk
+	uvmb.doc.VirtualMachine.Devices.Scsi[controller] = ctrl


I've forgotten my golang. Can you not do this in place without the copy out / update model?

Yes, nice catch! I have removed it and added a test too.

jterry75 · 2026-02-19T20:55:57Z

internal/vm/builder/processor.go

+
+var _ ProcessorOptions = (*UtilityVM)(nil)
+
+func (uvmb *UtilityVM) SetProcessorLimits(config *hcsschema.VirtualMachineProcessor) {


This one is odd. If you had the VirtualMachineProcessor you would have already set its .Count/.Limit/,Weight and they would be in the builder right? Seems like if we need this overload we would want it to reflect a smaller set of just count/limit/weight overrides

jterry75 · 2026-02-19T20:58:38Z

internal/vm/builder/device.go

+		return errors.Wrapf(errAlreadySet, "device %v already assigned to utility VM", device)
+	}
+
+	vmbusGUID, err := guid.NewV4()


The caller should pass this guid. You will need in in the controller layers for save/restore alignment.

Nice catch! Changed this.

jterry75 · 2026-02-19T20:59:12Z

internal/vm/builder/device.go

+}
+
+func (uvmb *UtilityVM) SetSerialConsole(port uint32, listenerPath string) error {
+	if !strings.HasPrefix(listenerPath, `\\.\pipe\`) {


You should also allow the administrators pipe prefix

The administrators pipe prefix(\\.\pipe\ProtectedPrefix\Administrator\) is already allowed since it starts with \\.\pipe\. I've added a test case to explicitly verify this.

jterry75 · 2026-02-19T21:00:28Z

internal/vm/builder/builder.go

+	case vm.Windows:
+		doc.VirtualMachine.Devices.VirtualSmb = &hcsschema.VirtualSmb{}
+	case vm.Linux:
+		doc.VirtualMachine.Devices.Plan9 = &hcsschema.Plan9{}


We should add this at the time of its use right? We dont want 9pfs if the caller has no shares right?

IIRC these are added pre-emptively so that HCS can perform warm-up logic on its end.

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

rawahars requested a review from a team as a code owner February 10, 2026 11:06

rawahars mentioned this pull request Feb 11, 2026

adds guest manager interfaces + implementation for guest operations #2598

Open

rawahars force-pushed the feat/vm-package branch 2 times, most recently from 207c612 to 00b1f90 Compare February 13, 2026 08:39

jterry75 reviewed Feb 13, 2026

View reviewed changes

internal/vm/vm.go Outdated Show resolved Hide resolved

jterry75 reviewed Feb 13, 2026

View reviewed changes

internal/vm/vmmanager/scsi.go Outdated Show resolved Hide resolved

jterry75 reviewed Feb 13, 2026

View reviewed changes

internal/vm/vmmanager/interface.go Outdated Show resolved Hide resolved

jterry75 reviewed Feb 13, 2026

View reviewed changes

internal/vm/vmmanager/vpmem.go Outdated Show resolved Hide resolved

rawahars added 2 commits February 15, 2026 17:32

Add unit tests for VM builder configuration and device management

7519c12

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

rawahars force-pushed the feat/vm-package branch from 00b1f90 to 7519c12 Compare February 15, 2026 12:03

msscotb assigned jterry75 and helsaawy Feb 18, 2026

jterry75 reviewed Feb 19, 2026

View reviewed changes

review comments

5648877

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


		var _ VMSocketManager = (*UtilityVM)(nil)

		func (uvm *UtilityVM) VMSocketListen(connID guid.GUID) (net.Listener, error) {


		var _ ProcessorOptions = (*UtilityVM)(nil)

		func (uvmb UtilityVM) SetProcessorLimits(config hcsschema.VirtualMachineProcessor) {

Conversation

rawahars commented Feb 10, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments