cloudhypervisor

Documentation

Index

• Constants
• func CustomErrValidator(failureMapping map[int]string) requests.ResponseHandler
• func ToJSONForCode(code int, dest interface{}) requests.ResponseHandler
• type BalloonConfig
• type Client
  • func New(socketPath string) Client
• type ConsoleConfig
• type ConsoleMode
• type CpuAffinity
• type CpuFeatures
• type CpuTopology
• type CpusConfig
• type DeviceConfig
• type DeviceNode
• type DiskConfig
• type FsConfig
• type MemoryConfig
• type MemoryZoneConfig
• type NetConfig
• type NumaConfig
• type NumaDistance
• type PayloadConfig
• type PciDeviceInfo
• type PlatformConfig
• type PmemConfig
• type RateLimiterConfig
• type ReceiveMigrationData
• type RestoreConfig
• type RngConfig
• type SendMigrationData
• type SgxEpcConfig
• type TdxConfig
• type TokenBucket
• type VMCoreDumpData
• type VdpaConfig
• type VmAddDevice
• type VmConfig
• type VmCounters
• type VmInfo
• type VmRemoveDevice
• type VmResize
• type VmResizeZone
• type VmSnapshotConfig
• type VmState
• type VmmPingResponse
• type VsockConfig

Constants

const (
	DefaultServerEndpoint = "http://localhost/api/v1/"

	PathVmmPing     = "vmm.ping"
	PathVmmShutdown = "vmm.shutdown"

	PathVmInfo           = "vm.info"
	PathVmCounters       = "vm.counters"
	PathVmCreate         = "vm.create"
	PathVmDelete         = "vm.delete"
	PathVmBoot           = "vm.boot"
	PathVmPause          = "vm.pause"
	PathVmResume         = "vm.resume"
	PathVmShutdown       = "vm.shutdown"
	PathVmReboot         = "vm.reboot"
	PathVmPowerButton    = "vm.power-button"
	PathVmResize         = "vm.resize"
	PathVmResizeZone     = "vm.resize-zone"
	PathVmAddDevice      = "vm.add-device"
	PathVmRemoveDevice   = "vm.remove-device"
	PathVmAddDisk        = "vm.add-disk"
	PathVmAddFs          = "vm.add-fs"
	PathVmAddPmem        = "vm.add-pmem"
	PathAddNetworkDevice = "vm.add-net"
	PathAddVsockDevice   = "vm.add-vsock"
	PathAddVdpaDevice    = "vm.add-vdpa"
	PathCoreDumpCreate   = "vm.coredump"
	PathSnapshotCreate   = "vm.snapshot"
	PathSnapshotRestore  = "vm.restore"
	PathMigrationReceive = "vm.receive-migration"
	PathMigrationSend    = "vm.send-migration"
)

Functions

func CustomErrValidator

func CustomErrValidator(failureMapping map[int]string) requests.ResponseHandler

CustomErrValidator is a custom response handler that will set a custom error message based on the status code.

func ToJSONForCode

func ToJSONForCode(code int, dest interface{}) requests.ResponseHandler

ToJSONForCode is a custom response handler that will unmarshal the http response body into the specific struct if the status code matches. Otherwise the destination is set to nil.

Types

type BalloonConfig

type BalloonConfig struct {
	Size              int64 `json:"size"`
	DeflateOnOom      *bool `json:"deflate_on_oom,omitempty"`
	FreePageReporting *bool `json:"free_page_reporting,omitempty"`
}

BalloonConfig holds the configuration for the balloon device.

type Client

type Client interface {
	// VmmPing checks for API server availability.
	VmmPing(ctx context.Context) (*VmmPingResponse, error)
	// VmmShutdown shuts down the cloud-hypervisor vmm.
	VmmShutdown(ctx context.Context) error
	// Info returns general information about the cloud-hypervisor Virtual Machine (VM) instance.
	Info(ctx context.Context) (*VmInfo, error)
	// Counters gets the counters from the VM.
	Counters(ctx context.Context) (*VmCounters, error)
	// Create will create the cloud-hypervisor Virtual Machine (VM) instance. The instance is not booted, only created.
	Create(ctx context.Context, config *VmConfig) error
	// Delete will delete the cloud-hypervisor Virtual Machine (VM) instance.
	Delete(ctx context.Context) error
	// Boot will boot the previously created VM instance.
	Boot(ctx context.Context) error
	// Pause a previously booted VM instance.
	Pause(ctx context.Context) error
	// Resume a previously paused VM instance.
	Resume(ctx context.Context) error
	// Shutdown the VM instance.
	Shutdown(ctx context.Context) error
	// Reboot the VM instance.
	Reboot(ctx context.Context) error
	// PowerButton simulates pressing the equivalent of a physical power button.
	PowerButton(ctx context.Context) error
	// Resize will change the vpcus/ram/balloon (a.k.a resize).
	Resize(ctx context.Context, config *VmResize) error
	// ResizeZone will resize a memory zone.
	ResizeZone(ctx context.Context, config *VmResizeZone) error
	// AddDevice is used to add a new device to the VM.
	AddDevice(ctx context.Context, config *VmAddDevice) (*PciDeviceInfo, error)
	// RemoveDevice is used to remove a device from the VM.
	RemoveDevice(ctx context.Context, config *VmRemoveDevice) error
	// AddDisk will add a new disk to the VM.
	AddDisk(ctx context.Context, config *DiskConfig) (*PciDeviceInfo, error)
	// AddFs will add a new virtio-fs device to the VM.
	AddFs(ctx context.Context, config *FsConfig) (*PciDeviceInfo, error)
	// AddPmemDevice will add a new pmem device to the VM.
	AddPmemDevice(ctx context.Context, config *PmemConfig) (*PciDeviceInfo, error)
	// AddNetworkDevice will add a new network device to the VM.
	AddNetworkDevice(ctx context.Context, config *NetConfig) (*PciDeviceInfo, error)
	// AddVsockDevice will add a new vsock device to the VM.
	AddVsockDevice(ctx context.Context, config *VsockConfig) (*PciDeviceInfo, error)
	// AddVdpaDevice will add a new vdpa device to the VM.
	AddVdpaDevice(ctx context.Context, config *VdpaConfig) (*PciDeviceInfo, error)
	// Snapshot will create a snapshot of the VM.
	Snapshot(ctx context.Context, config *VmSnapshotConfig) error
	// CoreDump will take a core dump of the VM.
	CoreDump(ctx context.Context, config *VMCoreDumpData) error
	// Restore will restore a VM from a snapshot.
	Restore(ctx context.Context, config *RestoreConfig) error
	// ReceiveMigration will receive a VM migration from a URL.
	ReceiveMigration(ctx context.Context, config *ReceiveMigrationData) error
	// SendMigration will send a VM migration to a URL.
	SendMigration(ctx context.Context, config *SendMigrationData) error
}

Client represents a client for the Cloud Hypervisor API.

func New

func New(socketPath string) Client

New will create a new cloud hypervisor client.

type ConsoleConfig

type ConsoleConfig struct {
	File  *string     `json:"file,omitempty"`
	Mode  ConsoleMode `json:"mode"`
	Iommu *bool       `json:"iommu,omitempty"`
}

ConsoleConfig represents the configuration for the console.

type ConsoleMode

type ConsoleMode string

ConsoleMode is type to represent the mode of the console device.

var (
	ConsoleModeOff  ConsoleMode = "Off"
	ConsoleModePty  ConsoleMode = "Pty"
	ConsoleModeTty  ConsoleMode = "Tty"
	ConsoleModeFile ConsoleMode = "File"
	ConsoleModeNull ConsoleMode = "Null"
)

type CpuAffinity

type CpuAffinity struct {
	Vcpu     *int32  `json:"vcpu,omitempty"`
	HostCpus []int32 `json:"host_cpus,omitempty"`
}

CpuAffinity is used to specify CPU affinity.

type CpuFeatures

type CpuFeatures struct {
	Amx *bool `json:"amx,omitempty"`
}

CpuFeatures is used to enable / disable CPU features.

type CpuTopology

type CpuTopology struct {
	ThreadsPerCore *int32 `json:"threads_per_core,omitempty"`
	CoresPerDie    *int32 `json:"cores_per_die,omitempty"`
	DiesPerPackage *int32 `json:"dies_per_package,omitempty"`
	Packages       *int32 `json:"packages,omitempty"`
}

CpuTopology is configuration for the SPU topology.

type CpusConfig

type CpusConfig struct {
	BootVcpus   int32         `json:"boot_vcpus"`
	MaxVcpus    int32         `json:"max_vcpus"`
	KvmHyperv   *bool         `json:"kvm_hyperv,omitempty"`
	Topology    *CpuTopology  `json:"topology,omitempty"`
	MaxPhysBits *int32        `json:"max_phys_bits,omitempty"`
	Affinity    []CpuAffinity `json:"affinity,omitempty"`
	Features    *CpuFeatures  `json:"features,omitempty"`
}

CpusConfig represents the configuration for CPUs attached to a VM.

type DeviceConfig

type DeviceConfig struct {
	Path       string  `json:"path"`
	Iommu      *bool   `json:"iommu,omitempty"`
	PciSegment *int32  `json:"pci_segment,omitempty"`
	Id         *string `json:"id,omitempty"`
}

DeviceConfig represents configuration for a device attached to a VM.

type DeviceNode

type DeviceNode struct {
	Id        *string                  `json:"id,omitempty"`
	Resources []map[string]interface{} `json:"resources,omitempty"`
	Children  []string                 `json:"children,omitempty"`
	PciBdf    *string                  `json:"pci_bdf,omitempty"`
}

DeviceNode represents a device attached to a VM.

type DiskConfig

type DiskConfig struct {
	Path              string             `json:"path"`
	Readonly          *bool              `json:"readonly,omitempty"`
	Direct            *bool              `json:"direct,omitempty"`
	Iommu             *bool              `json:"iommu,omitempty"`
	NumQueues         *int32             `json:"num_queues,omitempty"`
	QueueSize         *int32             `json:"queue_size,omitempty"`
	VhostUser         *bool              `json:"vhost_user,omitempty"`
	VhostSocket       *string            `json:"vhost_socket,omitempty"`
	RateLimiterConfig *RateLimiterConfig `json:"rate_limiter_config,omitempty"`
	PciSegment        *int32             `json:"pci_segment,omitempty"`
	Id                *string            `json:"id,omitempty"`
}

DiskConfig represents the configuration for a disk attached to a VM.

type FsConfig

type FsConfig struct {
	Tag        string  `json:"tag"`
	Socket     string  `json:"socket"`
	NumQueues  int32   `json:"num_queues"`
	QueueSize  int32   `json:"queue_size"`
	PciSegment *int32  `json:"pci_segment,omitempty"`
	Id         *string `json:"id,omitempty"`
}

FsConfig represents the configuration for a virtio-fs device.

type MemoryConfig

type MemoryConfig struct {
	Size           int64              `json:"size"`
	HotplugSize    *int64             `json:"hotplug_size,omitempty"`
	HotpluggedSize *int64             `json:"hotplugged_size,omitempty"`
	Mergeable      *bool              `json:"mergeable,omitempty"`
	HotplugMethod  *string            `json:"hotplug_method,omitempty"`
	Shared         *bool              `json:"shared,omitempty"`
	Hugepages      *bool              `json:"hugepages,omitempty"`
	HugepageSize   *int64             `json:"hugepage_size,omitempty"`
	Prefault       *bool              `json:"prefault,omitempty"`
	Zones          []MemoryZoneConfig `json:"zones,omitempty"`
}

MemoryConfig represents the memory configuration for a VM.

type MemoryZoneConfig

type MemoryZoneConfig struct {
	Id             string  `json:"id"`
	Size           int64   `json:"size"`
	File           *string `json:"file,omitempty"`
	Mergeable      *bool   `json:"mergeable,omitempty"`
	Shared         *bool   `json:"shared,omitempty"`
	Hugepages      *bool   `json:"hugepages,omitempty"`
	HugepageSize   *int64  `json:"hugepage_size,omitempty"`
	HostNumaNode   *int32  `json:"host_numa_node,omitempty"`
	HotplugSize    *int64  `json:"hotplug_size,omitempty"`
	HotpluggedSize *int64  `json:"hotplugged_size,omitempty"`
	Prefault       *bool   `json:"prefault,omitempty"`
}

MemoryZoneConfig represents the NUMA memory zone configuration.

type NetConfig

type NetConfig struct {
	Tap               *string            `json:"tap,omitempty"`
	Ip                *string            `json:"ip,omitempty"`
	Mask              *string            `json:"mask,omitempty"`
	Mac               *string            `json:"mac,omitempty"`
	Iommu             *bool              `json:"iommu,omitempty"`
	NumQueues         *int32             `json:"num_queues,omitempty"`
	QueueSize         *int32             `json:"queue_size,omitempty"`
	VhostUser         *bool              `json:"vhost_user,omitempty"`
	VhostSocket       *string            `json:"vhost_socket,omitempty"`
	VhostMode         *string            `json:"vhost_mode,omitempty"`
	Id                *string            `json:"id,omitempty"`
	PciSegment        *int32             `json:"pci_segment,omitempty"`
	RateLimiterConfig *RateLimiterConfig `json:"rate_limiter_config,omitempty"`
}

NetConfig is the configuration for a network interface.

type NumaConfig

type NumaConfig struct {
	GuestNumaId    int32          `json:"guest_numa_id"`
	Cpus           []int32        `json:"cpus,omitempty"`
	Distances      []NumaDistance `json:"distances,omitempty"`
	MemoryZones    []string       `json:"memory_zones,omitempty"`
	SgxEpcSections []string       `json:"sgx_epc_sections,omitempty"`
}

NumaConfig is the NUMA configuration for a VM.

type NumaDistance

type NumaDistance struct {
	Destination int32 `json:"destination"`
	Distance    int32 `json:"distance"`
}

NumaDistance represents the NUMA distance.

type PayloadConfig

type PayloadConfig struct {
	Kernel    string `json:"kernel"`
	CmdLine   string `json:"cmdline,omitempty"`
	InitRamFs string `json:"initramfs,omitempty"`
}

PayloadConfig is the configuration to boot the guest.

type PciDeviceInfo

type PciDeviceInfo struct {
	Id  string `json:"id"`
	Bdf string `json:"bdf"`
}

PciDeviceInfo represents information about a PCI device.

type PlatformConfig

type PlatformConfig struct {
	NumPciSegments *int32   `json:"num_pci_segments,omitempty"`
	IommuSegments  []int32  `json:"iommu_segments,omitempty"`
	SerialNumber   string   `json:"serial_number,omitempty"`
	UUID           string   `json:"uuid,omitempty"`
	OEMStrings     []string `json:"oem_strings,omitempty"`
}

PlatformConfig contains information about the platform.

type PmemConfig

type PmemConfig struct {
	File          string  `json:"file"`
	Size          *int64  `json:"size,omitempty"`
	Iommu         *bool   `json:"iommu,omitempty"`
	DiscardWrites *bool   `json:"discard_writes,omitempty"`
	PciSegment    *int32  `json:"pci_segment,omitempty"`
	Id            *string `json:"id,omitempty"`
}

PmemConfig represents the configuration for a PMEM device.

type RateLimiterConfig

type RateLimiterConfig struct {
	Bandwidth *TokenBucket `json:"bandwidth,omitempty"`
	Ops       *TokenBucket `json:"ops,omitempty"`
}

RateLimiterConfig defines an IO rate limiter with independent bytes/s and ops/s limits. Limits are defined by configuring each of the _bandwidth_ and _ops_ token buckets.

type ReceiveMigrationData

type ReceiveMigrationData struct {
	ReceiverUrl string `json:"receiver_url"`
}

ReceiveMigrationData is the configuration for receiving a VM migration.

type RestoreConfig

type RestoreConfig struct {
	SourceUrl string `json:"source_url"`
	Prefault  *bool  `json:"prefault,omitempty"`
}

RestoreConfig is the configuration for restoring a VM snapshot.

type RngConfig

type RngConfig struct {
	Src   string `json:"src"`
	Iommu *bool  `json:"iommu,omitempty"`
}

RngConfig is the configuration for the random number device.

type SendMigrationData

type SendMigrationData struct {
	DestinationUrl string `json:"destination_url"`
	Local          *bool  `json:"local,omitempty"`
}

SendMigrationData is the configuration for migrating a VM to another host.

type SgxEpcConfig

type SgxEpcConfig struct {
	Id       string `json:"id"`
	Size     int64  `json:"size"`
	Prefault *bool  `json:"prefault,omitempty"`
}

SgxEpcConfig is the SGX configuration.

type TdxConfig

type TdxConfig struct {
	Firmware string `json:"firmware"`
}

TdxConfig is the TDX configuration.

type TokenBucket

type TokenBucket struct {
	Size         int64  `json:"size"`
	OneTimeBurst *int64 `json:"one_time_burst,omitempty"`
	RefillTime   int64  `json:"refill_time"`
}

TokenBucket defines a token bucket with a maximum capacity (_size_), an initial burst size (_one_time_burst_) and an interval for refilling purposes (_refill_time_). The refill-rate is derived from _size_ and _refill_time_, and it is the constant rate at which the tokens replenish. The refill process only starts happening after the initial burst budget is consumed. Consumption from the token bucket is unbounded in speed which allows for bursts bound in size by the amount of tokens available. Once the token bucket is empty, consumption speed is bound by the refill-rate.

type VMCoreDumpData

type VMCoreDumpData struct {
	DestinationURL string `json:"destination_url"`
}

VMCoreDumpData is the configuration for a core dump.

type VdpaConfig

type VdpaConfig struct {
	Path       string  `json:"path"`
	NumQueues  int32   `json:"num_queues"`
	Iommu      *bool   `json:"iommu,omitempty"`
	PciSegment *int32  `json:"pci_segment,omitempty"`
	Id         *string `json:"id,omitempty"`
}

VdpaConfig represents the details of a vDPA device.

type VmAddDevice

type VmAddDevice struct {
	Path  *string `json:"path,omitempty"`
	Iommu *bool   `json:"iommu,omitempty"`
	Id    *string `json:"id,omitempty"`
}

VmAddDevice represents the configuration for adding a new device to a VM.

type VmConfig

type VmConfig struct {
	Cpus     *CpusConfig     `json:"cpus,omitempty"`
	Memory   *MemoryConfig   `json:"memory,omitempty"`
	Payload  PayloadConfig   `json:"payload"`
	Disks    []DiskConfig    `json:"disks,omitempty"`
	Net      []NetConfig     `json:"net,omitempty"`
	Rng      *RngConfig      `json:"rng,omitempty"`
	Balloon  *BalloonConfig  `json:"balloon,omitempty"`
	Fs       []FsConfig      `json:"fs,omitempty"`
	Pmem     []PmemConfig    `json:"pmem,omitempty"`
	Serial   *ConsoleConfig  `json:"serial,omitempty"`
	Console  *ConsoleConfig  `json:"console,omitempty"`
	Devices  []DeviceConfig  `json:"devices,omitempty"`
	Vdpa     []VdpaConfig    `json:"vdpa,omitempty"`
	Vsock    *VsockConfig    `json:"vsock,omitempty"`
	SgxEpc   []SgxEpcConfig  `json:"sgx_epc,omitempty"`
	Tdx      *TdxConfig      `json:"tdx,omitempty"`
	Numa     []NumaConfig    `json:"numa,omitempty"`
	Iommu    *bool           `json:"iommu,omitempty"`
	Watchdog *bool           `json:"watchdog,omitempty"`
	Platform *PlatformConfig `json:"platform,omitempty"`
}

VmConfig is the configuration for a VM.

type VmCounters

type VmCounters map[string]map[string]int64

VmCounters is the perf counters exposed from the VM.

type VmInfo

type VmInfo struct {
	Config           VmConfig               `json:"config"`
	State            VmState                `json:"state"`
	MemoryActualSize *int64                 `json:"memory_actual_size,omitempty"`
	DeviceTree       *map[string]DeviceNode `json:"device_tree,omitempty"`
}

VmInfo represents information about the VM.

type VmRemoveDevice

type VmRemoveDevice struct {
	Id *string `json:"id,omitempty"`
}

VmRemoveDevice represents the configuration for removing a device from a VM.

type VmResize

type VmResize struct {
	DesiredVcpus   *int32 `json:"desired_vcpus,omitempty"`
	DesiredRam     *int64 `json:"desired_ram,omitempty"`
	DesiredBalloon *int64 `json:"desired_balloon,omitempty"`
}

VmResize is the target size for the VM.

type VmResizeZone

type VmResizeZone struct {
	Id         *string `json:"id,omitempty"`
	DesiredRam *int64  `json:"desired_ram,omitempty"`
}

VmResizeZone is the target size for a NUMA memory zone.

type VmSnapshotConfig

type VmSnapshotConfig struct {
	DestinationUrl *string `json:"destination_url,omitempty"`
}

VmSnapshotConfig is the configuration for taking a VM snapshot.

type VmState

type VmState string

VmState is type to represent the state of a VM.

var (
	// VmStateCreated is a state where the the VM is created.
	VmStateCreated VmState = "Created"
	// VmStateRunning is a state where the the VM is running.
	VmStateRunning VmState = "Running"
	// VmStateShutdown is a state where the the VM is shutdown.
	VmStateShutdown VmState = "Shutdown"
	// VmStatePaused is a state where the the VM is paused.
	VmStatePaused VmState = "Paused"
	// VmStateBreakPoint is a state where the the VM is stopped at a breakpoint.
	VmStateBreakPoint VmState = "BreakPoint"
)

type VmmPingResponse

type VmmPingResponse struct {
	Version string `json:"version"`
}

VmmPingResponse is the details of the VMM

type VsockConfig

type VsockConfig struct {
	Cid        int64   `json:"cid"`
	Socket     string  `json:"socket"`
	Iommu      *bool   `json:"iommu,omitempty"`
	PciSegment *int32  `json:"pci_segment,omitempty"`
	Id         *string `json:"id,omitempty"`
}

VsockConfig represents the configuration for a vSock device.