package uvm

import "github.com/Microsoft/hcsshim/internal/uvm"

This package describes the external interface for utility VMs.

Index

Constants 

const (
	// MaxVPMEMCount is the maximum number of VPMem devices that may be added to an LCOW
	// utility VM
	MaxVPMEMCount = 128

	// DefaultVPMEMCount is the default number of VPMem devices that may be added to an LCOW
	// utility VM if the create request doesn't specify how many.
	DefaultVPMEMCount = 64

	// DefaultVPMemSizeBytes is the default size of a VPMem device if the create request
	// doesn't specify.
	DefaultVPMemSizeBytes = 4 * memory.GiB // 4GB
)
const (
	// InitrdFile is the default file name for an initrd.img used to boot LCOW.
	InitrdFile = "initrd.img"
	// VhdFile is the default file name for a rootfs.vhd used to boot LCOW.
	VhdFile = "rootfs.vhd"
	// DefaultDmVerityRootfsVhd is the default file name for a dmverity_rootfs.vhd,
	// which is mounted by the GuestStateFile during boot and used as the root file
	// system when booting in the SNP case. Similar to layer VHDs, the Merkle tree
	// is appended after ext4 filesystem ends.
	DefaultDmVerityRootfsVhd = "rootfs.vhd"
	// KernelFile is the default file name for a kernel used to boot LCOW.
	KernelFile = "kernel"
	// UncompressedKernelFile is the default file name for an uncompressed
	// kernel used to boot LCOW with KernelDirect.
	UncompressedKernelFile = "vmlinux"
	// GuestStateFile is the default file name for a vmgs (VM Guest State) file
	// which contains the kernel and kernel command which mounts DmVerityVhdFile
	// when booting in the SNP case.
	GuestStateFile = "kernel.vmgs"
	// UVMReferenceInfoFile is the default file name for a COSE_Sign1
	// reference UVM info, which can be made available to workload containers
	// and can be used for validation purposes.
	UVMReferenceInfoFile = "reference_info.cose"
)
const (
	GPUDeviceIDType         = "gpu"
	VPCILocationPathIDType  = "vpci-location-path"
	VPCIClassGUIDTypeLegacy = "class"
	VPCIClassGUIDType       = "vpci-class-guid"
	VPCIDeviceIDTypeLegacy  = "vpci"
	VPCIDeviceIDType        = "vpci-instance-id"
)
const (
	PageSize             = 0x1000
	MaxMappedDeviceCount = 1024
)
const ComputeAgentAddrFmt = "\\\\.\\pipe\\computeagent-%s"

Variables 

var (
	// ErrNetNSAlreadyAttached is an error indicating the guest UVM already has
	// an endpoint by this id.
	ErrNetNSAlreadyAttached = errors.New("network namespace already added")
	// ErrNetNSNotFound is an error indicating the guest UVM does not have a
	// network namespace by this id.
	ErrNetNSNotFound = errors.New("network namespace not found")
	// ErrNICNotFound is an error indicating that the guest UVM does not have a NIC
	// by this id.
	ErrNICNotFound = errors.New("NIC not found in network namespace")
)
var (
	// ErrMaxVPMemLayerSize is the error returned when the size of `hostPath` is
	// greater than the max vPMem layer size set at create time.
	ErrMaxVPMemLayerSize   = errors.New("layer size is to large for VPMEM max size")
	ErrNoAvailableLocation = fmt.Errorf("no available location")
	ErrNotAttached         = fmt.Errorf("not attached")
)
var ErrNoNetworkSetup = errors.New("no network setup present for UVM")
var (

	// Maximum number of SCSI controllers allowed
	MaxSCSIControllers = uint32(len(guestrequest.ScsiControllerGuids))
)

Functions

func GetContainerPipeMapping 

func GetContainerPipeMapping(uvm *UtilityVM, mount specs.Mount) (src string, dst string)

GetContainerPipeMapping returns the source and destination to use for a given pipe mount in a container.

func GetNamespaceEndpoints 

func GetNamespaceEndpoints(ctx context.Context, netNS string) ([]*hns.HNSEndpoint, error)

GetNamespaceEndpoints gets all endpoints in `netNS`

func IsPipe 

func IsPipe(hostPath string) bool

IsPipe returns true if the given path references a named pipe.

func IsValidDeviceType 

func IsValidDeviceType(deviceType string) bool

Types

type ConfidentialOptions 

type ConfidentialOptions struct {
	GuestStateFile         string // The vmgs file to load
	UseGuestStateFile      bool   // Use a vmgs file that contains a kernel and initrd, required for SNP
	SecurityPolicy         string // Optional security policy
	SecurityPolicyEnabled  bool   // Set when there is a security policy to apply on actual SNP hardware, use this rathen than checking the string length
	SecurityPolicyEnforcer string // Set which security policy enforcer to use (open door, standard or rego). This allows for better fallback mechanic.
	UVMReferenceInfoFile   string // Filename under `BootFilesPath` for (potentially signed) UVM image reference information.
	BundleDirectory        string // pod bundle directory
	DmVerityRootFsVhd      string // The VHD file (bound to the vmgs file via embedded dmverity hash data file) to load.
	DmVerityMode           bool   // override to be able to turn off dmverity for debugging
	DmVerityCreateArgs     string // set dm-verity args when booting with verity in non-SNP mode
}

