cloudhypervisor

Documentation

Index

• Constants
• func DebugDiskCLIArgs(storageConfigs []*types.StorageConfig, cpuCount int) []string
• func ReverseLayerSerials(storageConfigs []*types.StorageConfig) []string
• type CloudHypervisor
  • func New(conf *config.Config) (*CloudHypervisor, error)
  • func (ch *CloudHypervisor) Clone(ctx context.Context, vmID string, vmCfg *types.VMConfig, ...) (_ *types.VM, err error)
  • func (ch *CloudHypervisor) Console(ctx context.Context, ref string) (io.ReadWriteCloser, error)
  • func (ch *CloudHypervisor) Create(ctx context.Context, id string, vmCfg *types.VMConfig, ...) (_ *types.VM, err error)
  • func (ch *CloudHypervisor) Delete(ctx context.Context, refs []string, force bool) ([]string, error)
  • func (ch *CloudHypervisor) DirectClone(ctx context.Context, vmID string, vmCfg *types.VMConfig, ...) (_ *types.VM, err error)
  • func (ch *CloudHypervisor) DirectRestore(ctx context.Context, vmRef string, vmCfg *types.VMConfig, srcDir string) (*types.VM, error)
  • func (ch *CloudHypervisor) GCModule() gc.Module[chSnapshot]
  • func (ch *CloudHypervisor) Inspect(ctx context.Context, ref string) (*types.VM, error)
  • func (ch *CloudHypervisor) List(ctx context.Context) ([]*types.VM, error)
  • func (ch *CloudHypervisor) RegisterGC(orch *gc.Orchestrator)
  • func (ch *CloudHypervisor) Restore(ctx context.Context, vmRef string, vmCfg *types.VMConfig, snapshot io.Reader) (*types.VM, error)
  • func (ch *CloudHypervisor) Snapshot(ctx context.Context, ref string) (*types.SnapshotConfig, io.ReadCloser, error)
  • func (ch *CloudHypervisor) Start(ctx context.Context, refs []string) ([]string, error)
  • func (ch *CloudHypervisor) Stop(ctx context.Context, refs []string) ([]string, error)
  • func (ch *CloudHypervisor) Type() string
• type Config
  • func (c *Config) COWRawPath(vmID string) string
  • func (c *Config) CidataPath(vmID string) string
  • func (c *Config) EnsureDirs() error
  • func (c *Config) IndexFile() string
  • func (c *Config) IndexLock() string
  • func (c *Config) LogDir() string
  • func (c *Config) OverlayPath(vmID string) string
  • func (c *Config) RunDir() string
  • func (c *Config) SocketWaitTimeout() time.Duration
  • func (c *Config) TerminateGracePeriod() time.Duration
  • func (c *Config) VMLogDir(vmID string) string
  • func (c *Config) VMRunDir(vmID string) string

Constants

const CowSerial = "cocoon-cow"

CowSerial is the well-known virtio serial for the COW disk attached to OCI VMs.

Functions

func DebugDiskCLIArgs

func DebugDiskCLIArgs(storageConfigs []*types.StorageConfig, cpuCount int) []string

DebugDiskCLIArgs returns user-facing CH disk CLI args using the same storage-to-disk mapping as the runtime launch path.

func ReverseLayerSerials

func ReverseLayerSerials(storageConfigs []*types.StorageConfig) []string

ReverseLayerSerials extracts read-only layer serial names from StorageConfigs and returns them in reverse order (top layer first for overlayfs lowerdir).

Types

type CloudHypervisor

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

CloudHypervisor implements hypervisor.Hypervisor.

func New

func New(conf *config.Config) (*CloudHypervisor, error)

New creates a CloudHypervisor backend.

func (*CloudHypervisor) Clone

func (ch *CloudHypervisor) Clone(ctx context.Context, vmID string, vmCfg *types.VMConfig, networkConfigs []*types.NetworkConfig, snapshotConfig *types.SnapshotConfig, snapshot io.Reader) (_ *types.VM, err error)

Clone creates a new VM from a snapshot tar stream via vm.restore. Three phases: placeholder record → extract+prepare → launch+finalize.

func (*CloudHypervisor) Console

func (ch *CloudHypervisor) Console(ctx context.Context, ref string) (io.ReadWriteCloser, error)

Console connects to the VM's console output and returns a bidirectional stream.

For UEFI-boot VMs (cloudimg): connects to the serial socket (console.sock). For direct-boot VMs (OCI): opens the virtio-console PTY allocated by CH.

The console path is resolved lazily on first access via the CH API (OCI/PTY) or the deterministic socket path (UEFI), so callers like Clone and Start don't need to query it upfront. The caller is responsible for closing the returned ReadWriteCloser.

func (*CloudHypervisor) Create

func (ch *CloudHypervisor) Create(ctx context.Context, id string, vmCfg *types.VMConfig, storageConfigs []*types.StorageConfig, networkConfigs []*types.NetworkConfig, bootCfg *types.BootConfig) (_ *types.VM, err error)

Create registers a new VM, prepares the COW disk, and persists the record. The VM is left in Created state — call Start to launch it.

To avoid a race with GC (which scans directories and removes those not in the DB), we write a placeholder record first, then create directories and prepare disks, and finally update the record to Created state.

func (*CloudHypervisor) Delete

func (ch *CloudHypervisor) Delete(ctx context.Context, refs []string, force bool) ([]string, error)

Delete removes VMs. Running VMs require force=true (stops them first).

func (*CloudHypervisor) DirectClone

func (ch *CloudHypervisor) DirectClone(ctx context.Context, vmID string, vmCfg *types.VMConfig, networkConfigs []*types.NetworkConfig, snapshotConfig *types.SnapshotConfig, srcDir string) (_ *types.VM, err error)

DirectClone creates a new VM from a local snapshot directory. Files are handled per-type: hardlink for memory-range-*, reflink/copy for the COW disk, plain copy for small metadata, and cidata is regenerated.

func (*CloudHypervisor) DirectRestore

func (ch *CloudHypervisor) DirectRestore(ctx context.Context, vmRef string, vmCfg *types.VMConfig, srcDir string) (*types.VM, error)

DirectRestore reverts a running VM using a local snapshot directory. Files are handled per-type: hardlink for memory-range-*, reflink/copy for the COW disk, plain copy for small metadata.

func (*CloudHypervisor) GCModule

func (ch *CloudHypervisor) GCModule() gc.Module[chSnapshot]

GCModule returns the GC module for cross-module blob pinning and orphan cleanup.

func (*CloudHypervisor) Inspect

func (ch *CloudHypervisor) Inspect(ctx context.Context, ref string) (*types.VM, error)

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

func (*CloudHypervisor) List

func (ch *CloudHypervisor) List(ctx context.Context) ([]*types.VM, error)

List returns VM for all known VMs.

func (*CloudHypervisor) RegisterGC

func (ch *CloudHypervisor) RegisterGC(orch *gc.Orchestrator)

RegisterGC registers the Cloud Hypervisor GC module with the given Orchestrator.

func (*CloudHypervisor) Restore

func (ch *CloudHypervisor) Restore(ctx context.Context, vmRef string, vmCfg *types.VMConfig, snapshot io.Reader) (*types.VM, error)

Restore reverts a running VM to a previous snapshot's state.

The CH process is killed and restarted with the snapshot's memory and disk state. Network is preserved — same netns, same tap, same MAC/IP. vmCfg carries the final resource config (already validated >= snapshot values).

func (*CloudHypervisor) Snapshot

func (ch *CloudHypervisor) Snapshot(ctx context.Context, ref string) (*types.SnapshotConfig, io.ReadCloser, error)

Snapshot pauses the VM, captures its full state (CPU, memory, devices via CH snapshot API, plus the COW disk via sparse copy), resumes the VM, and returns a streaming tar.gz reader of the snapshot directory.

func (*CloudHypervisor) Start

func (ch *CloudHypervisor) Start(ctx context.Context, refs []string) ([]string, error)

Start launches the Cloud Hypervisor process for each VM ref. Returns the IDs that were successfully started.

func (*CloudHypervisor) Stop

func (ch *CloudHypervisor) Stop(ctx context.Context, refs []string) ([]string, error)

Stop shuts down the Cloud Hypervisor process for each VM ref. Two modes are used depending on the VM's boot method:

• UEFI boot (cloudimg): ACPI power-button → poll → fallback SIGTERM/SIGKILL
• Direct boot (OCI): vm.shutdown API → SIGTERM → SIGKILL (no ACPI)

Returns the IDs that were successfully stopped.

func (*CloudHypervisor) Type

func (ch *CloudHypervisor) Type() string

type Config

type Config struct {
	*config.Config
}

Config holds Cloud Hypervisor specific configuration, embedding the global config.

func (*Config) COWRawPath

func (c *Config) COWRawPath(vmID string) string

COWRawPath returns the path for the OCI COW raw disk.

func (*Config) CidataPath

func (c *Config) CidataPath(vmID string) string

CidataPath returns the path for the cloud-init NoCloud cidata disk.

func (*Config) EnsureDirs

func (c *Config) EnsureDirs() error

EnsureDirs creates all static directories required by the Cloud Hypervisor backend.

func (*Config) IndexFile

func (c *Config) IndexFile() string

IndexFile returns the VM index store path.

func (*Config) IndexLock

func (c *Config) IndexLock() string

IndexLock returns the VM index lock path.

func (*Config) LogDir

func (c *Config) LogDir() string

LogDir returns the top-level CH log directory.

func (*Config) OverlayPath

func (c *Config) OverlayPath(vmID string) string

OverlayPath returns the path for the cloudimg qcow2 overlay.

func (*Config) RunDir

func (c *Config) RunDir() string

RunDir returns the top-level CH runtime directory.

func (*Config) SocketWaitTimeout

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

SocketWaitTimeout returns the configured socket wait timeout or the default.

func (*Config) TerminateGracePeriod

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

TerminateGracePeriod returns the configured SIGTERM→SIGKILL grace period or the default.

func (*Config) VMLogDir

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

VMLogDir returns the per-VM log directory.

func (*Config) VMRunDir

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

VMRunDir returns the per-VM runtime directory.