hypervisor

package
v0.3.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 24, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	APISocketName   = "api.sock"
	ConsoleSockName = "console.sock"

	// CowSerial is the well-known virtio serial for the COW disk attached to OCI VMs.
	CowSerial = "cocoon-cow"

	// CreatingStateGCGrace bounds how long GC tolerates a "creating" VM.
	CreatingStateGCGrace = 24 * time.Hour

	// VMMemTransferTimeout is the single-shot timeout for snapshot/restore API calls.
	VMMemTransferTimeout = 10 * time.Minute

	// MinBalloonMemory is the minimum guest memory (256 MiB) below which
	// balloon is not enabled — the overhead is not worthwhile for tiny VMs.
	MinBalloonMemory = 256 << 20

	// DefaultBalloonDiv sizes the initial balloon as memory/DefaultBalloonDiv (25%).
	DefaultBalloonDiv = 4

	// GracefulStopPollInterval is how often we check if the guest has powered off
	// after sending a graceful shutdown signal (ACPI power-button or SendCtrlAltDel).
	GracefulStopPollInterval = 500 * time.Millisecond
)

Shared constants for all hypervisor backends.

Variables

View Source 
var (
	ErrNotFound   = errors.New("VM not found")
	ErrNotRunning = errors.New("VM not running")
	ErrAmbiguous  = errors.New("VM ref resolves to multiple backends")
)

Functions

func BlobHexFromPath added in v0.2.9 

func BlobHexFromPath(path string) string

e.g., "/var/lib/cocoon/oci/blobs/abc123.erofs" → "abc123"

func BuildIPParams added in v0.2.9 

func BuildIPParams(networkConfigs []*types.NetworkConfig, vmName string, dnsServers []string) string

func CleanSnapshotFiles added in v0.3.6 

func CleanSnapshotFiles(runDir string, match func(name string) bool) error

CleanSnapshotFiles removes snapshot-specific files from runDir.

func CleanupRuntimeFiles added in v0.2.9 

func CleanupRuntimeFiles(ctx context.Context, runDir string, files []string)

func CloneSnapshotFiles added in v0.3.6 

func CloneSnapshotFiles(dstDir, srcDir string, classify func(name string) SnapshotFileKind) error

CloneSnapshotFiles copies snapshot files using per-file strategies to minimize I/O.

func ConsoleSockPath added in v0.2.9 

func ConsoleSockPath(runDir string) string

func CopyFile added in v0.2.9 

func CopyFile(dst, src string) (err error)

func EnterNetns added in v0.2.9 

func EnterNetns(nsPath string) (restore func(), err error)

func ExpandRawImage added in v0.3.6 

func ExpandRawImage(path string, targetSize int64) error

ExpandRawImage truncates path up to targetSize. No-op if path is already at least targetSize. Used by both backends for raw COW expansion.

func ExtractBlobIDs added in v0.2.9 

func ExtractBlobIDs(storageConfigs []*types.StorageConfig, boot *types.BootConfig) map[string]struct{}

func InitCOWFilesystem added in v0.3.6 

func InitCOWFilesystem(ctx context.Context, path string) error

func MergeDirInto added in v0.3.1 

func MergeDirInto(src, dst string) error

MergeDirInto renames entries from src to dst, overwriting existing files.

func PrefixToNetmask added in v0.2.9 

func PrefixToNetmask(prefix int) string

func PrepareOCICOW added in v0.3.6 

func PrepareOCICOW(ctx context.Context, cowPath string, storage int64, storageConfigs []*types.StorageConfig) ([]*types.StorageConfig, error)

PrepareOCICOW creates an ext4-formatted sparse COW file at cowPath and returns storageConfigs with the new COW entry (CowSerial) appended. The returned slice must be used by the caller; append may reallocate.

func PrepareStagingDir added in v0.3.6 

func PrepareStagingDir(runDir string, snapshot io.Reader) (stagingDir string, cleanup func(), err error)

PrepareStagingDir creates a sibling staging directory, extracts the snapshot tar into it, and returns a cleanup function that removes the staging dir.

