373 lines
10 KiB
TypeScript
373 lines
10 KiB
TypeScript
import type { TFirecrackerArch, TCacheType, TSnapshotType, TLogLevel } from './common.js';
|
|
|
|
/**
|
|
* Top-level options for the SmartVM orchestrator.
|
|
*/
|
|
export interface ISmartVMOptions {
|
|
/** Directory for storing binaries, kernels, rootfs images, and sockets. Defaults to /tmp/.smartvm */
|
|
dataDir?: string;
|
|
/** Directory for VM sockets and ephemeral per-VM files. Defaults to /dev/shm/.smartvm/runtime on Linux when available. */
|
|
runtimeDir?: string;
|
|
/** Copy writable drives into the VM runtime directory before boot and delete them on cleanup. Defaults to true. */
|
|
ephemeralWritableDrives?: boolean;
|
|
/** Firecracker version to use. Defaults to latest. */
|
|
firecrackerVersion?: string;
|
|
/** Target architecture. Defaults to x86_64. */
|
|
arch?: TFirecrackerArch;
|
|
/** Custom path to firecracker binary (overrides version-based lookup). */
|
|
firecrackerBinaryPath?: string;
|
|
/** Network bridge name. Defaults to 'svbr0'. */
|
|
bridgeName?: string;
|
|
/** Network subnet in CIDR notation. Defaults to '172.30.0.0/24'. */
|
|
subnet?: string;
|
|
/** Directory for cached base images. Defaults to /tmp/.smartvm/base-images. */
|
|
baseImageCacheDir?: string;
|
|
/** Maximum number of cached base image bundles. Defaults to 2. */
|
|
maxStoredBaseImages?: number;
|
|
/** Hosted/project-owned base image manifest URL. */
|
|
baseImageManifestUrl?: string;
|
|
/** Local hosted/project-owned base image manifest path for development and tests. */
|
|
baseImageManifestPath?: string;
|
|
}
|
|
|
|
/**
|
|
* Predefined base image sources for integration testing and quick starts.
|
|
*/
|
|
export type TBaseImagePreset = 'latest' | 'lts' | 'hosted';
|
|
|
|
/**
|
|
* Root filesystem image type used by a base image bundle.
|
|
*/
|
|
export type TBaseImageRootfsType = 'ext4' | 'squashfs';
|
|
|
|
/**
|
|
* Options for the BaseImageManager.
|
|
*/
|
|
export interface IBaseImageManagerOptions {
|
|
/** Architecture to resolve. Defaults to x86_64. */
|
|
arch?: TFirecrackerArch;
|
|
/** Directory for cached base image bundles. Defaults to /tmp/.smartvm/base-images. */
|
|
cacheDir?: string;
|
|
/** Maximum number of cached base image bundles. Defaults to 2. */
|
|
maxStoredBaseImages?: number;
|
|
/** Hosted base image manifest URL for project-owned bundles. */
|
|
hostedManifestUrl?: string;
|
|
/** Local hosted base image manifest path for development and tests. */
|
|
hostedManifestPath?: string;
|
|
}
|
|
|
|
/**
|
|
* Options when resolving or downloading a base image bundle.
|
|
*/
|
|
export interface IEnsureBaseImageOptions {
|
|
/** Preset to use. Defaults to latest. */
|
|
preset?: TBaseImagePreset;
|
|
/** Architecture to resolve. Defaults to manager architecture. */
|
|
arch?: TFirecrackerArch;
|
|
/** Redownload even if the bundle already exists locally. */
|
|
forceDownload?: boolean;
|
|
/** Hosted base image manifest URL. Overrides preset resolution. */
|
|
manifestUrl?: string;
|
|
/** Local hosted base image manifest path. Overrides preset resolution. */
|
|
manifestPath?: string;
|
|
}
|
|
|
|
/**
|
|
* Single hosted base image artifact in a manifest.
|
|
*/
|
|
export interface IBaseImageArtifactManifest {
|
|
/** Public URL for hosted artifacts. */
|
|
url?: string;
|
|
/** Local path for development/tests. */
|
|
path?: string;
|
|
/** Optional plain output filename. Defaults to basename of url/path. */
|
|
fileName?: string;
|
|
/** Expected SHA256 for verification. Required when url is used. */
|
|
sha256?: string;
|
|
/** Expected file size in bytes. */
|
|
sizeBytes?: number;
|
|
}
|
|
|
|
/**
|
|
* Hosted/project-owned base image manifest format.
|
|
*/
|
|
export interface IBaseImageHostedManifest {
|
|
schemaVersion: 1;
|
|
bundleId: string;
|
|
name?: string;
|
|
arch: TFirecrackerArch;
|
|
firecrackerVersion: string;
|
|
rootfsType: TBaseImageRootfsType;
|
|
rootfsIsReadOnly?: boolean;
|
|
bootArgs?: string;
|
|
kernel: IBaseImageArtifactManifest;
|
|
rootfs: IBaseImageArtifactManifest;
|
|
}
|
|
|
|
/**
|
|
* Cached base image bundle metadata.
|
|
*/
|
|
export interface IBaseImageBundle {
|
|
preset: TBaseImagePreset;
|
|
arch: TFirecrackerArch;
|
|
ciVersion: string;
|
|
firecrackerVersion: string;
|
|
bundleId: string;
|
|
bundleDir: string;
|
|
kernelImagePath: string;
|
|
rootfsPath: string;
|
|
rootfsType: TBaseImageRootfsType;
|
|
rootfsIsReadOnly: boolean;
|
|
bootArgs: string;
|
|
source: {
|
|
type?: 'firecracker-ci' | 'hosted-manifest';
|
|
bucketUrl?: string;
|
|
kernelKey?: string;
|
|
rootfsKey?: string;
|
|
manifestUrl?: string;
|
|
manifestPath?: string;
|
|
kernelUrl?: string;
|
|
rootfsUrl?: string;
|
|
kernelSourcePath?: string;
|
|
rootfsSourcePath?: string;
|
|
};
|
|
checksums?: {
|
|
kernelSha256?: string;
|
|
rootfsSha256?: string;
|
|
};
|
|
sizes?: {
|
|
kernelBytes?: number;
|
|
rootfsBytes?: number;
|
|
};
|
|
createdAt: string;
|
|
lastAccessedAt: string;
|
|
}
|
|
|
|
/**
|
|
* Runtime behavior for a MicroVM instance.
|
|
*/
|
|
export interface IMicroVMRuntimeOptions {
|
|
/** Directory for VM sockets and ephemeral per-VM files. */
|
|
runtimeDir?: string;
|
|
/** Copy writable drives into runtimeDir before boot and delete them on cleanup. Defaults to true. */
|
|
ephemeralWritableDrives?: boolean;
|
|
}
|
|
|
|
/**
|
|
* Firecracker boot source configuration.
|
|
*/
|
|
export interface IBootSource {
|
|
/** Path to the kernel image on the host. */
|
|
kernelImagePath: string;
|
|
/** Kernel boot arguments. */
|
|
bootArgs?: string;
|
|
/** Path to initrd image (optional). */
|
|
initrdPath?: string;
|
|
}
|
|
|
|
/**
|
|
* Machine hardware configuration.
|
|
*/
|
|
export interface IMachineConfig {
|
|
/** Number of vCPUs (1-32). */
|
|
vcpuCount: number;
|
|
/** Memory size in MiB. */
|
|
memSizeMib: number;
|
|
/** Enable SMT (simultaneous multi-threading). Defaults to false. */
|
|
smt?: boolean;
|
|
/** Enable CPU template for security (C3, T2, T2S, T2CL, T2A, V1N1, None). */
|
|
cpuTemplate?: string;
|
|
/** Whether to track dirty pages for incremental snapshots. */
|
|
trackDirtyPages?: boolean;
|
|
}
|
|
|
|
/**
|
|
* Rate limiter configuration for drives and network interfaces.
|
|
*/
|
|
export interface IRateLimiter {
|
|
/** Bandwidth limit. */
|
|
bandwidth?: {
|
|
size: number;
|
|
oneTimeBurst?: number;
|
|
refillTime: number;
|
|
};
|
|
/** Operations per second limit. */
|
|
ops?: {
|
|
size: number;
|
|
oneTimeBurst?: number;
|
|
refillTime: number;
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Block device (drive) configuration.
|
|
*/
|
|
export interface IDriveConfig {
|
|
/** Unique drive identifier. */
|
|
driveId: string;
|
|
/** Path to the disk image on the host. */
|
|
pathOnHost: string;
|
|
/** Whether this is the root device. */
|
|
isRootDevice: boolean;
|
|
/** Whether the drive is read-only. */
|
|
isReadOnly?: boolean;
|
|
/** Partition UUID (optional). */
|
|
partUuid?: string;
|
|
/** Cache type (Unsafe or Writeback). */
|
|
cacheType?: TCacheType;
|
|
/** Rate limiter for the drive. */
|
|
rateLimiter?: IRateLimiter;
|
|
/** Path to a file that backs the device for I/O. */
|
|
ioEngine?: string;
|
|
/** Whether this drive should be staged into per-VM ephemeral storage. Defaults to true for writable drives. */
|
|
ephemeral?: boolean;
|
|
}
|
|
|
|
/**
|
|
* Network interface configuration.
|
|
*/
|
|
export interface INetworkInterfaceConfig {
|
|
/** Unique interface identifier (e.g., 'eth0'). */
|
|
ifaceId: string;
|
|
/** TAP device name on the host. Automatically set by NetworkManager if not provided. */
|
|
hostDevName?: string;
|
|
/** Guest MAC address. Automatically generated if not provided. */
|
|
guestMac?: string;
|
|
/** Rate limiter for RX traffic. */
|
|
rxRateLimiter?: IRateLimiter;
|
|
/** Rate limiter for TX traffic. */
|
|
txRateLimiter?: IRateLimiter;
|
|
}
|
|
|
|
/**
|
|
* Vsock device configuration.
|
|
*/
|
|
export interface IVsockConfig {
|
|
/** Guest CID (Context Identifier). Must be >= 3. */
|
|
guestCid: number;
|
|
/** Path to the Unix domain socket on the host. */
|
|
udsPath: string;
|
|
}
|
|
|
|
/**
|
|
* Balloon device configuration for dynamic memory management.
|
|
*/
|
|
export interface IBalloonConfig {
|
|
/** Target balloon size in MiB. */
|
|
amountMib: number;
|
|
/** Whether to deflate on OOM. */
|
|
deflateOnOom: boolean;
|
|
/** Polling interval for balloon stats in seconds. */
|
|
statsPollingIntervalS?: number;
|
|
}
|
|
|
|
/**
|
|
* MMDS (Microvm Metadata Service) configuration.
|
|
*/
|
|
export interface IMmdsConfig {
|
|
/** MMDS version (V1 or V2). */
|
|
version?: 'V1' | 'V2';
|
|
/** Network interfaces that MMDS traffic is allowed on. */
|
|
networkInterfaces: string[];
|
|
}
|
|
|
|
/**
|
|
* Logger configuration for Firecracker.
|
|
*/
|
|
export interface ILoggerConfig {
|
|
/** Path to the log file. */
|
|
logPath: string;
|
|
/** Log level. */
|
|
level?: TLogLevel;
|
|
/** Whether to show log level. */
|
|
showLevel?: boolean;
|
|
/** Whether to show log origin (file, line). */
|
|
showLogOrigin?: boolean;
|
|
}
|
|
|
|
/**
|
|
* Metrics configuration for Firecracker.
|
|
*/
|
|
export interface IMetricsConfig {
|
|
/** Path to the metrics file (FIFO). */
|
|
metricsPath: string;
|
|
}
|
|
|
|
/**
|
|
* Snapshot creation parameters.
|
|
*/
|
|
export interface ISnapshotCreateParams {
|
|
/** Path to save the snapshot file. */
|
|
snapshotPath: string;
|
|
/** Path to save the memory file. */
|
|
memFilePath: string;
|
|
/** Snapshot type (Full or Diff). */
|
|
snapshotType?: TSnapshotType;
|
|
}
|
|
|
|
/**
|
|
* Snapshot loading parameters.
|
|
*/
|
|
export interface ISnapshotLoadParams {
|
|
/** Path to the snapshot file. */
|
|
snapshotPath: string;
|
|
/** Path to the memory file. */
|
|
memFilePath: string;
|
|
/** Whether to enable diff snapshots after loading. */
|
|
enableDiffSnapshots?: boolean;
|
|
/** Whether to resume the VM after loading. */
|
|
resumeVm?: boolean;
|
|
}
|
|
|
|
/**
|
|
* Complete MicroVM configuration combining all sub-configs.
|
|
*/
|
|
export interface IMicroVMConfig {
|
|
/** Unique VM identifier. Auto-generated if not provided. */
|
|
id?: string;
|
|
/** Boot source configuration (required). */
|
|
bootSource: IBootSource;
|
|
/** Machine hardware configuration (required). */
|
|
machineConfig: IMachineConfig;
|
|
/** Block devices. */
|
|
drives?: IDriveConfig[];
|
|
/** Network interfaces. */
|
|
networkInterfaces?: INetworkInterfaceConfig[];
|
|
/** Vsock device. */
|
|
vsock?: IVsockConfig;
|
|
/** Balloon device. */
|
|
balloon?: IBalloonConfig;
|
|
/** MMDS configuration. */
|
|
mmds?: IMmdsConfig;
|
|
/** Logger configuration. */
|
|
logger?: ILoggerConfig;
|
|
/** Metrics configuration. */
|
|
metrics?: IMetricsConfig;
|
|
}
|
|
|
|
/**
|
|
* Options for the NetworkManager.
|
|
*/
|
|
export interface INetworkManagerOptions {
|
|
/** Bridge device name. Defaults to 'svbr0'. */
|
|
bridgeName?: string;
|
|
/** Subnet in CIDR notation. Defaults to '172.30.0.0/24'. */
|
|
subnet?: string;
|
|
}
|
|
|
|
/**
|
|
* Represents a TAP device created by the NetworkManager.
|
|
*/
|
|
export interface ITapDevice {
|
|
/** TAP device name on the host. */
|
|
tapName: string;
|
|
/** IP address assigned to the guest. */
|
|
guestIp: string;
|
|
/** Gateway IP (bridge IP). */
|
|
gatewayIp: string;
|
|
/** Subnet mask. */
|
|
subnetMask: string;
|
|
/** MAC address for the guest. */
|
|
mac: string;
|
|
}
|