type ConfidentialUVMOpt 

type ConfidentialUVMOpt func(ctx context.Context, r *guestresource.LCOWConfidentialOptions) error

func WithSecurityPolicy 

func WithSecurityPolicy(policy string) ConfidentialUVMOpt

WithSecurityPolicy sets the desired security policy for the resource.

func WithSecurityPolicyEnforcer 

func WithSecurityPolicyEnforcer(enforcer string) ConfidentialUVMOpt

WithSecurityPolicyEnforcer sets the desired enforcer type for the resource.

func WithUVMReferenceInfo 

func WithUVMReferenceInfo(referenceRoot string, referenceName string) ConfidentialUVMOpt

WithUVMReferenceInfo reads UVM reference info file and base64 encodes the content before setting it for the resource. This is no-op if the `referenceName` is empty or the file doesn't exist.

type NetworkConfigType 

type NetworkConfigType uint8

NetworkConfigType specifies the action to be performed during network configuration. For example: setup or teardown 

const (
	NetworkRequestSetup NetworkConfigType = iota
	NetworkRequestTearDown
)

type NetworkEndpoints 

type NetworkEndpoints struct {
	EndpointIDs []string
	// ID of the namespace the endpoints belong to
	Namespace string
}

NetworkEndpoints is a struct containing all of the endpoint IDs of a network namespace.

func (*NetworkEndpoints) Release 

func (endpoints *NetworkEndpoints) Release(ctx context.Context) error

Release releases the resources for all of the network endpoints in a namespace.

type NetworkSetup 

type NetworkSetup interface {
	ConfigureNetworking(ctx context.Context, namespaceID string, configType NetworkConfigType) error
}

NetworkSetup is used to abstract away the details of setting up networking for a container.

func NewExternalNetworkSetup 

func NewExternalNetworkSetup(ctx context.Context, vm *UtilityVM, caAddr, containerID string) (NetworkSetup, error)

NewExternalNetworkSetup returns an object implementing the NetworkSetup interface to be used for external network configuration.

func NewInternalNetworkSetup 

func NewInternalNetworkSetup(vm *UtilityVM) NetworkSetup

type Options 

type Options struct {
	ID    string // Identifier for the uvm. Defaults to generated GUID.
	Owner string // Specifies the owner. Defaults to executable name.

	// MemorySizeInMB sets the UVM memory. If `0` will default to platform
	// default.
	MemorySizeInMB uint64

	LowMMIOGapInMB   uint64
	HighMMIOBaseInMB uint64
	HighMMIOGapInMB  uint64

	// Memory for UVM. Defaults to true. For physical backed memory, set to
	// false.
	AllowOvercommit bool

	// FullyPhysicallyBacked describes if a uvm should be entirely physically
	// backed, including in any additional devices
	FullyPhysicallyBacked bool

	// Memory for UVM. Defaults to false. For virtual memory with deferred
	// commit, set to true.
	EnableDeferredCommit bool

	// ProcessorCount sets the number of vCPU's. If `0` will default to platform
	// default.
	ProcessorCount int32

	// ProcessorLimit sets the maximum percentage of each vCPU's the UVM can
	// consume. If `0` will default to platform default.
	ProcessorLimit int32

	// ProcessorWeight sets the relative weight of these vCPU's vs another UVM's
	// when scheduling. If `0` will default to platform default.
	ProcessorWeight int32

	// StorageQoSIopsMaximum sets the maximum number of Iops. If `0` will
	// default to the platform default.
	StorageQoSIopsMaximum int32

	// StorageQoSIopsMaximum sets the maximum number of bytes per second. If `0`
	// will default to the platform default.
	StorageQoSBandwidthMaximum int32

	// DisableCompartmentNamespace sets whether to disable namespacing the network compartment in the UVM
	// for WCOW. Namespacing makes it so the compartment created for a container is essentially no longer
	// aware or able to see any of the other compartments on the host (in this case the UVM).
	// The compartment that the container is added to now behaves as the default compartment as
	// far as the container is concerned and it is only able to view the NICs in the compartment it's assigned to.
	// This is the compartment setup (and behavior) that is followed for V1 HCS schema containers (docker) so
	// this change brings parity as well. This behavior is gated behind a registry key currently to avoid any
	// unnecessary behavior and once this restriction is removed then we can remove the need for this variable
	// and the associated annotation as well.
	DisableCompartmentNamespace bool

	// CPUGroupID set the ID of a CPUGroup on the host that the UVM should be added to on start.
	// Defaults to an empty string which indicates the UVM should not be added to any CPUGroup.
	CPUGroupID string
	// NetworkConfigProxy holds the address of the network config proxy service.
	// This != "" determines whether to start the ComputeAgent TTRPC service
	// that receives the UVMs set of NICs from this proxy instead of enumerating
	// the endpoints locally.
	NetworkConfigProxy string

	// Sets the location for process dumps to be placed in. On Linux this is a kernel setting so it will be
	// applied to all containers. On Windows it's configurable per container, but we can mimic this for
	// Windows by just applying the location specified here per container.
	ProcessDumpLocation string

	// NoWritableFileShares disables adding any writable vSMB and Plan9 shares to the UVM
	NoWritableFileShares bool

	// The number of SCSI controllers. Defaults to 1 for WCOW and 4 for LCOW
	SCSIControllerCount uint32

	// DumpDirectoryPath is the path of the directory inside which all debug dumps etc are stored.
	DumpDirectoryPath string

	// 	AdditionalHyperVConfig are extra Hyper-V socket configurations to provide.
	AdditionalHyperVConfig map[string]hcsschema.HvSocketServiceConfig
}

Options are the set of options passed to Create() to create a utility vm.

type OptionsLCOW 

type OptionsLCOW struct {
	*Options
	*ConfidentialOptions

	// Folder in which kernel and root file system reside. Defaults to \Program Files\Linux Containers.
	//
	// It is preferred to use [UpdateBootFilesPath] to change this value and update associated fields.
	BootFilesPath           string
	KernelFile              string               // Filename under `BootFilesPath` for the kernel. Defaults to `kernel`
	KernelDirect            bool                 // Skip UEFI and boot directly to `kernel`
	RootFSFile              string               // Filename under `BootFilesPath` for the UVMs root file system. Defaults to `InitrdFile`
	KernelBootOptions       string               // Additional boot options for the kernel
	EnableGraphicsConsole   bool                 // If true, enable a graphics console for the utility VM
	ConsolePipe             string               // The named pipe path to use for the serial console.  eg \\.\pipe\vmpipe
	UseGuestConnection      bool                 // Whether the HCS should connect to the UVM's GCS. Defaults to true
	ExecCommandLine         string               // The command line to exec from init. Defaults to GCS
	ForwardStdout           bool                 // Whether stdout will be forwarded from the executed program. Defaults to false
	ForwardStderr           bool                 // Whether stderr will be forwarded from the executed program. Defaults to true
	OutputHandlerCreator    OutputHandlerCreator `json:"-"` // Creates an [OutputHandler] that controls how output received over HVSocket from the UVM is handled. Defaults to parsing output as logrus messages
	VPMemDeviceCount        uint32               // Number of VPMem devices. Defaults to `DefaultVPMEMCount`. Limit at 128. If booting UVM from VHD, device 0 is taken.
	VPMemSizeBytes          uint64               // Size of the VPMem devices. Defaults to `DefaultVPMemSizeBytes`.
	VPMemNoMultiMapping     bool                 // Disables LCOW layer multi mapping
	PreferredRootFSType     PreferredRootFSType  // If `KernelFile` is `InitrdFile` use `PreferredRootFSTypeInitRd`. If `KernelFile` is `VhdFile` use `PreferredRootFSTypeVHD`
	EnableColdDiscardHint   bool                 // Whether the HCS should use cold discard hints. Defaults to false
	VPCIEnabled             bool                 // Whether the kernel should enable pci
	EnableScratchEncryption bool                 // Whether the scratch should be encrypted
	DisableTimeSyncService  bool                 // Disables the time synchronization service
	HclEnabled              *bool                // Whether to enable the host compatibility layer
	ExtraVSockPorts         []uint32             // Extra vsock ports to allow
	AssignedDevices         []VPCIDeviceID       // AssignedDevices are devices to add on pod boot
}

OptionsLCOW are the set of options passed to CreateLCOW() to create a utility vm.

func NewDefaultOptionsLCOW 

func NewDefaultOptionsLCOW(id, owner string) *OptionsLCOW

NewDefaultOptionsLCOW creates the default options for a bootable version of LCOW.

`id` the ID of the compute system. If not passed will generate a new GUID.

`owner` the owner of the compute system. If not passed will use the executable files name.

func (*OptionsLCOW) UpdateBootFilesPath 

func (opts *OptionsLCOW) UpdateBootFilesPath(ctx context.Context, path string)

UpdateBootFilesPath updates the LCOW BootFilesPath field and associated settings. Specifically, if VhdFile is found in path, RootFS is updated, and, if KernelDirect is set, KernelFile is also updated if UncompressedKernelFile is found in path.

This is a nop if the current BootFilesPath is equal to path (case-insensitive).

type OptionsWCOW 

type OptionsWCOW struct {
	*Options

	BootFiles *WCOWBootFiles

	// NoDirectMap specifies that no direct mapping should be used for any VSMBs added to the UVM
	NoDirectMap bool

	// NoInheritHostTimezone specifies whether to not inherit the hosts timezone for the UVM. UTC will be set as the default for the VM instead.
	NoInheritHostTimezone bool

	// AdditionalRegistryKeys are Registry keys and their values to additionally add to the uVM.
	AdditionalRegistryKeys []hcsschema.RegistryValue
}

OptionsWCOW are the set of options passed to CreateWCOW() to create a utility vm.

func NewDefaultOptionsWCOW 

func NewDefaultOptionsWCOW(id, owner string) *OptionsWCOW

NewDefaultOptionsWCOW creates the default options for a bootable version of WCOW. The caller `MUST` set the `BootFiles` on the returned value.

`id` the ID of the compute system. If not passed will generate a new GUID.

`owner` the owner of the compute system. If not passed will use the executable files name.

type OutputHandler 

type OutputHandler func(io.Reader)

OutputHandler is used to process the output from the program run in the UVM.

type OutputHandlerCreator 

type OutputHandlerCreator func(*Options) OutputHandler

type PipeMount 

type PipeMount struct {
	HostPath string
	// contains filtered or unexported fields
}

PipeMount contains the host path for pipe mount

func (*PipeMount) Release 

func (pipe *PipeMount) Release(ctx context.Context) error

Release frees the resources of the corresponding pipe Mount

type Plan9Share 

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

Plan9Share is a struct containing host paths for the UVM

func (*Plan9Share) Release 

func (p9 *Plan9Share) Release(ctx context.Context) error

Release frees the resources of the corresponding Plan9 share

type PreferredRootFSType 

type PreferredRootFSType int
const (
	PreferredRootFSTypeInitRd PreferredRootFSType = iota
	PreferredRootFSTypeVHD
	PreferredRootFSTypeNA
)

type UtilityVM 

type UtilityVM struct {

	// SCSI devices that are mapped into a Windows or Linux utility VM
	SCSIManager *scsi.Manager
	// contains filtered or unexported fields
}

UtilityVM is the object used by clients representing a utility VM

func CreateLCOW 

func CreateLCOW(ctx context.Context, opts *OptionsLCOW) (_ *UtilityVM, err error)

CreateLCOW creates an HCS compute system representing a utility VM. It consumes a set of options derived from various defaults and options expressed as annotations.

func CreateWCOW 

func CreateWCOW(ctx context.Context, opts *OptionsWCOW) (_ *UtilityVM, err error)

CreateWCOW creates an HCS compute system representing a utility VM.

WCOW Notes:

func (*UtilityVM) AddEndpointToNSWithID 

func (uvm *UtilityVM) AddEndpointToNSWithID(ctx context.Context, nsID, nicID string, endpoint *hns.HNSEndpoint) error

AddEndpointToNSWithID adds an endpoint to the network namespace with the specified NIC ID. If nicID is an empty string, a GUID will be generated for the ID instead.

If no network namespace matches `id` returns `ErrNetNSNotFound`.

func (*UtilityVM) AddEndpointsToNS 

func (uvm *UtilityVM) AddEndpointsToNS(ctx context.Context, id string, endpoints []*hns.HNSEndpoint) error

AddEndpointsToNS adds all unique `endpoints` to the network namespace matching `id`. On failure does not roll back any previously successfully added endpoints.

If no network namespace matches `id` returns `ErrNetNSNotFound`.

func (*UtilityVM) AddNICInGuest 

func (uvm *UtilityVM) AddNICInGuest(ctx context.Context, cfg *guestresource.LCOWNetworkAdapter) error

AddNICInGuest makes a request to setup a network adapter's interface inside the lcow guest. This is primarily used for adding NICs in the guest that have been VPCI assigned.

func (*UtilityVM) AddNetNS 

func (uvm *UtilityVM) AddNetNS(ctx context.Context, hcnNamespace *hcn.HostComputeNamespace) error

AddNetNS adds network namespace inside the guest without actually querying for the namespace by its ID. It uses the given namespace struct as it is in the guest request. This function is mostly used when we need to override the values inside the namespace struct returned by the GetNamespaceByID. For most uses cases AddNetNSByID is more appropriate.

If a namespace with the same id already exists this returns `ErrNetNSAlreadyAttached`.

func (*UtilityVM) AddNetNSByID 

func (uvm *UtilityVM) AddNetNSByID(ctx context.Context, id string) error

AddNetNSByID adds finds the namespace with given `id` and adds that network namespace inside the guest.

If a namespace with `id` already exists returns `ErrNetNSAlreadyAttached`.

func (*UtilityVM) AddPipe 

func (uvm *UtilityVM) AddPipe(ctx context.Context, hostPath string) (*PipeMount, error)

AddPipe shares a named pipe into the UVM.

func (*UtilityVM) AddPlan9 

func (uvm *UtilityVM) AddPlan9(ctx context.Context, hostPath string, uvmPath string, readOnly bool, restrict bool, allowedNames []string) (*Plan9Share, error)

AddPlan9 adds a Plan9 share to a utility VM.

func (*UtilityVM) AddVPMem 

func (uvm *UtilityVM) AddVPMem(ctx context.Context, hostPath string) (*VPMEMMount, error)

func (*UtilityVM) AddVSMB 

func (uvm *UtilityVM) AddVSMB(ctx context.Context, hostPath string, options *hcsschema.VirtualSmbShareOptions) (*VSMBShare, error)

AddVSMB adds a VSMB share to a Windows utility VM. Each VSMB share is ref-counted and only added if it isn't already. This is used for read-only layers, mapped directories to a container, and for mapped pipes.

func (*UtilityVM) AddVsmbAndGetSharePath 

func (uvm *UtilityVM) AddVsmbAndGetSharePath(ctx context.Context, reqHostPath, reqUVMPath string, readOnly bool) (*VSMBShare, string, error)

func (*UtilityVM) AssignDevice 

func (uvm *UtilityVM) AssignDevice(ctx context.Context, deviceID string, index uint16, vmBusGUID string) (*VPCIDevice, error)

AssignDevice assigns a vpci device to a uvm. If the device already exists, the stored VPCIDevice's ref count is increased and the VPCIDevice is returned. Otherwise, a new request is made to assign the target device indicated by the deviceID onto the UVM. A new VPCIDevice entry is made on the UVM and the VPCIDevice is returned to the caller. Allow callers to specify the vmbus guid they want the device to show up with.

func (*UtilityVM) Capabilities 

func (uvm *UtilityVM) Capabilities() (uint32, schema1.GuestDefinedCapabilities)

Capabilities returns the protocol version and the guest defined capabilities. This should only be used for testing.

func (*UtilityVM) Close 

func (uvm *UtilityVM) Close() error

Close terminates and releases resources associated with the utility VM.

func (*UtilityVM) CloseCtx 

func (uvm *UtilityVM) CloseCtx(ctx context.Context) (err error)

CloseCtx is similar to UtilityVM.Close, but accepts a context.

The context is used for all operations, including waits, so timeouts/cancellations may prevent proper uVM cleanup.

func (*UtilityVM) CloseGCSConnection 

func (uvm *UtilityVM) CloseGCSConnection() (err error)

Closes the external GCS connection if it is being used and also closes the listener for GCS connection.

func (*UtilityVM) CombineLayersLCOW 

func (uvm *UtilityVM) CombineLayersLCOW(ctx context.Context, containerID string, layerPaths []string, scratchPath, rootfsPath string) error

CombineLayersLCOW combines `layerPaths` and optionally `scratchPath` into an overlay filesystem at `rootfsPath`. If `scratchPath` is empty the overlay will be read only.

NOTE: `layerPaths`, `scrathPath`, and `rootfsPath` are paths from within the UVM.

func (*UtilityVM) CombineLayersWCOW 

func (uvm *UtilityVM) CombineLayersWCOW(ctx context.Context, layerPaths []hcsschema.Layer, containerRootPath string) error

CombineLayersWCOW combines `layerPaths` with `containerRootPath` into the container file system.

Note: `layerPaths` and `containerRootPath` are paths from within the UVM.

func (*UtilityVM) ConfigureNetworking 

func (uvm *UtilityVM) ConfigureNetworking(ctx context.Context, nsid string) error

ConfigureNetworking configures the utility VMs networking setup using the namespace ID `nsid`.

func (*UtilityVM) ContainerCounter 

func (uvm *UtilityVM) ContainerCounter() uint64

ContainerCounter is used for where we layout things for a container in a utility VM. For WCOW it'll be C:\c\N\. For LCOW it'll be /run/gcs/c/N/.

func (*UtilityVM) CreateAndAssignNetworkSetup 

func (uvm *UtilityVM) CreateAndAssignNetworkSetup(ctx context.Context, addr, containerID string) (err error)

CreateAndAssignNetworkSetup creates and assigns a new NetworkSetup interface to the Utility VM. This can be used to configure the networking (setup and teardown) of the vm.

`addr` is an optional parameter

func (*UtilityVM) CreateContainer 

func (uvm *UtilityVM) CreateContainer(ctx context.Context, id string, settings interface{}) (cow.Container, error)

CreateContainer creates a container in the utility VM.

func (*UtilityVM) CreateProcess 

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

CreateProcess creates a process in the utility VM.

func (*UtilityVM) DefaultVSMBOptions 

func (uvm *UtilityVM) DefaultVSMBOptions(readOnly bool) *hcsschema.VirtualSmbShareOptions

DefaultVSMBOptions returns the default VSMB options. If readOnly is specified, returns the default VSMB options for a readonly share.

func (*UtilityVM) DeleteContainerState 

func (uvm *UtilityVM) DeleteContainerState(ctx context.Context, cid string) error

func (*UtilityVM) DeleteContainerStateSupported 

func (uvm *UtilityVM) DeleteContainerStateSupported() bool

func (*UtilityVM) DevicesPhysicallyBacked 

func (uvm *UtilityVM) DevicesPhysicallyBacked() bool

