types

Documentation

Index

• type BootConfig
• type Image
• type Network
• type NetworkConfig
• type Snapshot
• type SnapshotConfig
• 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"`
}

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"`
}

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

	// 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 {
	ID           string              `json:"id,omitempty"` // generated by the hypervisor during Snapshot()
	Name         string              `json:"name"`
	Description  string              `json:"description,omitempty"`
	Image        string              `json:"image,omitempty"`          // source image reference (e.g. "ubuntu:22.04")
	ImageBlobIDs map[string]struct{} `json:"image_blob_ids,omitempty"` // blob hex set for GC pinning

	// Original VM resource config, populated during snapshot creation.
	// Used by clone for parameter inheritance and validation.
	CPU     int   `json:"cpu,omitempty"`
	Memory  int64 `json:"memory,omitempty"`  // bytes
	Storage int64 `json:"storage,omitempty"` // bytes
	NICs    int   `json:"nics,omitempty"`
	Windows bool  `json:"windows,omitempty"`
}

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

type StorageConfig

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

type VM

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

	// Runtime — populated only while State == VMStateRunning.
	PID        int    `json:"pid,omitempty"`
	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 {
	Name    string `json:"name"`
	CPU     int    `json:"cpu"`
	Memory  int64  `json:"memory"`  // bytes
	Storage int64  `json:"storage"` // COW disk size, bytes
	Image   string `json:"image"`
	Network string `json:"network,omitempty"` // CNI conflist name; empty = default
	Windows bool   `json:"windows,omitempty"` // Windows guest: UEFI boot, kvm_hyperv=on, no cidata
}

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

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
)