Virtual Machines API

The VMService (pivirt.vm.v1) delivers complete control over virtual machine lifecycles, power transitions, specification changes, live migration, and serial console streaming.

Service Definition

package pivirt.vm.v1;

service VMService {
  // Create a new VM
  rpc CreateVM(CreateVMRequest) returns (VM);

  // Get VM by ID
  rpc GetVM(GetVMRequest) returns (VM);

  // List VMs with filters
  rpc ListVMs(ListVMsRequest) returns (stream VM);

  // Update VM spec (hot-plug where supported)
  rpc UpdateVM(UpdateVMRequest) returns (VM);

  // Delete VM
  rpc DeleteVM(DeleteVMRequest) returns (google.protobuf.Empty);

  // Power operations
  rpc StartVM(StartVMRequest) returns (Operation);
  rpc StopVM(StopVMRequest) returns (Operation);
  rpc RebootVM(RebootVMRequest) returns (Operation);
  rpc PauseVM(PauseVMRequest) returns (Operation);
  rpc ResumeVM(ResumeVMRequest) returns (Operation);

  // Migration
  rpc MigrateVM(MigrateVMRequest) returns (Operation);

  // Console
  rpc GetConsole(GetConsoleRequest) returns (ConsoleInfo);
  rpc OpenConsole(stream ConsoleMessage) returns (stream ConsoleMessage);

  // Snapshots
  rpc CreateSnapshot(CreateSnapshotRequest) returns (Snapshot);
  rpc ListSnapshots(ListSnapshotsRequest) returns (stream Snapshot);
  rpc RestoreSnapshot(RestoreSnapshotRequest) returns (Operation);
  rpc DeleteSnapshot(DeleteSnapshotRequest) returns (google.protobuf.Empty);
}

Messages

VM

message VM {
  string id = 1;
  string name = 2;
  string namespace = 3;
  VMStatus status = 4;
  VMSpec spec = 5;
  VMStatusDetail status_detail = 6;
  map<string, string> labels = 7;
  map<string, string> annotations = 8;
  google.protobuf.Timestamp created_at = 9;
  google.protobuf.Timestamp updated_at = 10;
  string owner = 11;
}

enum VMStatus {
  VM_STATUS_UNSPECIFIED = 0;
  VM_STATUS_PENDING = 1;
  VM_STATUS_RUNNING = 2;
  VM_STATUS_STOPPED = 3;
  VM_STATUS_PAUSED = 4;
  VM_STATUS_ERROR = 5;
  VM_STATUS_MIGRATING = 6;
  VM_STATUS_SNAPSHOTTING = 7;
}

VMSpec

message VMSpec {
  // Compute
  int32 vcpus = 1;
  int64 memory_bytes = 2;
  string cpu_model = 3;
  CPUTopology cpu_topology = 4;
  string firmware = 5;  // bios, uefi
  string machine_type = 6;

  // Disks
  repeated Disk disks = 10;

  // Network
  repeated NetworkInterface nics = 20;

  // Features
  bool enable_balloon = 30;
  bool enable_hugepages = 31;
  bool enable_nested_virt = 32;

  // Cloud-init
  CloudInitConfig cloud_init = 40;
}

message Disk {
  string name = 1;
  string pool = 2;
  int64 size_bytes = 3;
  string format = 4;  // raw, qcow2, vmdk
  string bus = 5;     // virtio, scsi, sata, nvme
  bool bootable = 6;
  bool discard = 7;   // trim support
  IOThread iothread = 8;
  string existing_path = 9;
  string backing_file = 10;  // for copy-on-write
}

message NetworkInterface {
  string name = 1;
  string bridge = 2;
  string mac = 3;
  string model = 4;  // virtio, e1000, vmxnet3
  int32 queues = 5;
  VLANConfig vlan = 6;
  VXLANConfig vxlan = 7;
  BandwidthLimit bandwidth = 8;
}

Methods

CreateVM

message CreateVMRequest {
  VMSpec spec = 1;
  string namespace = 2;
  map<string, string> labels = 3;
  map<string, string> annotations = 4;
}

Example:

grpcurl -plaintext -d '{
  "spec": {
    "name": "web-01",
    "vcpus": 2,
    "memory_bytes": 4294967296,
    "disks": [{
      "name": "root",
      "pool": "default",
      "size_bytes": 21474836480,
      "format": "qcow2",
      "bus": "virtio"
    }],
    "nics": [{
      "name": "eth0",
      "bridge": "virbr0",
      "model": "virtio"
    }]
  },
  "namespace": "production"
}' localhost:9001 pivirt.vm.v1.VMService/CreateVM

GetVM

message GetVMRequest {
  string id = 1;
  string namespace = 2;
}

Example:

grpcurl -plaintext -d '{
  "id": "vm-abc123",
  "namespace": "production"
}' localhost:9001 pivirt.vm.v1.VMService/GetVM

ListVMs

message ListVMsRequest {
  string namespace = 1;
  map<string, string> label_selector = 2;
  VMStatus status_filter = 3;
  int32 page_size = 4;
  string page_token = 5;
}

Example:

grpcurl -plaintext -d '{
  "namespace": "production",
  "status_filter": "VM_STATUS_RUNNING"
}' localhost:9001 pivirt.vm.v1.VMService/ListVMs

StartVM

message StartVMRequest {
  string id = 1;
  string namespace = 2;
}

Example:

grpcurl -plaintext -d '{
  "id": "vm-abc123",
  "namespace": "production"
}' localhost:9001 pivirt.vm.v1.VMService/StartVM

MigrateVM

message MigrateVMRequest {
  string id = 1;
  string namespace = 2;
  string target_node = 3;
  MigrationOptions options = 4;
}

message MigrationOptions {
  bool live = 1;
  int64 bandwidth_limit_mbps = 2;
  int32 downtime_limit_ms = 3;
  bool compress = 4;
}

Example:

grpcurl -plaintext -d '{
  "id": "vm-abc123",
  "namespace": "production",
  "target_node": "node-02",
  "options": {
    "live": true,
    "bandwidth_limit_mbps": 1000,
    "downtime_limit_ms": 500,
    "compress": true
  }
}' localhost:9001 pivirt.vm.v1.VMService/MigrateVM

Error Codes

Code	Description
NOT_FOUND	VM not found
ALREADY_EXISTS	VM with same name exists
INVALID_ARGUMENT	Invalid VM spec
RESOURCE_EXHAUSTED	Insufficient resources
FAILED_PRECONDITION	VM in wrong state

Related

• API Overview
• VM Concepts
• pvcli VM Commands