guestmanager

package
v0.15.0-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 31, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Rendered for windows/amd64

Overview

Package guestmanager manages guest-side operations for utility VMs (UVMs) via the GCS (Guest Compute Service) connection.

It provides a concrete Guest struct, a top-level Manager interface that aggregates connection lifecycle and container/process operations, and a set of granular resource-scoped manager interfaces:

  • Manager – connection lifecycle, container and process creation, stack dumps, and container state deletion.
  • LCOWNetworkManager – add and remove network interfaces in an LCOW guest.
  • WCOWNetworkManager – add and remove network interfaces and namespaces in a WCOW guest.
  • LCOWDirectoryManager – map and unmap directories in an LCOW guest.
  • WCOWDirectoryManager – map directories in a WCOW guest.
  • [LCOWScsiManager] – add and remove mapped virtual disks and SCSI devices in an LCOW guest.
  • [WCOWScsiManager] – add and remove mapped virtual disks and SCSI devices in a WCOW guest.
  • LCOWLayersManager – add and remove combined layers in an LCOW guest.
  • WCOWLayersManager – add and remove combined layers in a WCOW guest.
  • CIMsManager – add and remove WCOW block CIM mounts.
  • [LCOWDeviceManager] – add and remove VPCI and VPMem devices in an LCOW guest.
  • SecurityPolicyManager – add security policies and inject policy fragments.

All interfaces are implemented by Guest.

This package is strictly guest-side. It does not own or modify host-side UVM state; that is the responsibility of the sibling vmmanager package. It also does not store UVM host or guest state — state management belongs to the orchestration layer above.

Creating a Guest

After the UVM has been started via vmmanager, create a Guest and establish the GCS connection:

