types

Documentation

Index

• func ValidDataDiskName(s string) bool
• func ValidateStorageConfigs(configs []*StorageConfig) error
• type BootConfig
• type Config
• type DataDiskSpec
• type Image
• type Network
• type NetworkConfig
• type Snapshot
• type SnapshotConfig
• type SnapshotExport
• type StorageConfig
• type StorageRole
• type VM
• type VMConfig
  • func (cfg *VMConfig) Validate() error
• type VMState

Functions

func ValidDataDiskName

func ValidDataDiskName(s string) bool

ValidDataDiskName reports whether s is a legal data disk name. Shared between CLI parsing and sidecar loading (sidecar may be untrusted).

func ValidateStorageConfigs

func ValidateStorageConfigs(configs []*StorageConfig) error

ValidateStorageConfigs enforces invariants at every boundary that loads or finalizes StorageConfigs (FinalizeCreate, Start, Snapshot, Clone/Restore after sidecar load).

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
	// SharedMemory toggles CH memory shared=on, the prerequisite for
	// vhost-user-fs hot-plug. Decided at VM creation: the memory model is
	// fixed for the VM's lifetime and propagates through clone/restore via
	// the persisted config and the snapshot-time CH config.json.
	SharedMemory bool `json:"shared_memory,omitempty"`
}

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 DataDiskSpec

type DataDiskSpec struct {
	Name          string
	Size          int64
	FSType        string
	MountPoint    string
	MountPointSet bool `json:"-"` // distinguishes mount=<empty> (set) from omitted
	DirectIO      *bool
}

DataDiskSpec is the user-facing description of an extra data disk parsed from --data-disk. Transient — never persisted.

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 is the provider type ("cni" or "bridge"); empty means "cni" for
	// backward compat with pre-bridge VM records.
	Backend string `json:"backend,omitempty"`

	// BridgeDev is the Linux bridge device name; set only when Backend=="bridge".
	BridgeDev string `json:"bridge_dev,omitempty"`

	// NetnsPath is the netns where the TAP lives; empty for backends without netns (e.g. macOS vmnet).
	NetnsPath string `json:"netns_path,omitempty"`

	// Network is the guest-visible IP config; nil means DHCP.
	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"`
	Role       StorageRole `json:"role"`
	MountPoint string      `json:"mount_point,omitempty"` // Role==Data only
	FSType     string      `json:"fstype,omitempty"`      // Role==Data only
	DirectIO   *bool       `json:"direct_io,omitempty"`   // Role==Data only; nil inherits VM-level NoDirectIO
}

StorageConfig describes a disk attached to a VM.

type StorageRole

type StorageRole string

StorageRole classifies a disk's purpose in the VM. Required on every StorageConfig — empty values are rejected by ValidateStorageConfigs.

const (
	StorageRoleLayer  StorageRole = "layer"
	StorageRoleCOW    StorageRole = "cow"
	StorageRoleCidata StorageRole = "cidata"
	StorageRoleData   StorageRole = "data"

	// Phase 1 fstype values for Role==Data disks.
	FSTypeExt4 = "ext4"
	FSTypeNone = "none"
)

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
	VsockSocket string `json:"vsock_socket,omitempty"` // hybrid vsock UDS for cocoon-agent

	// 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:"-"`
	DataDisks []DataDiskSpec `json:"-"` // populated from --data-disk; consumed by Create
}

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
)