func RemoveVMDirs added in v0.2.9 

func RemoveVMDirs(runDir, logDir string) error

func SocketPath added in v0.2.9 

func SocketPath(runDir string) string

func ValidateHostCPU added in v0.3.1 

func ValidateHostCPU(cpu int) error

func VerifyBaseFiles added in v0.2.9 

func VerifyBaseFiles(storageConfigs []*types.StorageConfig, boot *types.BootConfig) error

func WaitForSocket added in v0.2.9 

func WaitForSocket(ctx context.Context, socketPath string, pid int, timeout time.Duration, processName string) error

Types

type Backend added in v0.2.9 

type Backend struct {
	Typ    string
	Conf   BackendConfig
	DB     storage.Store[VMIndex]
	Locker lock.Locker
}

Backend provides shared store operations for hypervisor backends.

func (*Backend) AbortLaunch added in v0.2.9 

func (b *Backend) AbortLaunch(ctx context.Context, pid int, sockPath, runDir string, runtimeFiles []string)

AbortLaunch terminates a failed launch and removes runtime files.

func (*Backend) BatchMarkStarted added in v0.2.9 

func (b *Backend) BatchMarkStarted(ctx context.Context, ids []string) error

func (*Backend) BuildGCModule added in v0.3.6 

func (b *Backend) BuildGCModule() gc.Module[VMGCSnapshot]

BuildGCModule builds GC module that scans DB and dirs for orphan VMs.

func (*Backend) BuildSnapshotConfig added in v0.3.6 

func (b *Backend) BuildSnapshotConfig(snapID string, rec *VMRecord) *types.SnapshotConfig

func (*Backend) CleanStalePlaceholders added in v0.2.9 

func (b *Backend) CleanStalePlaceholders(_ context.Context, ids []string) error

CleanStalePlaceholders removes "creating" records past GC grace period.

func (*Backend) CloneFromStream added in v0.3.6 

func (b *Backend) CloneFromStream(
	ctx context.Context, vmID string, vmCfg *types.VMConfig,
	networkConfigs []*types.NetworkConfig, snapshotConfig *types.SnapshotConfig, snapshot io.Reader,
	afterExtract func(ctx context.Context, vmID string, vmCfg *types.VMConfig, networkConfigs []*types.NetworkConfig, runDir, logDir string, now time.Time) (*types.VM, error),
) (_ *types.VM, err error)

CloneFromStream runs the shared streaming Clone sequence: reserve a placeholder via CloneSetup, extract the snapshot tar into runDir, then hand off to afterExtract for backend-specific startup.

func (*Backend) CloneSetup added in v0.3.1 

func (b *Backend) CloneSetup(ctx context.Context, vmID string, vmCfg *types.VMConfig, snapshotConfig *types.SnapshotConfig) (runDir, logDir string, now time.Time, cleanup func(), err error)

CloneSetup handles the shared pre-clone sequence used by both backends' Clone and DirectClone entry points: validate CPU, reserve a placeholder record, create dirs, and return a cleanup function.

func (*Backend) DirectCloneBase added in v0.3.6 

func (b *Backend) DirectCloneBase(
	ctx context.Context, vmID string, vmCfg *types.VMConfig,
	networkConfigs []*types.NetworkConfig, snapshotConfig *types.SnapshotConfig, srcDir string,
	cloneFiles func(dstDir, srcDir string) error,
	afterExtract func(ctx context.Context, vmID string, vmCfg *types.VMConfig, networkConfigs []*types.NetworkConfig, runDir, logDir string, now time.Time) (*types.VM, error),
) (_ *types.VM, err error)

DirectCloneBase runs the shared DirectClone sequence: reserve a placeholder via CloneSetup, copy snapshot files via cloneFiles, then hand off to afterExtract for backend-specific startup.

func (*Backend) FinalizeClone added in v0.3.6 

func (b *Backend) FinalizeClone(ctx context.Context, vmID string, info *types.VM, bootCfg *types.BootConfig, blobIDs map[string]struct{}) error