g, err := guestmanager.New(ctx, uvm)
if err != nil { // handle error }
if err := g.CreateConnection(ctx); err != nil { // handle error }

After the connection is established, use the manager interfaces for guest-side changes:

_ = g.AddLCOWNetworkInterface(ctx, &guestresource.LCOWNetworkAdapter{...})
_ = g.AddLCOWMappedVirtualDisk(ctx, guestresource.LCOWMappedVirtualDisk{...})

Layer Boundaries

This package covers guest-side changes executed over the GCS connection. Host-side VM configuration and lifecycle operations belong in the sibling vmmanager package.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CIMsManager

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
}

CIMsManager exposes guest WCOW block CIM operations.

type ConfigOption

type ConfigOption func(*gcs.GuestConnectionConfig) error

ConfigOption defines a function that modifies the GCS connection config.

func WithInitializationState

func WithInitializationState(state *gcs.InitialGuestState) ConfigOption

WithInitializationState applies initial guest state to the GCS connection config.

type Guest

type Guest struct {
	// contains filtered or unexported fields
}

Guest manages the GCS connection and guest-side operations for a utility VM.

func New

New creates a new Guest Manager.

func (*Guest) AddCWCOWCombinedLayers

func (gm *Guest) AddCWCOWCombinedLayers(ctx context.Context, settings guestresource.CWCOWCombinedLayers) error

AddCWCOWCombinedLayers adds combined layers in the CWCOW guest.

func (*Guest) AddLCOWCombinedLayers

func (gm *Guest) AddLCOWCombinedLayers(ctx context.Context, settings guestresource.LCOWCombinedLayers) error

AddLCOWCombinedLayers adds LCOW combined layers in the guest.

func (*Guest) AddLCOWMappedDirectory

func (gm *Guest) AddLCOWMappedDirectory(ctx context.Context, settings guestresource.LCOWMappedDirectory) error

AddLCOWMappedDirectory maps a directory into LCOW guest.

func (*Guest) AddLCOWMappedVirtualDisk

func (gm *Guest) AddLCOWMappedVirtualDisk(ctx context.Context, settings guestresource.LCOWMappedVirtualDisk) error

AddLCOWMappedVirtualDisk maps a virtual disk into a LCOW guest.

func (*Guest) AddLCOWNetworkInterface

func (gm *Guest) AddLCOWNetworkInterface(ctx context.Context, settings *guestresource.LCOWNetworkAdapter) error

AddLCOWNetworkInterface adds a network interface to the LCOW guest.

func (*Guest) AddMappedDirectory

func (gm *Guest) AddMappedDirectory(ctx context.Context, settings *hcsschema.MappedDirectory) error

AddMappedDirectory maps a directory into the guest.

func (*Guest) AddNetworkInterface

func (gm *Guest) AddNetworkInterface(ctx context.Context, adapterID string, requestType guestrequest.RequestType, settings *hcn.HostComputeEndpoint) error

AddNetworkInterface adds a network interface to the WCOW guest.

func (*Guest) AddNetworkNamespace

func (gm *Guest) AddNetworkNamespace(ctx context.Context, settings *hcn.HostComputeNamespace) error

AddNetworkNamespace adds a network namespace in the guest.

func (*Guest) AddSecurityPolicy

func (gm *Guest) AddSecurityPolicy(ctx context.Context, settings guestresource.ConfidentialOptions) error

AddSecurityPolicy adds a security policy to the guest.

func (*Guest) AddVPCIDevice

func (gm *Guest) AddVPCIDevice(ctx context.Context, settings guestresource.LCOWMappedVPCIDevice) error

AddVPCIDevice adds a VPCI device in the guest.

func (*Guest) AddVPMemDevice

func (gm *Guest) AddVPMemDevice(ctx context.Context, settings guestresource.LCOWMappedVPMemDevice) error

AddVPMemDevice adds a VPMem device in the guest.

func (*Guest) AddWCOWBlockCIMs

func (gm *Guest) AddWCOWBlockCIMs(ctx context.Context, settings *guestresource.CWCOWBlockCIMMounts) error

AddWCOWBlockCIMs adds WCOW block CIM mounts in the guest.

func (*Guest) AddWCOWCombinedLayers

func (gm *Guest) AddWCOWCombinedLayers(ctx context.Context, settings guestresource.WCOWCombinedLayers) error

AddWCOWCombinedLayers adds WCOW combined layers in the guest.

func (*Guest) AddWCOWMappedVirtualDisk

func (gm *Guest) AddWCOWMappedVirtualDisk(ctx context.Context, settings guestresource.WCOWMappedVirtualDisk) error

AddWCOWMappedVirtualDisk maps a virtual disk into a WCOW guest.

func (*Guest) AddWCOWMappedVirtualDiskForContainerScratch

func (gm *Guest) AddWCOWMappedVirtualDiskForContainerScratch(ctx context.Context, settings guestresource.WCOWMappedVirtualDisk) error

AddWCOWMappedVirtualDiskForContainerScratch attaches a scratch disk in the WCOW guest.

func (*Guest) Capabilities

func (gm *Guest) Capabilities() gcs.GuestDefinedCapabilities

Capabilities returns the capabilities of the guest connection.

func (*Guest) CloseConnection

func (gm *Guest) CloseConnection() error

CloseConnection closes any active GCS connection and listener.

func (*Guest) CreateConnection

func (gm *Guest) CreateConnection(ctx context.Context, GCSServiceID guid.GUID, opts ...ConfigOption) error

CreateConnection accepts the GCS connection and performs initial setup.

func (*Guest) CreateContainer

func (gm *Guest) CreateContainer(ctx context.Context, cid string, config interface{}) (*gcs.Container, error)

CreateContainer creates a container in the guest with the given ID and config.

func (*Guest) CreateProcess

func (gm *Guest) CreateProcess(ctx context.Context, settings interface{}) (cow.Process, error)

CreateProcess creates a process in the guest using the provided settings.

func (*Guest) DeleteContainerState

func (gm *Guest) DeleteContainerState(ctx context.Context, cid string) error

DeleteContainerState removes persisted state for the container identified by cid from the guest.

func (*Guest) DumpStacks

func (gm *Guest) DumpStacks(ctx context.Context) (string, error)

DumpStacks requests a stack dump from the guest and returns it as a string.

func (*Guest) ExecIntoUVM

func (gm *Guest) ExecIntoUVM(ctx context.Context, request *cmd.CmdProcessRequest) (int, error)

ExecIntoUVM executes commands specified in the requests in the utility VM.

func (*Guest) InjectPolicyFragment

func (gm *Guest) InjectPolicyFragment(ctx context.Context, settings guestresource.SecurityPolicyFragment) error

InjectPolicyFragment injects a policy fragment into the guest.

func (*Guest) RemoveCWCOWCombinedLayers

func (gm *Guest) RemoveCWCOWCombinedLayers(ctx context.Context, settings guestresource.CWCOWCombinedLayers) error

RemoveCWCOWCombinedLayers removes combined layers in CWCOW guest.

func (*Guest) RemoveLCOWCombinedLayers

func (gm *Guest) RemoveLCOWCombinedLayers(ctx context.Context, settings guestresource.LCOWCombinedLayers) error

RemoveLCOWCombinedLayers removes LCOW combined layers in the guest.

func (*Guest) RemoveLCOWMappedDirectory

func (gm *Guest) RemoveLCOWMappedDirectory(ctx context.Context, settings guestresource.LCOWMappedDirectory) error

RemoveLCOWMappedDirectory unmaps a directory from LCOW guest.

func (*Guest) RemoveLCOWMappedVirtualDisk

func (gm *Guest) RemoveLCOWMappedVirtualDisk(ctx context.Context, settings guestresource.LCOWMappedVirtualDisk) error

RemoveLCOWMappedVirtualDisk unmaps a virtual disk from the LCOW guest.

func (*Guest) RemoveLCOWNetworkInterface

func (gm *Guest) RemoveLCOWNetworkInterface(ctx context.Context, settings *guestresource.LCOWNetworkAdapter) error

RemoveLCOWNetworkInterface removes a network interface from the LCOW guest.

func (*Guest) RemoveNetworkInterface

func (gm *Guest) RemoveNetworkInterface(ctx context.Context, adapterID string, requestType guestrequest.RequestType, settings *hcn.HostComputeEndpoint) error

RemoveNetworkInterface removes a network interface from the WCOW guest.

func (*Guest) RemoveNetworkNamespace

func (gm *Guest) RemoveNetworkNamespace(ctx context.Context, settings *hcn.HostComputeNamespace) error

RemoveNetworkNamespace removes a network namespace in the guest.

func (*Guest) RemoveSCSIDevice

func (gm *Guest) RemoveSCSIDevice(ctx context.Context, settings guestresource.SCSIDevice) error

RemoveSCSIDevice removes a SCSI device in the guest.

func (*Guest) RemoveVPMemDevice

func (gm *Guest) RemoveVPMemDevice(ctx context.Context, settings guestresource.LCOWMappedVPMemDevice) error

RemoveVPMemDevice removes a VPMem device in the guest.

func (*Guest) RemoveWCOWBlockCIMs

func (gm *Guest) RemoveWCOWBlockCIMs(ctx context.Context, settings *guestresource.CWCOWBlockCIMMounts) error

RemoveWCOWBlockCIMs removes WCOW block CIM mounts in the guest.

func (*Guest) RemoveWCOWCombinedLayers

func (gm *Guest) RemoveWCOWCombinedLayers(ctx context.Context, settings guestresource.WCOWCombinedLayers) error

RemoveWCOWCombinedLayers removes WCOW combined layers in the guest.

func (*Guest) RemoveWCOWMappedVirtualDisk

func (gm *Guest) RemoveWCOWMappedVirtualDisk(ctx context.Context, settings guestresource.WCOWMappedVirtualDisk) error

RemoveWCOWMappedVirtualDisk unmaps a virtual disk from the WCOW guest.

func (*Guest) UpdateHvSocketAddress

func (gm *Guest) UpdateHvSocketAddress(ctx context.Context, settings *hcsschema.HvSocketAddress) error

UpdateHvSocketAddress updates the Hyper-V socket address settings for the VM. These address settings are applied by the GCS every time the VM starts or restores.

type HVSocketManager

type HVSocketManager interface {
	UpdateHvSocketAddress(ctx context.Context, settings *hcsschema.HvSocketAddress) error
}

HVSocketManager exposes the hvSocket operations in the Guest.

type LCOWDirectoryManager

type LCOWDirectoryManager interface {
	// AddLCOWMappedDirectory maps a directory into the LCOW guest.
	AddLCOWMappedDirectory(ctx context.Context, settings guestresource.LCOWMappedDirectory) error
	// RemoveLCOWMappedDirectory unmaps a directory from the LCOW guest.
	RemoveLCOWMappedDirectory(ctx context.Context, settings guestresource.LCOWMappedDirectory) error
}

LCOWDirectoryManager exposes mapped directory operations in the LCOW guest.

type LCOWLayersManager

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
}

