uvm

package
v0.9.8 Latest Latest
Warning

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

 Go to latest Published: Mar 15, 2023 License: MIT Imports: 63 Imported by: 0

Documentation

Index

Constants

View Source 
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 * 1024 * 1024 * 1024 // 4GB

	// LCOWMountPathPrefix is the path format in the LCOW UVM where non global mounts, such
	// as Plan9 mounts are added
	LCOWMountPathPrefix = "/mounts/m%d"
	// LCOWGlobalMountPrefix is the path format in the LCOW UVM where global mounts are added
	LCOWGlobalMountPrefix = "/run/mounts/m%d"
	// LCOWNvidiaMountPath is the path format in LCOW UVM where nvidia tools are mounted
	// keep this value in sync with opengcs
	LCOWNvidiaMountPath = "/run/nvidia"
	// WCOWGlobalMountPrefix is the path prefix format in the WCOW UVM where mounts are added
	WCOWGlobalMountPrefix = "C:\\mounts\\m%d"
	// RootfsPath is part of the container's rootfs path
	RootfsPath = "rootfs"
)
View Source 
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"
	// 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"
)
View Source 
const (
	GPUDeviceIDType         = "gpu"
	VPCILocationPathIDType  = "vpci-location-path"
	VPCIClassGUIDTypeLegacy = "class"
	VPCIClassGUIDType       = "vpci-class-guid"
	VPCIDeviceIDTypeLegacy  = "vpci"
	VPCIDeviceIDType        = "vpci-instance-id"
)
View Source 
const (
	PageSize             = 0x1000
	MaxMappedDeviceCount = 1024
)
View Source 
const ComputeAgentAddrFmt = "\\\\.\\pipe\\computeagent-%s"
View Source 
const (

	// default namespace ID used for all template and clone VMs.
	DefaultCloneNetworkNamespaceID = "89EB8A86-E253-41FD-9800-E6D88EB2E18A"
)

Variables

View Source 
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")
)
View Source 
var (
	ErrNoAvailableLocation      = fmt.Errorf("no available location")
	ErrNotAttached              = fmt.Errorf("not attached")
	ErrAlreadyAttached          = fmt.Errorf("already attached")
	ErrNoSCSIControllers        = fmt.Errorf("no SCSI controllers configured for this utility VM")
	ErrTooManyAttachments       = fmt.Errorf("too many SCSI attachments")
	ErrSCSILayerWCOWUnsupported = fmt.Errorf("SCSI attached layers are not supported for WCOW")
)
View Source 
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")
)
View Source 
var ErrNoNetworkSetup = errors.New("no network setup present for UVM")

Functions

func GetContainerPipeMapping added in v0.8.7 

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 added in v0.8.16 

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

GetNamespaceEndpoints gets all endpoints in `netNS`

func IsPipe added in v0.8.7 

func IsPipe(hostPath string) bool

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

func ParseExtensibleVirtualDiskPath added in v0.9.0 

func ParseExtensibleVirtualDiskPath(hostPath string) (evdType, mountPath string, err error)

ParseExtensibleVirtualDiskPath parses the evd path provided in the config. extensible virtual disk path has format "evd://<evdType>/<evd-mount-path>" this function parses that and returns the `evdType` and `evd-mount-path`.

Types

type Cloneable added in v0.8.15 

type Cloneable interface {

	// A SerialVersionID is an identifier used to recognize a unique version of a
	// resource. Every time the definition of the resource struct changes this ID is
	// bumped up.  This ID is used to ensure that we serialize and deserialize the
	// same version of a resource.
	GetSerialVersionID() uint32

	// Clone function creates a clone of the resource on the UVM `vm` (i.e adds the
	// cloned resource to the `vm`)
	// `cd` parameter can be used to pass any other data that is required during the
	// cloning process of that resource (for example, when cloning SCSI Mounts we
	// might need scratchFolder).
	// Clone function should be called on a valid struct (Mostly on the struct which
	// is deserialized, and so Clone function should only depend on the fields that
	// are exported in the struct).
	// The implementation of the clone function should avoid reading any data from the
	// `vm` struct, it can add new fields to the vm struct but since the vm struct
	// isn't fully ready at this point it shouldn't be used to read any data.
	Clone(ctx context.Context, vm *UtilityVM, cd *cloneData) error
}

Cloneable is a generic interface for cloning a specific resource. Not all resources can be cloned and so all resources might not implement this interface. This interface is mainly used during late cloning process to clone the resources associated with the UVM and the container. For some resources (like scratch VHDs of the UVM & container) cloning means actually creating a copy of that resource while for some resources it simply means adding that resource to the cloned VM without copying (like VSMB shares). The Clone function of that resource will deal with these details.

type NetworkConfigType added in v0.8.16 

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 added in v0.8.8 

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 added in v0.8.8 

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

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

type NetworkSetup added in v0.8.16 

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 added in v0.8.16 

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 added in v0.8.16 

func NewInternalNetworkSetup(vm *UtilityVM) NetworkSetup

type Options added in v0.8.4 

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
	// unneccessary 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
}

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

type OptionsLCOW added in v0.8.4 

type OptionsLCOW struct {
	*Options

	BootFilesPath           string              // Folder in which kernel and root file system reside. Defaults to \Program Files\Linux Containers
	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
	SCSIControllerCount     uint32              // The number of SCSI controllers. Defaults to 1. Currently we only support 0 or 1.
	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
	OutputHandler           OutputHandler       `json:"-"` // 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
	SecurityPolicy          string              // Optional security policy
}

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

func NewDefaultOptionsLCOW added in v0.8.4 

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.

type OptionsWCOW added in v0.8.4 

type OptionsWCOW struct {
	*Options

	LayerFolders []string // Set of folders for base layers and scratch. Ordered from top most read-only through base read-only layer, followed by scratch

	// IsTemplate specifies if this UVM will be saved as a template in future. Setting
	// this option will also enable some VSMB Options during UVM creation that allow
	// template creation.
	IsTemplate bool

	// IsClone specifies if this UVM should be created by cloning a template. If
	// IsClone is true then a valid UVMTemplateConfig struct must be passed in the
	// `TemplateConfig` field.
	IsClone bool

	// TemplateConfig is only used during clone creation. If a uvm is
	// being cloned then this TemplateConfig struct must be passed
	// which holds all the information about the template from
	// which this clone should be created.
	TemplateConfig *UVMTemplateConfig

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

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

func NewDefaultOptionsWCOW added in v0.8.4 

func NewDefaultOptionsWCOW(id, owner string) *OptionsWCOW

NewDefaultOptionsWCOW creates the default options for a bootable version of WCOW. The caller `MUST` set the `LayerFolders` path 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 added in v0.8.4 

type OutputHandler func(io.Reader)

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

type PipeMount added in v0.8.8 

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

PipeMount contains the host path for pipe mount

func (*PipeMount) Release added in v0.8.8 

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

Release frees the resources of the corresponding pipe Mount

type Plan9Share added in v0.8.7 

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

Plan9Share is a struct containing host paths for the UVM

func (*Plan9Share) Release added in v0.8.8 

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
)

type SCSIMount added in v0.8.8 

type SCSIMount struct {

	// path is the host path to the vhd that is mounted.
	HostPath string
	// path for the uvm
	UVMPath string
	// scsi controller
	Controller int
	// scsi logical unit number
	LUN int32
	// contains filtered or unexported fields
}

SCSIMount struct representing a SCSI mount point and the UVM it belongs to.

func (*SCSIMount) Clone added in v0.8.15 

func (sm *SCSIMount) Clone(ctx context.Context, vm *UtilityVM, cd *cloneData) error

Clone function creates a clone of the SCSIMount `sm` and adds the cloned SCSIMount to the uvm `vm`. If `sm` is read only then it is simply added to the `vm`. But if it is a writeable mount(e.g a scratch layer) then a copy of it is made and that copy is added to the `vm`.

func (*SCSIMount) GetSerialVersionID added in v0.8.15 

func (sm *SCSIMount) GetSerialVersionID() uint32

func (*SCSIMount) GobDecode added in v0.8.15 

func (sm *SCSIMount) GobDecode(data []byte) error

GobDecode deserializes the SCSIMount struct into the struct on which this is called (i.e the sm pointer)

func (*SCSIMount) GobEncode added in v0.8.15 

func (sm *SCSIMount) GobEncode() ([]byte, error)

GobEncode serializes the SCSIMount struct

func (*SCSIMount) RefCount added in v0.8.15 

func (sm *SCSIMount) RefCount() uint32

RefCount returns the current refcount for the SCSI mount.

func (*SCSIMount) Release added in v0.8.8 

func (sm *SCSIMount) Release(ctx context.Context) error

Release frees the resources of the corresponding Scsi Mount

type UVMTemplateConfig added in v0.8.15 

type UVMTemplateConfig struct {
	// ID of the template vm
	UVMID string
	// Array of all resources that will be required while making a clone from this template
	Resources []Cloneable
	// The OptionsWCOW used for template uvm creation
	CreateOpts OptionsWCOW
}

UVMTemplateConfig is just a wrapper struct that keeps together all the resources that need to be saved to create a template.

type UtilityVM 

type UtilityVM struct {

	// specifies if this UVM is created to be saved as a template
	IsTemplate bool

	// specifies if this UVM is a cloned from a template
	IsClone bool

	// ID of the template from which this clone was created. Only applies when IsClone
	// is true
	TemplateID string
	// contains filtered or unexported fields
}

UtilityVM is the object used by clients representing a utility VM

func CreateLCOW added in v0.8.4 

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

CreateLCOW creates an HCS compute system representing a utility VM.

func CreateWCOW added in v0.8.4 

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

CreateWCOW creates an HCS compute system representing a utility VM. The HCS Compute system can either be created from scratch or can be cloned from a template.

WCOW Notes:

  • The scratch is always attached to SCSI 0:0

func (*UtilityVM) AddEndpointToNSWithID added in v0.8.16 

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 added in v0.8.7 

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) 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 added in v0.8.15 

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 added in v0.8.7 

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) AddSCSI 

func (uvm *UtilityVM) AddSCSI(
	ctx context.Context,
	hostPath string,
	uvmPath string,
	readOnly bool,
	encrypted bool,
	guestOptions []string,
	vmAccess VMAccessType,
) (*SCSIMount, error)

AddSCSI adds a SCSI disk to a utility VM at the next available location. This function should be called for adding a scratch layer, a read-only layer as an alternative to VPMEM, or for other VHD mounts.

`hostPath` is required and must point to a vhd/vhdx path.

`uvmPath` is optional. If not provided, no guest request will be made

`readOnly` set to `true` if the vhd/vhdx should be attached read only.

`encrypted` set to `true` if the vhd/vhdx should be attached in encrypted mode. The device will be formatted, so this option must be used only when creating scratch vhd/vhdx.

`guestOptions` is a slice that contains optional information to pass to the guest service

`vmAccess` indicates what access to grant the vm for the hostpath

func (*UtilityVM) AddSCSIExtensibleVirtualDisk added in v0.9.0 

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

AddSCSIExtensibleVirtualDisk adds an extensible virtual disk as a SCSI mount to the utility VM at the next available location. All such disks which are not actual virtual disks but provide the same SCSI interface are added to the UVM as Extensible Virtual disks.

`hostPath` is required. Depending on the type of the extensible virtual disk the format of `hostPath` can be different. For example, in case of storage spaces the host path must be in the `evd://space/{storage_pool_unique_ID}{virtual_disk_unique_ID}` format.

`uvmPath` must be provided in order to be able to use this disk in a container.

`readOnly` set to `true` if the virtual disk should be attached read only.

`vmAccess` indicates what access to grant the vm for the hostpath

func (*UtilityVM) AddSCSIPhysicalDisk added in v0.8.4 

func (uvm *UtilityVM) AddSCSIPhysicalDisk(ctx context.Context, hostPath, uvmPath string, readOnly bool, guestOptions []string) (*SCSIMount, error)

AddSCSIPhysicalDisk attaches a physical disk from the host directly to the Utility VM at the next available location.

`hostPath` is required and `likely` start's with `\\.\PHYSICALDRIVE`.

`uvmPath` is optional if a guest mount is not requested.

`readOnly` set to `true` if the physical disk should be attached read only.

`guestOptions` is a slice that contains optional information to pass to the guest service

func (*UtilityVM) AddVPMem added in v0.9.0 

func (uvm *UtilityVM) AddVPMem(ctx context.Context, hostPath string) (string, 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) AssignDevice added in v0.8.8 

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

AssignDevice assigns a vpci device to the 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

func (*UtilityVM) Capabilities added in v0.8.7 

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) CloneContainer added in v0.8.15 

func (uvm *UtilityVM) CloneContainer(ctx context.Context, id string) (cow.Container, error)

CloneContainer attaches back to a container that is already running inside the UVM because of the clone

func (*UtilityVM) Close 

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

Close terminates and releases resources associated with the utility VM.

func (*UtilityVM) CloseGCSConnection added in v0.8.15 

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 added in v0.8.7 

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 added in v0.8.7 

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 added in v0.8.16 

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 added in v0.8.16 

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 added in v0.8.7 

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 added in v0.8.7 

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

CreateProcess creates a process in the utility VM.

func (*UtilityVM) DefaultVSMBOptions added in v0.8.10 

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 added in v0.8.8 

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

func (*UtilityVM) DeleteContainerStateSupported added in v0.8.8 

func (uvm *UtilityVM) DeleteContainerStateSupported() bool

func (*UtilityVM) DevicesPhysicallyBacked added in v0.8.10 

func (uvm *UtilityVM) DevicesPhysicallyBacked() bool

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

func (*UtilityVM) DumpStacks added in v0.8.7 

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

func (*UtilityVM) ExitError added in v0.8.7 

func (uvm *UtilityVM) ExitError() error

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

func (*UtilityVM) GenerateTemplateConfig added in v0.8.15 

func (uvm *UtilityVM) GenerateTemplateConfig() (*UVMTemplateConfig, error)

Captures all the information that is necessary to properly save this UVM as a template and create clones from this template later. The struct returned by this method must be later on made available while creating a clone from this template.

func (*UtilityVM) GetAssignedDeviceVMBUSInstanceID added in v0.8.10 

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 added in v0.8.10 

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

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

func (*UtilityVM) GetNCProxyClient added in v0.9.0 

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

func (*UtilityVM) GetScsiUvmPath added in v0.8.4 

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

GetScsiUvmPath returns the guest mounted path of a SCSI drive.

If `hostPath` is not mounted returns `ErrNotAttached`.

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 added in v0.8.10 

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) IsOCI added in v0.8.7 

func (uvm *UtilityVM) IsOCI() bool

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

func (*UtilityVM) NCProxyEnabled added in v0.8.16 

func (uvm *UtilityVM) NCProxyEnabled() bool

NCProxyEnabled returns if there is a network configuration client.

func (*UtilityVM) OS 

func (uvm *UtilityVM) OS() string

OS returns the operating system of the utility VM.

func (*UtilityVM) PhysicallyBacked added in v0.8.10 

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 added in v0.9.0 

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 added in v0.8.7 

func (uvm *UtilityVM) ProcessorCount() int32

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

func (*UtilityVM) ReleaseCPUGroup added in v0.8.13 

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

ReleaseCPUGroup unsets the cpugroup from the VM

func (*UtilityVM) RemoveAllNICs added in v0.8.15 

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

Removes all NICs added to this uvm.

func (*UtilityVM) RemoveCombinedLayersLCOW added in v0.9.0 

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

func (*UtilityVM) RemoveCombinedLayersWCOW added in v0.9.0 

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) RemoveEndpointFromNS added in v0.8.16 

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 added in v0.8.7 

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 added in v0.8.11 

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

RemoveHvSocketService will remove an hvsocket service entry if it exists.

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 added in v0.8.7 

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) RemoveSCSI 

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

RemoveSCSI removes a SCSI disk from a utility VM.

func (*UtilityVM) RemoveVPMem added in v0.9.0 

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) SaveAsTemplate added in v0.8.15 

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

Pauses the uvm and then saves it as a template. This uvm can not be restarted or used after it is successfully saved. uvm must be in the paused state before it can be saved as a template.save call will throw an incorrect uvm state exception if uvm is not in the paused state at the time of saving.

func (*UtilityVM) ScratchEncryptionEnabled added in v0.9.0 

func (uvm *UtilityVM) ScratchEncryptionEnabled() bool

ScratchEncryptionEnabled is a getter for `uvm.encryptScratch`.

Returns true if the scratch disks should be encrypted, false otherwise.

func (*UtilityVM) SetCPUGroup added in v0.8.13 

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

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

func (*UtilityVM) SetSaveableVSMBOptions added in v0.8.15 

func (uvm *UtilityVM) SetSaveableVSMBOptions(opts *hcsschema.VirtualSmbShareOptions, readOnly bool)

func (*UtilityVM) SetSecurityPolicy added in v0.9.0 

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

SetSecurityPolicy tells the gcs instance in the UVM what policy to apply.

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 added in v0.8.16 

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

Network namespace setup is a bit different for templates and clones. For templates and clones we use a special network namespace ID. Details about this can be found in the Networking section of the late-clone wiki page.

In this function we take the namespace ID of the namespace that was created for this UVM. We hot add the namespace (with the default ID if this is a template). We get the endpoints associated with this namespace and then hot add those endpoints (by changing their namespace IDs by the deafult IDs if it is a template).

func (*UtilityVM) Share added in v0.8.14 

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 added in v0.8.7 

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 added in v0.8.7 

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

Stats returns various UVM statistics.

func (*UtilityVM) TearDownNetworking added in v0.8.16 

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 added in v0.8.8 

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) UpdateCPULimits added in v0.8.13 

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

UpdateCPULimits updates the CPU limits of the utility vm

func (*UtilityVM) UpdateConstraints added in v0.9.0 

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

func (*UtilityVM) UpdateHvSocketService added in v0.8.11 

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 added in v0.8.10 

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 added in v0.8.16 

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

UpdateNIC updates a UVM's network adapter.

func (*UtilityVM) VSMBNoDirectMap added in v0.9.0 

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.

type VMAccessType added in v0.8.8 

type VMAccessType int

VMAccessType is used to determine the various types of access we can grant for a given file. 

const (
	// `VMAccessTypeNoop` indicates no additional access should be given. Note
	// this should be used for layers and gpu vhd where we have given VM group
	// access outside of the shim (containerd for layers, package installation
	// for gpu vhd).
	VMAccessTypeNoop VMAccessType = iota
	// `VMAccessTypeGroup` indicates we should give access to a file for the VM group sid
	VMAccessTypeGroup
	// `VMAccessTypeIndividual` indicates we should give additional access to a file for
	// the running VM only
	VMAccessTypeIndividual
)

type VPCIDevice added in v0.8.8 

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 added in v0.8.8 

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

Release frees the resources of the corresponding vpci device

type VPCIDeviceKey added in v0.9.0 

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

type VSMBShare added in v0.8.8 

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

VSMBShare contains the host path for a Vsmb Mount

func (*VSMBShare) Clone added in v0.8.15 

func (vsmb *VSMBShare) Clone(ctx context.Context, vm *UtilityVM, cd *cloneData) error

Clone creates a clone of the VSMBShare `vsmb` and adds that clone to the uvm `vm`. To clone VSMB share we just need to add it into the config doc of that VM and increase the vsmb counter.

func (*VSMBShare) GetSerialVersionID added in v0.8.15 

func (vsmb *VSMBShare) GetSerialVersionID() uint32

func (*VSMBShare) GobDecode added in v0.8.15 

func (vsmb *VSMBShare) GobDecode(data []byte) error

GobDecode deserializes the VSMBShare struct into the struct on which this is called (i.e the vsmb pointer)

func (*VSMBShare) GobEncode added in v0.8.15 

func (vsmb *VSMBShare) GobEncode() ([]byte, error)

GobEncode serializes the VSMBShare struct

func (*VSMBShare) Release added in v0.8.8 

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

Release frees the resources of the corresponding vsmb Mount

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.