func (*Backend) FinalizeCreate added in v0.3.6 

func (b *Backend) FinalizeCreate(ctx context.Context, id string, info *types.VM, bootCfg *types.BootConfig, blobIDs map[string]struct{}) error

FinalizeCreate writes populated VM record to DB, replacing placeholder.

func (*Backend) FinalizeRestore added in v0.3.6 

func (b *Backend) FinalizeRestore(ctx context.Context, vmID string, vmCfg *types.VMConfig, rec *VMRecord, pid int) (*types.VM, error)

FinalizeRestore updates DB and assembles returned VM after restore.

func (*Backend) ForEachVM added in v0.2.9 

func (b *Backend) ForEachVM(ctx context.Context, ids []string, op string, fn func(context.Context, string) error) ([]string, error)

func (*Backend) GCCollect added in v0.2.9 

func (b *Backend) GCCollect(ctx context.Context, ids []string) error

GCCollect removes orphan VM directories and stale DB records. Kills leftover hypervisor processes before removing directories. Runs under the GC orchestrator's flock — uses lock-free DB access.

func (*Backend) GracefulStop added in v0.3.6 

func (b *Backend) GracefulStop(ctx context.Context, vmID string, pid int, timeout time.Duration, signal, escalate func() error) error

GracefulStop sends a shutdown signal, polls until the process exits, and escalates via the escalate closure if the timeout fires. Used by both CH (ACPI power-button) and FC (SendCtrlAltDel).

func (*Backend) HandleStopResult added in v0.3.6 

func (b *Backend) HandleStopResult(ctx context.Context, id, runDir string, runtimeFiles []string, shutdownErr error) error

func (*Backend) Inspect added in v0.2.9 

func (b *Backend) Inspect(ctx context.Context, ref string) (*types.VM, error)

Inspect returns VM info for a single VM by ref (ID, name, or prefix).

func (*Backend) KillForRestore added in v0.3.6 

func (b *Backend) KillForRestore(ctx context.Context, vmID string, rec *VMRecord, terminate func(pid int) error, runtimeFiles []string) error

KillForRestore stops a running VM and cleans up its runtime files in preparation for a restore. The terminate callback performs the backend-specific shutdown (e.g. CH graceful shutdown vs FC direct kill).

func (*Backend) List added in v0.2.9 

func (b *Backend) List(ctx context.Context) ([]*types.VM, error)

List returns VM info for all known VMs.

func (*Backend) LoadRecord added in v0.2.9 

func (b *Backend) LoadRecord(ctx context.Context, id string) (VMRecord, error)

func (*Backend) MarkError added in v0.2.9 

func (b *Backend) MarkError(ctx context.Context, id string)

func (*Backend) PIDFilePath added in v0.2.9 

func (b *Backend) PIDFilePath(runDir string) string

func (*Backend) PrepareStart added in v0.3.6 

func (b *Backend) PrepareStart(ctx context.Context, id string, runtimeFiles []string) (*VMRecord, error)

PrepareStart loads record, validates state, ensures dirs are ready.

func (*Backend) RecordSnapshot added in v0.3.6 

func (b *Backend) RecordSnapshot(ctx context.Context, vmID, tmpDir string) (snapID string, err error)

func (*Backend) RegisterGC added in v0.3.6 

func (b *Backend) RegisterGC(orch *gc.Orchestrator)

func (*Backend) ReserveVM added in v0.2.9 

func (b *Backend) ReserveVM(ctx context.Context, id string, vmCfg *types.VMConfig, blobIDs map[string]struct{}, runDir, logDir string) error

func (*Backend) ResolveForRestore added in v0.3.6 

func (b *Backend) ResolveForRestore(ctx context.Context, vmRef string) (string, *VMRecord, error)

ResolveForRestore resolves VM ref and validates it's running.

func (*Backend) ResolveRef added in v0.2.9 

func (b *Backend) ResolveRef(ctx context.Context, ref string) (string, error)

ResolveRef resolves a single ref (ID, name, or prefix) to an exact VM ID.

func (*Backend) ResolveRefs added in v0.2.9 

func (b *Backend) ResolveRefs(ctx context.Context, refs []string) ([]string, error)

ResolveRefs batch-resolves refs to exact VM IDs under a single lock.

func (*Backend) RollbackCreate added in v0.2.9 

func (b *Backend) RollbackCreate(ctx context.Context, id, name string)

RollbackCreate removes a placeholder VM record from the DB.

func (*Backend) ToVM added in v0.2.9 

func (b *Backend) ToVM(rec *VMRecord) *types.VM

func (*Backend) Type added in v0.2.9 

func (b *Backend) Type() string

func (*Backend) UpdateStates added in v0.2.9 

func (b *Backend) UpdateStates(ctx context.Context, ids []string, state types.VMState) error

func (*Backend) WatchPath added in v0.3.6 

func (b *Backend) WatchPath() string

WatchPath returns VM index file path for filesystem-based watching.

func (*Backend) WithRunningVM added in v0.2.9 

func (b *Backend) WithRunningVM(ctx context.Context, rec *VMRecord, fn func(pid int) error) error

WithRunningVM calls fn if rec still points to a live VM process.

type BackendConfig added in v0.2.9 

type BackendConfig interface {
	BinaryName() string
	PIDFileName() string
	TerminateGracePeriod() time.Duration
	EffectivePoolSize() int
	IndexFile() string
	RunDir() string
	LogDir() string
	VMRunDir(id string) string
	VMLogDir(id string) string
}

BackendConfig provides backend-specific values needed by shared Backend methods.

type BaseConfig added in v0.3.1 

type BaseConfig struct {
	*config.Config
	// contains filtered or unexported fields
}

BaseConfig holds the directory layout and timeout defaults shared by all hypervisor backends. Each backend embeds BaseConfig and adds backend-specific methods (BinaryName, PIDFileName, etc.).

func NewBaseConfig added in v0.3.1 

func NewBaseConfig(conf *config.Config, name string) BaseConfig

NewBaseConfig creates a BaseConfig for the named backend.

func (*BaseConfig) EnsureDirs added in v0.3.1 

func (c *BaseConfig) EnsureDirs() error

EnsureDirs creates all static directories required by the backend.

func (*BaseConfig) IndexFile added in v0.3.1 

func (c *BaseConfig) IndexFile() string

func (*BaseConfig) IndexLock added in v0.3.1 

func (c *BaseConfig) IndexLock() string

func (*BaseConfig) LogDir added in v0.3.1 

func (c *BaseConfig) LogDir() string

func (*BaseConfig) RunDir added in v0.3.1 

func (c *BaseConfig) RunDir() string

func (*BaseConfig) SocketWaitTimeout added in v0.3.1 

func (c *BaseConfig) SocketWaitTimeout() time.Duration

SocketWaitTimeout returns configured timeout or default (5s).

func (*BaseConfig) TerminateGracePeriod added in v0.3.1 

func (c *BaseConfig) TerminateGracePeriod() time.Duration

TerminateGracePeriod returns configured grace period or default (5s).

func (*BaseConfig) VMLogDir added in v0.3.1 

func (c *BaseConfig) VMLogDir(vmID string) string

func (*BaseConfig) VMRunDir added in v0.3.1 

func (c *BaseConfig) VMRunDir(vmID string) string

type Direct 

type Direct interface {
	DirectClone(ctx context.Context, vmID string, vmCfg *types.VMConfig, networkConfigs []*types.NetworkConfig, snapshotConfig *types.SnapshotConfig, srcDir string) (*types.VM, error)
	DirectRestore(ctx context.Context, vmRef string, vmCfg *types.VMConfig, srcDir string) (*types.VM, error)
}

Direct is an optional interface for hypervisors that support clone/restore from a local snapshot directory.

type Hypervisor 

type Hypervisor interface {
	Type() string

	Create(ctx context.Context, vmID string, vmCfg *types.VMConfig, storage []*types.StorageConfig, network []*types.NetworkConfig, boot *types.BootConfig) (*types.VM, error)
	Start(ctx context.Context, refs []string) ([]string, error)
	Stop(ctx context.Context, refs []string) ([]string, error)
	Inspect(ctx context.Context, ref string) (*types.VM, error)
	List(context.Context) ([]*types.VM, error)
	Delete(ctx context.Context, refs []string, force bool) ([]string, error)
	Console(ctx context.Context, ref string) (io.ReadWriteCloser, error)
	Snapshot(ctx context.Context, ref string) (*types.SnapshotConfig, io.ReadCloser, error)
	Clone(ctx context.Context, vmID string, vmCfg *types.VMConfig, networkConfigs []*types.NetworkConfig, snapshotConfig *types.SnapshotConfig, snapshot io.Reader) (*types.VM, error)
	Restore(ctx context.Context, vmRef string, vmCfg *types.VMConfig, snapshot io.Reader) (*types.VM, error)

	RegisterGC(*gc.Orchestrator)
}

Hypervisor manages VM lifecycle. Implemented by each backend.

type SnapshotFileKind added in v0.3.6 

type SnapshotFileKind int

SnapshotFileKind classifies a snapshot file for CloneSnapshotFiles. 

const (
	// SnapshotFileMemory is a read-only memory/state file (hard link or symlink).
	SnapshotFileMemory SnapshotFileKind = iota
	// SnapshotFileCOW is a writable disk that must be copied (reflink/sparse).
	SnapshotFileCOW
	// SnapshotFileMeta is small metadata that is plain-copied.
	SnapshotFileMeta
	// SnapshotFileSkip means the file should not be cloned.
	SnapshotFileSkip
)

type VMGCSnapshot added in v0.3.6 

type VMGCSnapshot struct {
	// contains filtered or unexported fields
}

VMGCSnapshot holds the data collected during the ReadDB phase of a hypervisor GC module. Both Cloud Hypervisor and Firecracker produce identical snapshots; the type lives here to avoid duplication.

func (VMGCSnapshot) ActiveVMIDs added in v0.3.6 

func (s VMGCSnapshot) ActiveVMIDs() map[string]struct{}

func (VMGCSnapshot) UsedBlobIDs added in v0.3.6 

func (s VMGCSnapshot) UsedBlobIDs() map[string]struct{}

type VMIndex 

type VMIndex struct {
	VMs   map[string]*VMRecord `json:"vms"`
	Names map[string]string    `json:"names"` // name → VM ID
}

VMIndex is the top-level DB structure for a hypervisor backend.

func (*VMIndex) Init 

func (idx *VMIndex) Init()

func (*VMIndex) Resolve 

func (idx *VMIndex) Resolve(ref string) (string, error)

func (*VMIndex) ResolveMany 

func (idx *VMIndex) ResolveMany(refs []string) ([]string, error)

type VMRecord 

type VMRecord struct {
	types.VM

	BootConfig   *types.BootConfig   `json:"boot_config,omitempty"`    // nil for UEFI boot (cloudimg)
	ImageBlobIDs map[string]struct{} `json:"image_blob_ids,omitempty"` // blob hex set for GC pinning

	// RunDir and LogDir store the absolute paths used when the VM was created.
	// Persisting them ensures cleanup succeeds even if --run-dir / --log-dir
	// differ from the values at creation time.
	RunDir string `json:"run_dir,omitempty"`
	LogDir string `json:"log_dir,omitempty"`
}

VMRecord is the persisted record for a single VM.

StorageConfigs and NetworkConfigs live on the embedded types.VM so that a value-copy (info := rec.VM) automatically includes them — no manual field copying needed. The JSON tags are on types.VM; do NOT duplicate them here or Go's encoding/json will silently shadow the promoted fields.

type Watchable added in v0.2.6 

type Watchable interface {
	WatchPath() string
}

Watchable is optionally implemented by hypervisors that support file-based state watching.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.