LCOWLayersManager exposes combined layer operations in the LCOW guest.

type LCOWNetworkManager

type LCOWNetworkManager interface {
	// AddLCOWNetworkInterface adds a network interface to the LCOW guest.
	AddLCOWNetworkInterface(ctx context.Context, settings *guestresource.LCOWNetworkAdapter) error
	// RemoveLCOWNetworkInterface removes a network interface from the LCOW guest.
	RemoveLCOWNetworkInterface(ctx context.Context, settings *guestresource.LCOWNetworkAdapter) error
}

LCOWNetworkManager exposes guest network operations.

type Manager

type Manager interface {
	// CreateConnection accepts the GCS connection and performs initial setup.
	CreateConnection(ctx context.Context, GCSServiceID guid.GUID, opts ...ConfigOption) error
	// CloseConnection closes the GCS connection and listener.
	CloseConnection() error
	// 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
	// ExecIntoUVM executes commands specified in the requests in the utility VM.
	ExecIntoUVM(ctx context.Context, request *cmd.CmdProcessRequest) (int, error)
}

Manager provides access to guest operations over the GCS connection. Call CreateConnection before invoking other methods.

type SecurityPolicyManager

type SecurityPolicyManager interface {
	// AddSecurityPolicy adds a security policy to the guest.
	AddSecurityPolicy(ctx context.Context, settings guestresource.ConfidentialOptions) error
	// InjectPolicyFragment injects a policy fragment into the guest.
	InjectPolicyFragment(ctx context.Context, settings guestresource.SecurityPolicyFragment) error
}

