firecracker.proto

syntax = "proto3";

import "types.proto";

option go_package = ".;proto";

// CreateVMRequest specifies creation parameters for a new FC instance
message CreateVMRequest {
    // VM identifier to assign
    string VMID = 1;

    // Specifies the machine configuration for the VM
    FirecrackerMachineConfiguration MachineCfg = 2;

    // Specifies the file path where the kernel image is located
    string KernelImagePath = 3;

    // Specifies the commandline arguments that should be passed to the kernel
    string KernelArgs = 4;

    // Specifies drive containing the rootfs of the VM
    FirecrackerRootDrive RootDrive = 5;

    // Specifies additional drives whose contents will be mounted inside the VM on boot.
    repeated FirecrackerDriveMount DriveMounts = 6;

    // Specifies the networking configuration for a VM
    repeated FirecrackerNetworkInterface NetworkInterfaces = 7;

    // The number of dummy drives to reserve in advance before running FC instance.
    int32 ContainerCount = 8;

    // Whether the VM should exit after all tasks running in it have been deleted.
    bool ExitAfterAllTasksDeleted = 9;

    JailerConfig JailerConfig = 10;

    uint32 TimeoutSeconds = 11;

    string LogFifoPath = 12;
    string MetricsFifoPath = 13;

    FirecrackerBalloonDevice BalloonDevice = 14;
}

message CreateVMResponse {
    string VMID = 1;
    string SocketPath = 2;
    string LogFifoPath = 3;
    string MetricsFifoPath = 4;
    string CgroupPath = 5;
}

message PauseVMRequest {
    string VMID = 1;
}

message ResumeVMRequest {
    string VMID = 1;
}

message StopVMRequest {
    string VMID = 1;
    uint32 TimeoutSeconds = 2;
}

message GetVMInfoRequest {
    string VMID = 1;
}

message GetVMInfoResponse {
    string VMID = 1;
    string SocketPath = 2;
    string LogFifoPath = 3;
    string MetricsFifoPath = 4;
    string CgroupPath = 5;
    string VSockPath = 6;
}

message SetVMMetadataRequest {
    string VMID = 1;
    string Metadata = 2;
}

message UpdateVMMetadataRequest {
    string VMID = 1;
    string Metadata = 2;
}

message GetVMMetadataRequest {
    string VMID = 1;
}

message GetVMMetadataResponse {
    string Metadata = 1;
}

// DriveExposePolicy is used to configure the method to expose drive files.
// "COPY" is copying the files to the jail, which is the default behavior.
// "BIND" is bind-mounting the files on the jail, assuming a caller pre-configures the permissions of
// the files appropriately.
enum DriveExposePolicy {
    COPY = 0;
    BIND = 1;
}

message JailerConfig {
    string NetNS = 1;
    // List of the physical numbers of the CPUs on which processes in that
    // cpuset are allowed to execute.  See List Format below for a description
    // of the format of cpus.
    //
    // The CPUs allowed to a cpuset may be changed by writing a new list to its
    // cpus file.
    // Taken from http://man7.org/linux/man-pages/man7/cpuset.7.html
    //
    // This is formatted as specified in the cpuset man page under "List Format"
    // http://man7.org/linux/man-pages/man7/cpuset.7.html
    string CPUs = 2;
    // List of memory nodes on which processes in this cpuset are allowed to
    // allocate memory.  See List Format below for a description of the format
    // of mems.
    // Taken from http://man7.org/linux/man-pages/man7/cpuset.7.html
    //
    // This is formatted as specified in the cpuset man page under "List Format"
    // http://man7.org/linux/man-pages/man7/cpuset.7.html
    string Mems = 3;
    uint32 UID = 4;
    uint32 GID = 5;
	// CgroupPath is used to dictate where the cgroup should be located
	// relative to the cgroup directory which is
	// /sys/fs/cgroup/cpu/<CgroupPath>/<vmID>
	// if no value was provided, then /firecracker-containerd will be used as
	// the default value
    string CgroupPath = 6;

    // DriveExposePolicy is used to configure the method to expose drive files.
    DriveExposePolicy DriveExposePolicy = 7;
}

message UpdateBalloonRequest {
    string VMID = 1;
    int64 AmountMib = 2;
}

message GetBalloonConfigRequest {
    string VMID = 1;
}

message GetBalloonConfigResponse {
    FirecrackerBalloonDevice BalloonConfig = 1;
}

message GetBalloonStatsRequest {
    string VMID = 1;
}

message GetBalloonStatsResponse {
    // Actual amount of memory (in MiB) the device is holding.
    int64 ActualMib = 1;

    // Actual number of pages the device is holding.
    int64 ActualPages = 2; 

    // An estimate of how much memory is available (in bytes) for starting new applications, without pushing the system to swap.
    int64 AvailableMemory = 3;  

    // The amount of memory, in bytes, that can be quickly reclaimed without additional I/O. 
    // Typically these pages are used for caching files from disk.
    int64 DiskCaches = 4;

    // The amount of memory not being used for any purpose (in bytes).
    int64 FreeMemory = 5; 

    // The number of successful hugetlb page allocations in the guest.
    int64 HugetlbAllocations = 6; 	

    // The number of failed hugetlb page allocations in the guest.
    int64 HugetlbFailures = 7; 	

    // The number of major page faults that have occurred.
    int64 MajorFaults = 8; 
    
    // The number of minor page faults that have occurred.
    int64 MinorFaults = 9; 

    // The amount of memory that has been swapped in (in bytes).
    int64 SwapIn = 10; 	

    // The amount of memory that has been swapped out to disk (in bytes).
    int64 SwapOut = 11;	

    // Target amount of memory (in MiB) the device aims to hold.
    int64 TargetMib = 12; 

    // Target number of pages the device aims to hold.
    int64 TargetPages = 13;	

    // The total amount of memory available (in bytes).
    int64 TotalMemory = 14; 
}

message UpdateBalloonStatsRequest {
    string VMID = 1;
    int64 StatsPollingIntervals = 2;
}