vm

Documentation

Overview

Package vm provides virtual machine abstractions for QEMU.

Index

• Variables
• type Image
• type Machine
  • func LoadMachine(machineFile string) (*Machine, error)
  • func (m *Machine) Clone() *Machine
  • func (m Machine) Options() MachineOptions
  • func (m *Machine) SetDefaults(options MachineOptions) error
  • func (m *Machine) Validate() error
• type MachineOptions
• type MutableImage
• type Network
• type VirtualMachine
  • func NewVirtualMachine(machineOptions MachineOptions, image Image, network Network, ...) (*VirtualMachine, error)
  • func (vm *VirtualMachine) Kill()
  • func (vm *VirtualMachine) Screenshot() (image.Image, error)
  • func (vm *VirtualMachine) SetHTTPHandler(handler http.Handler)
  • func (vm *VirtualMachine) Start()
  • func (vm *VirtualMachine) VNCSocket() string

Variables

var MachineOptionsSchema = schematypes.Object{
	Title: "Machine Options",
	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,
		},
		"maxCores": schematypes.Integer{
			Title: "Max CPU Cores",
			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 'maxCores' number of
				cores in a single socket.
			`),
			Minimum: 1,
			Maximum: 255,
		},
	},
	Required: []string{
		"maxMemory",
		"maxCores",
	},
}

MachineOptionsSchema is the schema for MachineOptions.

Types

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.

type Machine

type Machine struct {
	UUID   string `json:"uuid"`
	Memory int    `json:"memory,omitempty"`
	CPU    struct {
		Threads int `json:"threads,omitempty"`
		Cores   int `json:"cores,omitempty"`
		Sockets int `json:"sockets,omitempty"`
	} `json:"cpu"`
	Network struct {
		Device string `json:"device"`
		MAC    string `json:"mac"`
	} `json:"network"`
	Keyboard struct {
		Layout string `json:"layout"`
	} `json:"keyboard"`
	Sound *struct {
		Device     string `json:"device"`
		Controller string `json:"controller"`
	} `json:"sound,omitempty"`
}

Machine specifies arguments for various QEMU options.

This only allows certain arguments to be specified.

func LoadMachine

func LoadMachine(machineFile string) (*Machine, error)

LoadMachine will load machine definition from file

func (*Machine) Clone

func (m *Machine) Clone() *Machine

Clone returns a copy of this machine definition

func (Machine) Options

func (m Machine) Options() MachineOptions

Options will return a set of MachineOptions that allows the current machine definition, and otherwise contains sane defaults. This is for utilities only.

func (*Machine) SetDefaults

func (m *Machine) SetDefaults(options MachineOptions) error

SetDefaults will validate limitations and set defaults from options

func (*Machine) Validate

func (m *Machine) Validate() error

Validate returns a MalformedPayloadError if the Machine definition isn't valid and legal.

type MachineOptions

type MachineOptions struct {
	MaxMemory int `json:"maxMemory"`
	MaxCores  int `json:"maxCores"`
}

MachineOptions specifies the limits on the virtual machine limits, default values and options.

type MutableImage

type MutableImage interface {
	Image
	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 169.254.169.254:80
	Release()                        // Release the network after use
}

A Network provides a -netdev argument for QEMU, isolation and an HTTP server that will handle requests for 169.254.169.254. 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(
	machineOptions MachineOptions,
	image Image, network Network, socketFolder, cdrom1, cdrom2 string,
	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.