DevicesPhysicallyBacked describes if additional devices added to the UVM should be physically backed.

func (*UtilityVM) DumpStacks 

func (uvm *UtilityVM) DumpStacks(ctx context.Context) (string, error)

func (*UtilityVM) ExitError 

func (uvm *UtilityVM) ExitError() error

ExitError returns an error if the utility VM has terminated unexpectedly.

func (*UtilityVM) GetAssignedDeviceVMBUSInstanceID 

func (uvm *UtilityVM) GetAssignedDeviceVMBUSInstanceID(vmBusChannelGUID string) string

GetAssignedDeviceVMBUSInstanceID returns the instance ID of the VMBUS channel device node created.

When a device is assigned to a UVM via VPCI support in HCS, a new VMBUS channel device node is created in the UVM. The actual device that was assigned in is exposed as a child on this VMBUS channel device node.

A device node's instance ID is an identifier that distinguishes that device from other devices on the system. The GUID of a VMBUS channel device node refers to that channel's unique identifier used internally by VMBUS and can be used to determine the VMBUS channel device node's instance ID.

A VMBUS channel device node's instance ID is in the form: "VMBUS\vmbusChannelTypeGUIDFormatted\{vmBusChannelGUID}"

func (*UtilityVM) GetAssignedMemoryInBytes 

func (uvm *UtilityVM) GetAssignedMemoryInBytes(ctx context.Context) (uint64, error)

GetAssignedMemoryInBytes returns the amount of assigned memory for the UVM in bytes

func (*UtilityVM) GetNCProxyClient 

func (uvm *UtilityVM) GetNCProxyClient() (*ncproxyClient, error)

func (*UtilityVM) GetVSMBUvmPath 

func (uvm *UtilityVM) GetVSMBUvmPath(ctx context.Context, hostPath string, readOnly bool) (string, error)

GetVSMBUvmPath returns the guest path of a VSMB mount.

func (*UtilityVM) GuestRequest 

func (uvm *UtilityVM) GuestRequest(ctx context.Context, guestReq interface{}) error

GuestRequest send an arbitrary guest request to the UVM.

func (*UtilityVM) ID 

func (uvm *UtilityVM) ID() string

ID returns the ID of the VM's compute system.

func (*UtilityVM) InjectPolicyFragment 

func (uvm *UtilityVM) InjectPolicyFragment(ctx context.Context, fragment *ctrdtaskapi.PolicyFragment) error

InjectPolicyFragment sends policy fragment to GCS.

func (*UtilityVM) IsOCI 

func (*UtilityVM) IsOCI() bool

IsOCI returns false, indicating the parameters to CreateProcess should not include an OCI spec.

func (*UtilityVM) NCProxyEnabled 

func (uvm *UtilityVM) NCProxyEnabled() bool

NCProxyEnabled returns if there is a network configuration client.

func (*UtilityVM) NoWritableFileShares 

func (uvm *UtilityVM) NoWritableFileShares() bool

func (*UtilityVM) OS 

func (uvm *UtilityVM) OS() string

OS returns the operating system of the utility VM.

func (*UtilityVM) PhysicallyBacked 

func (uvm *UtilityVM) PhysicallyBacked() bool

PhysicallyBacked returns if the UVM is backed by physical memory (Over commit and deferred commit both false).

func (*UtilityVM) ProcessDumpLocation 

func (uvm *UtilityVM) ProcessDumpLocation() string

ProcessDumpLocation returns the location that process dumps will get written to for containers running in the UVM.

func (*UtilityVM) ProcessorCount 

func (uvm *UtilityVM) ProcessorCount() int32

ProcessorCount returns the number of processors actually assigned to the UVM.

func (*UtilityVM) ReleaseCPUGroup 

func (uvm *UtilityVM) ReleaseCPUGroup(ctx context.Context) error

ReleaseCPUGroup unsets the cpugroup from the VM

func (*UtilityVM) RemoveAllNICs 

func (uvm *UtilityVM) RemoveAllNICs(ctx context.Context) error

Removes all NICs added to this uvm.

func (*UtilityVM) RemoveCombinedLayersLCOW 

func (uvm *UtilityVM) RemoveCombinedLayersLCOW(ctx context.Context, rootfsPath string) error

func (*UtilityVM) RemoveCombinedLayersWCOW 

func (uvm *UtilityVM) RemoveCombinedLayersWCOW(ctx context.Context, rootfsPath string) error

RemoveCombinedLayers removes the previously combined layers at `rootfsPath`.

NOTE: `rootfsPath` is the path from within the UVM.

func (*UtilityVM) RemoveDevice 

func (uvm *UtilityVM) RemoveDevice(ctx context.Context, deviceInstanceID string, index uint16) error

RemoveDevice removes a vpci device from a uvm when there are no more references to a given VPCIDevice. Otherwise, decrements the reference count of the stored VPCIDevice and returns nil.

func (*UtilityVM) RemoveEndpointFromNS 

