Documentation
¶
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 ¶
- type CIMsManager
- type ConfigOption
- type Guest
- func (gm *Guest) AddCWCOWCombinedLayers(ctx context.Context, settings guestresource.CWCOWCombinedLayers) error
- func (gm *Guest) AddLCOWCombinedLayers(ctx context.Context, settings guestresource.LCOWCombinedLayers) error
- func (gm *Guest) AddLCOWMappedDirectory(ctx context.Context, settings guestresource.LCOWMappedDirectory) error
- func (gm *Guest) AddLCOWMappedVirtualDisk(ctx context.Context, settings guestresource.LCOWMappedVirtualDisk) error
- func (gm *Guest) AddLCOWNetworkInterface(ctx context.Context, settings *guestresource.LCOWNetworkAdapter) error
- func (gm *Guest) AddMappedDirectory(ctx context.Context, settings *hcsschema.MappedDirectory) error
- func (gm *Guest) AddNetworkInterface(ctx context.Context, adapterID string, requestType guestrequest.RequestType, ...) error
- func (gm *Guest) AddNetworkNamespace(ctx context.Context, settings *hcn.HostComputeNamespace) error
- func (gm *Guest) AddSecurityPolicy(ctx context.Context, settings guestresource.ConfidentialOptions) error
- func (gm *Guest) AddVPCIDevice(ctx context.Context, settings guestresource.LCOWMappedVPCIDevice) error
- func (gm *Guest) AddVPMemDevice(ctx context.Context, settings guestresource.LCOWMappedVPMemDevice) error
- func (gm *Guest) AddWCOWBlockCIMs(ctx context.Context, settings *guestresource.CWCOWBlockCIMMounts) error
- func (gm *Guest) AddWCOWCombinedLayers(ctx context.Context, settings guestresource.WCOWCombinedLayers) error
- func (gm *Guest) AddWCOWMappedVirtualDisk(ctx context.Context, settings guestresource.WCOWMappedVirtualDisk) error
- func (gm *Guest) AddWCOWMappedVirtualDiskForContainerScratch(ctx context.Context, settings guestresource.WCOWMappedVirtualDisk) error
- func (gm *Guest) Capabilities() gcs.GuestDefinedCapabilities
- func (gm *Guest) CloseConnection() error
- func (gm *Guest) CreateConnection(ctx context.Context, GCSServiceID guid.GUID, opts ...ConfigOption) error
- func (gm *Guest) CreateContainer(ctx context.Context, cid string, config interface{}) (*gcs.Container, error)
- func (gm *Guest) CreateProcess(ctx context.Context, settings interface{}) (cow.Process, error)
- func (gm *Guest) DeleteContainerState(ctx context.Context, cid string) error
- func (gm *Guest) DumpStacks(ctx context.Context) (string, error)
- func (gm *Guest) ExecIntoUVM(ctx context.Context, request *cmd.CmdProcessRequest) (int, error)
- func (gm *Guest) InjectPolicyFragment(ctx context.Context, settings guestresource.SecurityPolicyFragment) error
- func (gm *Guest) RemoveCWCOWCombinedLayers(ctx context.Context, settings guestresource.CWCOWCombinedLayers) error
- func (gm *Guest) RemoveLCOWCombinedLayers(ctx context.Context, settings guestresource.LCOWCombinedLayers) error
- func (gm *Guest) RemoveLCOWMappedDirectory(ctx context.Context, settings guestresource.LCOWMappedDirectory) error
- func (gm *Guest) RemoveLCOWMappedVirtualDisk(ctx context.Context, settings guestresource.LCOWMappedVirtualDisk) error
- func (gm *Guest) RemoveLCOWNetworkInterface(ctx context.Context, settings *guestresource.LCOWNetworkAdapter) error
- func (gm *Guest) RemoveNetworkInterface(ctx context.Context, adapterID string, requestType guestrequest.RequestType, ...) error
- func (gm *Guest) RemoveNetworkNamespace(ctx context.Context, settings *hcn.HostComputeNamespace) error
- func (gm *Guest) RemoveSCSIDevice(ctx context.Context, settings guestresource.SCSIDevice) error
- func (gm *Guest) RemoveVPMemDevice(ctx context.Context, settings guestresource.LCOWMappedVPMemDevice) error
- func (gm *Guest) RemoveWCOWBlockCIMs(ctx context.Context, settings *guestresource.CWCOWBlockCIMMounts) error
- func (gm *Guest) RemoveWCOWCombinedLayers(ctx context.Context, settings guestresource.WCOWCombinedLayers) error
- func (gm *Guest) RemoveWCOWMappedVirtualDisk(ctx context.Context, settings guestresource.WCOWMappedVirtualDisk) error
- func (gm *Guest) UpdateHvSocketAddress(ctx context.Context, settings *hcsschema.HvSocketAddress) error
- type HVSocketManager
- type LCOWDirectoryManager
- type LCOWLayersManager
- type LCOWNetworkManager
- type Manager
- type SecurityPolicyManager
- type WCOWDirectoryManager
- type WCOWLayersManager
- type WCOWNetworkManager
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 ¶
func New(ctx context.Context, uvm interface { vmmanager.LifetimeManager vmmanager.VMSocketManager }) *Guest
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 ¶
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 ¶
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 ¶
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 ¶
CreateProcess creates a process in the guest using the provided settings.
func (*Guest) DeleteContainerState ¶
DeleteContainerState removes persisted state for the container identified by cid from the guest.
func (*Guest) DumpStacks ¶
DumpStacks requests a stack dump from the guest and returns it as a string.
func (*Guest) ExecIntoUVM ¶
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.