Version: v0.1.20 Latest Latest

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

Go to latest
Published: Jul 3, 2018 License: MPL-2.0 Imports: 24 Imported by: 0



Package vm provides virtual machine abstractions using QEMU.



This section is empty.


View Source
var MachineLimitsSchema = schematypes.Object{
	Title: "Machine Limits",
	Description: util.Markdown(`
		Limitations and default values for the virtual machine
		configuration. Tasks with machine images that does not satisfy
		these limitations will be resolved 'malformed-payload'.
	Properties: schematypes.Properties{
		"maxMemory": schematypes.Integer{
			Title: "Max Memory",
			Description: util.Markdown(`
				Maximum allowed virtual machine memory in MiB. This is
				also the default memory if the machine image does not
				specify memory requirements. If the machine specifies a
				memory higher than this, the task will fail to run.
			Minimum: 0,
			Maximum: 1024 * 1024,
		"maxCPUs": schematypes.Integer{
			Title: "Max CPUs",
			Description: util.Markdown(`
				Maximum number of CPUs a virtual machine can use.

				This is the product of 'threads', 'cores' and 'sockets' as specified
				in the machine definition 'machine.json'. If the virtual machine image
				does not specify CPU requires it will be given
				'maxCPUs / defaultThreads' number of cores in a single socket.
			Minimum: 1,
			Maximum: 255,
		"defaultThreads": schematypes.Integer{
			Title: "Default CPU Threads",
			Description: util.Markdown(`
				Number of CPU threads to assign, if assigning default values for
				'threads', 'cores' and 'sockets' based on 'maxCPUs'.

				This should generally default to 2, if the host features hyperthreading,
				otherwise 1 is likely ideal.
			Minimum: 1,
			Maximum: 255,
	Required: []string{

MachineLimitsSchema is the schema for MachineOptions.

View Source
var MachineSchema schematypes.Schema = schematypes.Object{
	Title:       "Machine Configuration",
	Description: `Hardware definition for a virtual machine`,
	Properties: schematypes.Properties{
		"version": schematypes.IntegerEnum{
			Title:   "Format Version",
			Options: []int{machineFormatVersion},
		"uuid": schematypes.String{
			Title:       "System UUID",
			Description: `System UUID for the virtual machine`,
			Pattern:     `^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`,
		"chipset": schematypes.StringEnum{
			Title:   "Chipset",
			Options: []string{"pc-i440fx-2.8"},
		"cpu": schematypes.StringEnum{
			Title: "CPU",
			Description: util.Markdown(`
				CPU to be exposed to the virtual machine.

				The number of virtual CPUs inside the virtual machine will be
				'threads * cores * sockets' as configured below.
			Options: []string{"host"},
		"flags": schematypes.Array{
			Items: schematypes.StringEnum{},
		"threads": schematypes.Integer{
			Description: "Threads per CPU core, leave undefined to get maximum available",
			Minimum:     1,
			Maximum:     255,
		"cores": schematypes.Integer{
			Description: "CPU cores per socket, leave undefined to get maximum available",
			Minimum:     1,
			Maximum:     255,
		"sockets": schematypes.Integer{
			Description: "CPU sockets in machine, leave undefined to get maximum available",
			Minimum:     1,
			Maximum:     255,
		"memory": schematypes.Integer{
			Title:       "Memory",
			Description: `Memory in MiB, defaults to maximum available, if not specified.`,
			Minimum:     1,
			Maximum:     1024 * 1024,
		"usb": schematypes.StringEnum{
			Title:   "Host Controller Interface",
			Options: []string{"piix3-usb-uhci", "piix4-usb-uhci", "nec-usb-xhci"},
		"network": schematypes.StringEnum{
			Title:   "Network Interface Controller",
			Options: []string{"rtl8139", "e1000"},
		"mac": schematypes.String{
			Title:       "MAC Address",
			Description: `Local unicast MAC Address`,
			Pattern:     `^[0-9a-f][26ae](:[0-9a-f]{2}){5}$`,
		"storage": schematypes.StringEnum{
			Title:       "Storage Device",
			Description: `Block device to use for attaching storage`,
			Options:     []string{"virtio-blk-pci"},
		"graphics": schematypes.StringEnum{
			Options: []string{"VGA", "vmware-svga", "qxl-vga", "virtio-vga"},
		"sound": schematypes.StringEnum{
			Options: []string{
				"AC97", "ES1370",
				"hda-duplex/intel-hda", "hda-micro/intel-hda", "hda-output/intel-hda",
				"hda-duplex/ich9-intel-hda", "hda-micro/ich9-intel-hda", "hda-output/ich9-intel-hda",
		"keyboard": schematypes.StringEnum{
			Options: []string{"usb-kbd", "PS/2"},
		"keyboardLayout": schematypes.StringEnum{
			Options: []string{
				"ar", "da", "de", "de-ch", "en-gb", "en-us", "es", "et", "fi", "fo",
				"fr", "fr-be", "fr-ca", "fr-ch", "hr", "hu", "is", "it", "ja", "lt",
				"lv", "mk", "nl", "nl-be", "no", "pl", "pt", "pt-br", "ru", "sl",
				"sv", "th", "tr",
		"mouse": schematypes.StringEnum{
			Options: []string{"usb-mouse", "PS/2"},
		"tablet": schematypes.StringEnum{
			Options: []string{"usb-tablet", "none"},
	Required: []string{"version"},

MachineSchema must be satisfied by config passed to NewMachine


func MigrateMachineDefinition

func MigrateMachineDefinition(definition interface{}) interface{}

MigrateMachineDefinition takes a machine definition and migrates it to the latest format version, and returns nil, if format is not supported.


type Image

type Image interface {
	DiskFile() string // Primary disk file to be used as boot disk.
	Format() string   // Image format 'qcow2', 'raw', etc.
	Machine() Machine // Machine configuration.
	Release()         // Free resources held by this image instance.

An Image provides an instance of a virtual machine image that a virtual machine can be started from.

func OverwriteMachine

func OverwriteMachine(image Image, machine Machine) Image

OverwriteMachine returns an image with a machine definition whose properties is overwritten by machine given here.

type LinuxBootOptions

type LinuxBootOptions struct {
	Kernel string // -kernel <bzImage>
	Append string // -append <cmdline>
	Initrd string // -initrd <file>

LinuxBootOptions holds optionals boot options for Linux. These are exclusively useful for building images and should not be used in production when running per-task VMs. But they can greatly simplify image building by facilitating injection of arguments for the Linux kernel.

type Machine

type Machine struct {
	// contains filtered or unexported fields

Machine specifies arguments for various QEMU options.

Machine objects can be combined using the WithDefaults() method which creates a new Machine from two Machine objects, merging the machine definitions. The empty Machine value specifies nothing and will be fully overwritten with defaults if used as target of WithDefaults(). Effectively, the empty Machine definition will assume whatever default values are given.

func NewMachine

func NewMachine(definition interface{}) Machine

NewMachine returns a new machine from definition matching MachineSchema

func (Machine) ApplyLimits

func (m Machine) ApplyLimits(limits MachineLimits) (Machine, error)

ApplyLimits returns an Machine with defaults extracted from the limits, or a MalformedPayloadError if limits were violated.

func (Machine) DeriveLimits

func (m Machine) DeriveLimits() MachineLimits

DeriveLimits constructs sane MachineLimits that permits the machine.

func (Machine) MarshalJSON

func (m Machine) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler

func (Machine) WithDefaults

func (m Machine) WithDefaults(defaults Machine) Machine

WithDefaults creates a new Machine with empty-values in c defaulting to defaults.

type MachineLimits

type MachineLimits struct {
	MaxMemory      int `json:"maxMemory"`
	MaxCPUs        int `json:"maxCPUs"`
	DefaultThreads int `json:"defaultThreads"`

MachineLimits imposes limits on a virtual machine definition.

type MutableImage

type MutableImage interface {
	Package(targetFile string) error // Package the as zstd compressed tar archive

A MutableImage is an instance of a virtual machine image similar to to Image, except that it can also be packaged into a compressed image tar archive as used for input by image manager.

type Network

type Network interface {
	NetDev(ID string) string         // Argument for the QEMU -netdev option
	SetHandler(handler http.Handler) // Set http.Handler for
	Release()                        // Release the network after use

A Network provides a -netdev argument for QEMU, isolation and an HTTP server that will handle requests for Ensuring that the requests orignates from the virtual machine wit hthe -netdev argument.

type VirtualMachine

type VirtualMachine struct {
	Done  <-chan struct{} // Closed when the virtual machine is done
	Error error           // Error, to be read after Done is closed
	// contains filtered or unexported fields

VirtualMachine holds the QEMU process and associated resources. This is useful as the VM remains alive in the ResultSet stage, as we use guest tools to copy files from the virtual machine.

func NewVirtualMachine

func NewVirtualMachine(
	limits MachineLimits,
	image Image, network Network, socketFolder, cdrom1, cdrom2 string,
	bootOptions LinuxBootOptions,
	monitor runtime.Monitor,
) (*VirtualMachine, error)

NewVirtualMachine constructs a new virtual machine using the given machineOptions, image, network and cdroms.

Returns engines.MalformedPayloadError if machineOptions and image definition are conflicting. If this returns an error, caller is responsible for releasing all resources, otherwise, they will be held by the VirtualMachine object.

func (*VirtualMachine) Kill

func (vm *VirtualMachine) Kill()

Kill the virtual machine, can only be called after Start()

func (*VirtualMachine) Screenshot

func (vm *VirtualMachine) Screenshot() (image.Image, error)

Screenshot takes a screenshot of the virtual machine screen as is running.

func (*VirtualMachine) SetHTTPHandler

func (vm *VirtualMachine) SetHTTPHandler(handler http.Handler)

SetHTTPHandler sets the HTTP handler for the meta-data service.

func (*VirtualMachine) Start

func (vm *VirtualMachine) Start()

Start the virtual machine.

func (*VirtualMachine) VNCSocket

func (vm *VirtualMachine) VNCSocket() string

VNCSocket returns the path to VNC socket, empty-string if closed.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to