[shimV2] [VM controller] refactor + adds Update + Device controllers by rawahars · Pull Request #2663 · microsoft/hcsshim

rawahars · 2026-04-06T11:23:24Z

Summary

In this change, we are adding the following changes-

Following the shim V2 standard, we are declaring the interfaces at the place where the APIs are used. Therefore, we are deleting all the interfaces from the existing packages.
We are refactoring the vm controller to bring it to the same standard as rest of the controllers.

Additionally, we are adding-

Update functionality with LCOW and WCOW specific implementation
RuntimeID API to return the HCS compute ID
APIs to obtain device controllers
- SCSI controller which is initialized eagerly on VM create
- VPCI controller which is lazy initialized
- Plan9 controller which is lazy initialized specifically for lcow builds

jterry75 · 2026-04-09T16:52:11Z

+	ID string
+
+	// HCSDocument specifies the HCS schema document used to create the VM.
+	HCSDocument *hcsschema.ComputeSystem


Note to self, I would have imagined the Create call is what makes this. How does the caller have it for create opts?

So we build the document in the service layer and pass it along to the VM controller.
Ref-

hcsshim/cmd/containerd-shim-lcow-v2/service/service_sandbox_internal.go

Line 74 in 799fe74

hcsDocument, sandboxOptions, err := lcow.BuildSandboxConfig(ctx, ShimName, request.BundlePath, shimOpts, &sandboxSpec)

Hmm. Lets chat on this one. I'm not sure

jterry75 · 2026-04-15T03:37:07Z

+// NetworkController returns a new controller for managing network devices on the VM.
+// Since we have a namespace per pod, we create a new controller per call.
+func (c *Controller) NetworkController() *network.Controller {
+	return network.New(c.uvm, c.guest, c.guest)


New? Why not same one each time?

So networking is local to each pod i.e. each pod has exactly one network namespace and associated endpoints in them. Therefore, it seemed more natural to have a new controller for each pod which controlled per-pod settings.

Device controllers such as SCSI or Plan9 are different since they need holistic view of the VM for vm-host side allocation as well as guest side mount paths.

Hmm. Lets chat on this one too

jterry75 · 2026-04-15T03:38:28Z

+
+	// Iterate over the well-known controller GUIDs so the slice index gives us
+	// the correct controller number directly.
+	for ctrlIdx, guid := range guestrequest.ScsiControllerGuids {


I dont get this? Are you saying we force all controllers to have the same guid?

Yes, we can have maximum 4 SCSI controllers and each has a specific GUID.
Reference-

hcsshim/internal/protocol/guestrequest/types.go

Line 46 in 799fe74

// V5 GUIDs for SCSI controllers

I still dont get it. Why cant you just do doc.devices.scsi[guid]; !ok thats an empty guid you can allocate

If we iterated over the map directly, we'd have the GUID but not the controller number. We'd then need to reverse-lookup the index in ScsiControllerGuids for every GUID.

Honestly, this is because we use controller index which is an index into guestrequest.ScsiControllerGuids. We could have used controller GUIDs directly, but then slotting logic would have became complicated.

Following the shim V2 standard, we are declaring the interfaces at the place where the APIs are used. Therefore, we are deleting all the interfaces from the existing packages. Signed-off-by: Harsh Rawat <harshrawat@microsoft.com>

In this commit, we are refactoring the vm controller to bring it to the same standard as rest of the controllers. Additionally, we are adding- - Update functionality - RuntimeID API - APIs to obtain device controllers Signed-off-by: Harsh Rawat <harshrawat@microsoft.com>

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

rawahars · 2026-04-16T05:28:27Z

Rebased the PR to mainline which should eliminate PR checks.
No functional changes to the PR in the last push.

The added changes are for unblocking CI errors.

rawahars requested a review from a team as a code owner April 6, 2026 11:23

rawahars mentioned this pull request Apr 7, 2026

[shimV2] add plan9 device controller #2641

Merged

msscotb assigned jterry75 and helsaawy Apr 7, 2026

rawahars mentioned this pull request Apr 8, 2026

Adds the core V2 shim implementation for LCOW #2667

Open

helsaawy approved these changes Apr 9, 2026

View reviewed changes

jterry75 requested changes Apr 15, 2026

View reviewed changes

rawahars force-pushed the vm_controller_changes branch from 59b1602 to 50bcc09 Compare April 15, 2026 07:08

rawahars added 4 commits April 16, 2026 09:41

review 1

c874986

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

review 2

f660bd8

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

rawahars force-pushed the vm_controller_changes branch 5 times, most recently from c66dd9d to 16ce43e Compare April 16, 2026 04:59

review 3

00c98b1

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

rawahars force-pushed the vm_controller_changes branch from 16ce43e to 00c98b1 Compare April 16, 2026 05:24

Conversation

rawahars commented Apr 6, 2026

Summary

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!

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!

Uh oh!

Uh oh!

Uh oh!

rawahars commented Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants