types

Documentation

Index

• type BootConfig
• type Config
• type Image
• type Network
• type NetworkConfig
• type Snapshot
• type SnapshotConfig
• type SnapshotExport
• type StorageConfig
• type VM
• type VMConfig
  • func (cfg *VMConfig) Validate() error
• type VMState

Types

type BootConfig

type BootConfig struct {
	// Direct-boot fields (OCI images).
	KernelPath string `json:"kernel_path,omitempty"`
	InitrdPath string `json:"initrd_path,omitempty"`
	// Cmdline is the kernel command line for direct-boot VMs.
	// Set at Create time from the storage layout (cocoon.layers=, cocoon.cow=, …).
	Cmdline string `json:"cmdline,omitempty"`

	// UEFI-boot field (cloud images).
	FirmwarePath string `json:"firmware_path,omitempty"`
}

BootConfig holds kernel and firmware paths used to boot a VM.

type Config

type Config struct {
	CPU           int    `json:"cpu,omitempty"`
	Memory        int64  `json:"memory,omitempty"`          // bytes
	Storage       int64  `json:"storage,omitempty"`         // COW disk size, bytes
	QueueSize     int    `json:"queue_size,omitempty"`      // virtio-net ring depth per queue; 0 = default
	DiskQueueSize int    `json:"disk_queue_size,omitempty"` // virtio-blk ring depth per device; 0 = default
	Image         string `json:"image,omitempty"`
	ImageDigest   string `json:"image_digest,omitempty"` // resolved image digest (e.g. "sha256:abc123")
	ImageType     string `json:"image_type,omitempty"`   // image backend type ("oci" or "cloudimg")
	Network       string `json:"network,omitempty"`      // CNI conflist name; empty = default
	NoDirectIO    bool   `json:"no_direct_io,omitempty"` // disable O_DIRECT on writable disks
	Windows       bool   `json:"windows,omitempty"`      // Windows guest: UEFI boot, kvm_hyperv=on, no cidata
}

Config holds the resource parameters shared between VMConfig and SnapshotConfig. Embedding it in both structs eliminates field duplication and allows value-copy transfer (e.g. BuildSnapshotConfig).

type Image

type Image struct {
	ID        string    `json:"id"`
	Name      string    `json:"name"`
	Type      string    `json:"type"`
	Size      int64     `json:"size"`
	CreatedAt time.Time `json:"created_at"`
}

Image represents metadata for a stored image entry.

type Network

type Network struct {
	IP      string `json:"ip,omitempty"`      // dotted decimal, e.g. "10.0.0.2"
	Gateway string `json:"gateway,omitempty"` // dotted decimal, e.g. "10.0.0.1"
	Prefix  int    `json:"prefix,omitempty"`  // CIDR prefix length, e.g. 24
}

Network holds guest-visible IP configuration for a NIC. All addresses are stored as human-readable strings for JSON clarity. All fields are omitempty — DHCP NICs have no static IP configuration.

type NetworkConfig

type NetworkConfig struct {
	Tap       string `json:"tap"`
	Mac       string `json:"mac"`
	NumQueues int    `json:"num_queues"` // Virtio queue count (= CPU * 2 for multi-queue).
	QueueSize int    `json:"queue_size"`

	// Backend identifies the network provider that created this NIC ("cni" or "bridge").
	// Used to select the correct provider during network recovery on VM start.
	// Empty means "cni" for backward compatibility with existing VM records.
	Backend string `json:"backend,omitempty"`

	// BridgeDev is the Linux bridge device name (e.g. "cni0", "br0").
	// Set only when Backend is "bridge"; required for recovery and GC.
	BridgeDev string `json:"bridge_dev,omitempty"`

	// NetnsPath is the network namespace path where the tap device lives.
	// Set by the network plugin at Config time; read by the hypervisor at Start time.
	// Empty when the network backend does not use network namespaces (e.g. macOS vmnet).
	NetnsPath string `json:"netns_path,omitempty"`

	// Guest-side IP configuration returned by the network plugin.
	// nil means DHCP / no static config.
	Network *Network `json:"network,omitempty"`
}

NetworkConfig describes a single NIC attached to a VM.

type Snapshot

type Snapshot struct {
	SnapshotConfig
	CreatedAt time.Time `json:"created_at"`
}

Snapshot is the public record for a snapshot.

type SnapshotConfig

type SnapshotConfig struct {
	Config

	ID           string              `json:"id,omitempty"` // generated by the hypervisor during Snapshot()
	Name         string              `json:"name"`
	Description  string              `json:"description,omitempty"`
	ImageBlobIDs map[string]struct{} `json:"image_blob_ids,omitempty"` // blob hex set for GC pinning
	Hypervisor   string              `json:"hypervisor,omitempty"`     // originating backend ("cloud-hypervisor" or "firecracker")
	NICs         int                 `json:"nics,omitempty"`
}

SnapshotConfig carries the parameters for creating a snapshot. The hypervisor fills ID, Image, ImageBlobIDs, Hypervisor, and resource fields; the CLI adds Name and Description.

type SnapshotExport

type SnapshotExport struct {
	Config  SnapshotConfig `json:"config"`
	Version int            `json:"version"`
}

SnapshotExport is the envelope written as snapshot.json inside an export archive.

type StorageConfig

type StorageConfig struct {
	Path   string `json:"path"`
	RO     bool   `json:"ro"`
	Serial string `json:"serial"`
}

StorageConfig describes a disk attached to a VM.

type VM

type VM struct {
	ID         string   `json:"id"`
	Hypervisor string   `json:"hypervisor,omitempty"`
	State      VMState  `json:"state"`
	Config     VMConfig `json:"config"`

	// Runtime — populated only while State == VMStateRunning.
	PID        int    `json:"pid"`
	SocketPath string `json:"socket_path,omitempty"` // CH API Unix socket

	// Attached resources — promoted into VMRecord via embedding.
	NetworkConfigs []*NetworkConfig `json:"network_configs,omitempty"`
	StorageConfigs []*StorageConfig `json:"storage_configs,omitempty"`

	// FirstBooted is true after the VM has been started at least once.
	// Used to skip cidata attachment on subsequent starts (cloudimg only).
	FirstBooted bool `json:"first_booted"`

	// SnapshotIDs tracks snapshots created from this VM.
	// Populated at runtime by toVM() from VMRecord.SnapshotIDs.
	SnapshotIDs map[string]struct{} `json:"snapshot_ids,omitempty"`

	// Timestamps.
	CreatedAt time.Time  `json:"created_at"`
	UpdatedAt time.Time  `json:"updated_at"`
	StartedAt *time.Time `json:"started_at,omitempty"`
	StoppedAt *time.Time `json:"stopped_at,omitempty"`
}

VM is the runtime record for a VM, persisted by the hypervisor backend.

type VMConfig

type VMConfig struct {
	Config
	Name string `json:"name"`

	OnDemand bool   `json:"-"` // use UFFD on-demand memory restore (CH only); transient, not persisted
	User     string `json:"-"`
	Password string `json:"-"`
}

VMConfig describes the resources requested for a new VM.

func (*VMConfig) Validate

func (cfg *VMConfig) Validate() error

Validate checks that VMConfig fields are within acceptable ranges.

type VMState

type VMState string

VMState represents the lifecycle state of a VM.

const (
	VMStateCreating VMState = "creating" // DB placeholder written, dirs/disks being prepared
	VMStateCreated  VMState = "created"  // registered, CH process not yet started
	VMStateRunning  VMState = "running"  // CH process alive, guest is up
	VMStateStopped  VMState = "stopped"  // CH process has exited cleanly
	VMStateError    VMState = "error"    // start or stop failed
)