func (uvm *UtilityVM) RemoveEndpointFromNS(ctx context.Context, id string, endpoint *hns.HNSEndpoint) error

RemoveEndpointFromNS removes `endpoint` in the network namespace matching `id`. If no endpoint matching `endpoint.Id` is found in the network namespace this command returns `ErrNICNotFound`.

If no network namespace matches `id` this function returns `ErrNetNSNotFound`.

func (*UtilityVM) RemoveEndpointsFromNS 

func (uvm *UtilityVM) RemoveEndpointsFromNS(ctx context.Context, id string, endpoints []*hns.HNSEndpoint) error

RemoveEndpointsFromNS removes all matching `endpoints` in the network namespace matching `id`. If no endpoint matching `endpoint.Id` is found in the network namespace this command silently succeeds.

If no network namespace matches `id` returns `ErrNetNSNotFound`.

func (*UtilityVM) RemoveHvSocketService 

func (uvm *UtilityVM) RemoveHvSocketService(ctx context.Context, sid string) error

RemoveHvSocketService will remove an hvsocket service entry if it exists.

func (*UtilityVM) RemoveNICInGuest 

func (uvm *UtilityVM) RemoveNICInGuest(ctx context.Context, cfg *guestresource.LCOWNetworkAdapter) error

RemoveNICInGuest makes a request to remove a network interface inside the lcow guest. This is primarily used for removing NICs in the guest that were VPCI assigned.

func (*UtilityVM) RemoveNetNS 

func (uvm *UtilityVM) RemoveNetNS(ctx context.Context, id string) error

RemoveNetNS removes the namespace from the uvm and all remaining endpoints in the namespace.

If a namespace matching `id` is not found this command silently succeeds.

func (*UtilityVM) RemovePipe 

func (uvm *UtilityVM) RemovePipe(ctx context.Context, hostPath string) error

RemovePipe removes a shared named pipe from the UVM.

func (*UtilityVM) RemovePlan9 

func (uvm *UtilityVM) RemovePlan9(ctx context.Context, share *Plan9Share) error

RemovePlan9 removes a Plan9 share from a utility VM. Each Plan9 share is ref-counted and only actually removed when the ref-count drops to zero.

func (*UtilityVM) RemoveVPMem 

func (uvm *UtilityVM) RemoveVPMem(ctx context.Context, hostPath string) error

func (*UtilityVM) RemoveVSMB 

func (uvm *UtilityVM) RemoveVSMB(ctx context.Context, hostPath string, readOnly bool) error

RemoveVSMB removes a VSMB share from a utility VM. Each VSMB share is ref-counted and only actually removed when the ref-count drops to zero.

func (*UtilityVM) ScratchEncryptionEnabled 

func (uvm *UtilityVM) ScratchEncryptionEnabled() bool

func (*UtilityVM) SetCPUGroup 

func (uvm *UtilityVM) SetCPUGroup(ctx context.Context, id string) error

SetCPUGroup setups up the cpugroup for the VM with the requested id

func (*UtilityVM) SetConfidentialUVMOptions 

func (uvm *UtilityVM) SetConfidentialUVMOptions(ctx context.Context, opts ...ConfidentialUVMOpt) error

SetConfidentialUVMOptions sends information required to run the UVM on SNP hardware, e.g., security policy and enforcer type, signed UVM reference information, etc.

This has to happen before we start mounting things or generally changing the state of the UVM after is has been measured at startup

func (*UtilityVM) SetupNetworkNamespace 

func (uvm *UtilityVM) SetupNetworkNamespace(ctx context.Context, nsid string) error

In this function we take the namespace ID of the namespace that was created for this UVM. We hot add the namespace. We get the endpoints associated with this namespace and then hot add those endpoints.

func (*UtilityVM) Share 

func (uvm *UtilityVM) Share(ctx context.Context, reqHostPath, reqUVMPath string, readOnly bool) (err error)

Share shares in file(s) from `reqHostPath` on the host machine to `reqUVMPath` inside the UVM. This function handles both LCOW and WCOW scenarios.

func (*UtilityVM) SignalProcessSupported 

func (uvm *UtilityVM) SignalProcessSupported() bool

SignalProcessSupported returns `true` if the guest supports the capability to signal a process.

This support was added RS5+ guests.

func (*UtilityVM) Start 

func (uvm *UtilityVM) Start(ctx context.Context) (err error)

Start synchronously starts the utility VM.

func (*UtilityVM) Stats 

func (uvm *UtilityVM) Stats(ctx context.Context) (*stats.VirtualMachineStatistics, error)

Stats returns various UVM statistics.

func (*UtilityVM) TearDownNetworking 

func (uvm *UtilityVM) TearDownNetworking(ctx context.Context, nsid string) error

TearDownNetworking tears down the utility VMs networking setup using the namespace ID `nsid`.

func (*UtilityVM) Terminate 

func (uvm *UtilityVM) Terminate(ctx context.Context) error

Terminate requests that the utility VM be terminated.

func (*UtilityVM) UVMMountCounter 

func (uvm *UtilityVM) UVMMountCounter() uint64

mountCounter is used for maintaining the number of mounts to the UVM. This helps in generating unique mount paths for every mount.

func (*UtilityVM) Update 

func (uvm *UtilityVM) Update(ctx context.Context, data interface{}, annots map[string]string) error

func (*UtilityVM) UpdateCPULimits 

func (uvm *UtilityVM) UpdateCPULimits(ctx context.Context, limits *hcsschema.ProcessorLimits) error

UpdateCPULimits updates the CPU limits of the utility vm

func (*UtilityVM) UpdateHvSocketService 

func (uvm *UtilityVM) UpdateHvSocketService(ctx context.Context, sid string, doc *hcsschema.HvSocketServiceConfig) error

UpdateHvSocketService calls HCS to update/create the hvsocket service for the UVM. Takes in a service ID and the hvsocket service configuration. If there is no entry for the service ID already it will be created. The same call on HvSockets side handles the Create/Update/Delete cases based on what is passed in. Here is the logic for the call.

1. If the service ID does not currently exist in the service table, it will be created with whatever descriptors and state was specified (disabled or not). 2. If the service already exists and empty descriptors and Disabled is passed in for the service config, the service will be removed. 3. Otherwise any combination that is not Disabled && Empty descriptors will just update the service.

If the request is crafted with Disabled = True and empty descriptors, then this function will behave identically to a call to RemoveHvSocketService. Prefer RemoveHvSocketService for this behavior as the relevant fields are set on HCS' side.

func (*UtilityVM) UpdateMemory 

func (uvm *UtilityVM) UpdateMemory(ctx context.Context, sizeInBytes uint64) error

UpdateMemory makes a call to the VM's orchestrator to update the VM's size in MB Internally, HCS will get the number of pages this corresponds to and attempt to assign pages to numa nodes evenly

func (*UtilityVM) UpdateNIC 

func (uvm *UtilityVM) UpdateNIC(ctx context.Context, id string, settings *hcsschema.NetworkAdapter) error

UpdateNIC updates a UVM's network adapter.

func (*UtilityVM) VSMBNoDirectMap 

func (uvm *UtilityVM) VSMBNoDirectMap() bool

VSMBNoDirectMap returns if VSMB devices should be mounted with `NoDirectMap` set to true.

func (*UtilityVM) Wait 

func (uvm *UtilityVM) Wait() error

Wait waits synchronously for a utility VM to terminate.

func (*UtilityVM) WaitCtx 

func (uvm *UtilityVM) WaitCtx(ctx context.Context) (err error)

Wait waits synchronously for a utility VM to terminate, or the context to be cancelled.

type VPCIDevice 

type VPCIDevice struct {

	// VMBusGUID is the instance ID for this device when it is exposed via VMBus
	VMBusGUID string
	// contains filtered or unexported fields
}

VPCIDevice represents a vpci device. Holds its guid and a handle to the uvm it belongs to.

func (*VPCIDevice) Release 

func (vpci *VPCIDevice) Release(ctx context.Context) error

Release frees the resources of the corresponding vpci device

type VPCIDeviceID 

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

func NewVPCIDeviceID 

func NewVPCIDeviceID(deviceInstanceID string, virtualFunctionIndex uint16) VPCIDeviceID

type VPMEMMount 

type VPMEMMount struct {
	GuestPath string
	// contains filtered or unexported fields
}

func (*VPMEMMount) Release 

func (vc *VPMEMMount) Release(ctx context.Context) error

type VSMBShare 

type VSMBShare struct {
	HostPath string
	// contains filtered or unexported fields
}

VSMBShare contains the host path for a Vsmb Mount.

func (*VSMBShare) Release 

func (vsmb *VSMBShare) Release(ctx context.Context) error

Release frees the resources of the corresponding vsmb Mount

type WCOWBootFiles 

type WCOWBootFiles struct {
	// Path to the directory that contains the OS files.
	OSFilesPath string
	// Path of the boot directory relative to the `OSFilesPath`. This boot directory MUST
	// contain the BCD & bootmgfw.efi files.
	OSRelativeBootDirPath string
	// Path for the scratch VHD of thef UVM
	ScratchVHDPath string
}

Source Files

capabilities.go combine_layers.go computeagent.go constants.go counter.go cpugroups.go cpulimits_update.go create.go create_lcow.go create_wcow.go delete_container.go doc.go dumpstacks.go guest_request.go hvsocket.go memory_update.go modify.go network.go pipes.go plan9.go security_policy.go share.go start.go stats.go timezone.go types.go update_uvm.go virtual_device.go vpmem.go vpmem_mapped.go vsmb.go wait.go

Directories

PathSynopsis
internal/uvm/scsiPackage scsi handles SCSI device attachment and mounting for VMs.
Version
v0.13.0-rc.1
Published
Jun 27, 2024
Platform
windows/amd64
Imports
63 packages
Last checked
37 minutes ago –

Tools for package owners.