SecurityPolicyManager exposes guest security policy operations.

type WCOWDirectoryManager

type WCOWDirectoryManager interface {
	// AddMappedDirectory maps a directory into the WCOW guest.
	AddMappedDirectory(ctx context.Context, settings *hcsschema.MappedDirectory) error
}

WCOWDirectoryManager exposes mapped directory operations in the WCOW guest.

type WCOWLayersManager

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
}

WCOWLayersManager exposes combined layer operations in the WCOW guest.

type WCOWNetworkManager

type WCOWNetworkManager interface {
	// AddNetworkNamespace adds a network namespace to the WCOW guest.
	AddNetworkNamespace(ctx context.Context, settings *hcn.HostComputeNamespace) error
	// RemoveNetworkNamespace removes a network namespace from the WCOW guest.
	RemoveNetworkNamespace(ctx context.Context, settings *hcn.HostComputeNamespace) error
	// AddNetworkInterface adds a network interface to the WCOW guest.
	AddNetworkInterface(ctx context.Context, adapterID string, requestType guestrequest.RequestType, settings *hcn.HostComputeEndpoint) error
	// RemoveNetworkInterface removes a network interface from the WCOW guest.
	RemoveNetworkInterface(ctx context.Context, adapterID string, requestType guestrequest.RequestType, settings *hcn.HostComputeEndpoint) error
}

WCOWNetworkManager exposes guest network operations.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL