uvm

Documentation

Index

• Constants
• Variables
• type MemoryBackingType
• type PreferredRootFSType
• type UVMOptions
• type UtilityVM
  • func Create(opts *UVMOptions) (_ *UtilityVM, err error)
  • func (uvm *UtilityVM) AddNetNS(id string, endpoints []*hns.HNSEndpoint) (err error)
  • func (uvm *UtilityVM) AddPlan9(hostPath string, uvmPath string, readOnly bool) error
  • func (uvm *UtilityVM) AddSCSI(hostPath string, uvmPath string) (int, int32, error)
  • func (uvm *UtilityVM) AddSCSILayer(hostPath string) (int, int32, error)
  • func (uvm *UtilityVM) AddVPMEM(hostPath string, expose bool) (uint32, string, error)
  • func (uvm *UtilityVM) AddVSMB(hostPath string, guestRequest interface{}, ...) error
  • func (uvm *UtilityVM) Close() error
  • func (uvm *UtilityVM) ComputeSystem() *hcs.System
  • func (uvm *UtilityVM) ContainerCounter() uint64
  • func (uvm *UtilityVM) GetVSMBUvmPath(hostPath string) (string, error)
  • func (uvm *UtilityVM) ID() string
  • func (uvm *UtilityVM) Modify(hcsModificationDocument interface{}) error
  • func (uvm *UtilityVM) OS() string
  • func (uvm *UtilityVM) RemoveNetNS(id string) error
  • func (uvm *UtilityVM) RemovePlan9(hostPath string) error
  • func (uvm *UtilityVM) RemoveSCSI(hostPath string) error
  • func (uvm *UtilityVM) RemoveVPMEM(hostPath string) error
  • func (uvm *UtilityVM) RemoveVSMB(hostPath string) error
  • func (uvm *UtilityVM) Start() error
  • func (uvm *UtilityVM) Terminate() error
  • func (uvm *UtilityVM) Wait() error

Constants

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

	// DefaultVPMEM 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.
	DefaultVPMEM = 64
)

const (
	PreferredRootFSTypeInitRd = 0
	PreferredRootFSTypeVHD    = 1
)

Variables

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

Types

type MemoryBackingType

type MemoryBackingType int

MemoryBackingType is the set of values possible for the UVM's memory type. TODO: JTERRY75 - Get this into the OCI spec for WindowsMemoryResources

const (
	// MemoryBackingTypeVirtual uses virtual memory for the UVM.
	MemoryBackingTypeVirtual MemoryBackingType = iota
	// MemoryBackingTypeVirtualDeferred uses virtual memory for the UVM with
	// Deferred Commit.
	MemoryBackingTypeVirtualDeferred
	// MemoryBackingTypePhysical uses physical memory for the UVM.
	MemoryBackingTypePhysical
)

type PreferredRootFSType

type PreferredRootFSType int

type UVMOptions

type UVMOptions struct {
	ID                      string                  // Identifier for the uvm. Defaults to generated GUID.
	Owner                   string                  // Specifies the owner. Defaults to executable name.
	OperatingSystem         string                  // "windows" or "linux".
	Resources               *specs.WindowsResources // Optional resources for the utility VM. Supports Memory.limit and CPU.Count only currently. // TODO consider extending?
	AdditionHCSDocumentJSON string                  // Optional additional JSON to merge into the HCS document prior

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

	// LCOW specific parameters
	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`
	RootFSFile            string               // Filename under BootFilesPath for the UVMs root file system. Defaults are `initrd.img` or `rootfs.vhd`.
	PreferredRootFSType   *PreferredRootFSType // Controls searching for the RootFSFile.
	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
	VPMemDeviceCount      *int32               // Number of VPMem devices. Limit at 128. If booting UVM from VHD, device 0 is taken. LCOW Only.
	SCSIControllerCount   *int                 // The number of SCSI controllers. Defaults to 1 if omitted. Currently we only support 0 or 1.

	// TODO: JTERRY75 - If we put this in OCI remove this type and use it from WindowsMemoryResources
	MemoryBackingType *MemoryBackingType
}

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

type UtilityVM

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

UtilityVM is the object used by clients representing a utility VM

func Create

func Create(opts *UVMOptions) (_ *UtilityVM, err error)

Create creates an HCS compute system representing a utility VM.

WCOW Notes:

• If the scratch folder does not exist, it will be created
• If the scratch folder does not contain `sandbox.vhdx` it will be created based on the system template located in the layer folders.
• The scratch is always attached to SCSI 0:0

func (*UtilityVM) AddNetNS

func (uvm *UtilityVM) AddNetNS(id string, endpoints []*hns.HNSEndpoint) (err error)

AddNetNS adds network namespace inside the guest & adds endpoints to the guest on that namepace

func (*UtilityVM) AddPlan9

func (uvm *UtilityVM) AddPlan9(hostPath string, uvmPath string, readOnly bool) error

AddPlan9 adds a Plan9 share to a utility VM. Each Plan9 share is ref-counted and only added if it isn't already.

func (*UtilityVM) AddSCSI

func (uvm *UtilityVM) AddSCSI(hostPath string, uvmPath string) (int, int32, error)

AddSCSI adds a SCSI disk to a utility VM at the next available location. This function should be called for a RW/scratch layer. For read-only layers on LCOW as an alternate to PMEM for large layers, use AddSCSILayer instead.

hostPath is required uvmPath is optional.

func (*UtilityVM) AddSCSILayer

func (uvm *UtilityVM) AddSCSILayer(hostPath string) (int, int32, error)

AddSCSILayer adds a read-only layer disk to a utility VM at the next available location. This function is used by LCOW as an alternate to PMEM for large layers. The UVMPath will always be /tmp/S<controller>/<lun>.

func (*UtilityVM) AddVPMEM

func (uvm *UtilityVM) AddVPMEM(hostPath string, expose bool) (uint32, string, error)

AddVPMEM adds a VPMEM disk to a utility VM at the next available location.

Returns the location(0..MaxVPMEM-1) where the device is attached, and if exposed, the utility VM path which will be /tmp/p<location>//

func (*UtilityVM) AddVSMB

func (uvm *UtilityVM) AddVSMB(hostPath string, guestRequest interface{}, options *hcsschema.VirtualSmbShareOptions) 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) Close

func (uvm *UtilityVM) Close() error

Close terminates and releases resources associated with the utility VM.

func (*UtilityVM) ComputeSystem

func (uvm *UtilityVM) ComputeSystem() *hcs.System

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

func (uvm *UtilityVM) GetVSMBUvmPath(hostPath string) (string, error)

GetVSMBUvmPath returns the guest path of a VSMB mount.

func (*UtilityVM) ID

func (uvm *UtilityVM) ID() string

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

func (*UtilityVM) Modify

func (uvm *UtilityVM) Modify(hcsModificationDocument interface{}) error

Modifies the compute system by sending a request to HCS

func (*UtilityVM) OS

func (uvm *UtilityVM) OS() string

OS returns the operating system of the utility VM.

func (*UtilityVM) RemoveNetNS

func (uvm *UtilityVM) RemoveNetNS(id string) error

RemoveNetNS removes the namespace information

func (*UtilityVM) RemovePlan9

func (uvm *UtilityVM) RemovePlan9(hostPath string) 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(hostPath string) error

RemoveSCSI removes a SCSI disk from a utility VM. As an external API, it is "safe". Internal use can call removeSCSI.

func (*UtilityVM) RemoveVPMEM

func (uvm *UtilityVM) RemoveVPMEM(hostPath string) error

RemoveVPMEM removes a VPMEM disk from a utility VM. As an external API, it is "safe". Internal use can call removeVPMEM.

func (*UtilityVM) RemoveVSMB

func (uvm *UtilityVM) RemoveVSMB(hostPath string) 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) Start

func (uvm *UtilityVM) Start() error

Start synchronously starts the utility VM.

func (*UtilityVM) Terminate

func (uvm *UtilityVM) Terminate() error

Terminate requests a utility VM terminate. If IsPending() on the error returned is true, it may not actually be shut down until Wait() succeeds.

func (*UtilityVM) Wait

func (uvm *UtilityVM) Wait() error

Waits synchronously waits for a utility VM to terminate.