Protocol Documentation
Table of Contents
Top
provider/v1/provider.proto
CloneRequest Clone operations
Field Type Label Description source_vm_id string target_name string linked bool Best-effort linked clone class_json string JSON-encoded specifications for customization
VMClass overrides | | placement_json | string | | Placement hints | | customize_json | string | | Customization spec |
CloneResponse
CreateRequest Create a new virtual machine
Field Type Label Description name string user_data bytes Already rendered cloud-init/ignition data meta_data bytes Cloud-init metadata (YAML format) class_json string JSON-encoded provider-agnostic specifications
VMClass | | image_json | string | | VMImage | | networks_json | string | | []NetworkAttachment | | disks_json | string | | []DiskSpec | | placement_json | string | | Placement | | tags | string | repeated | Tags |
CreateResponse Field Type Label Description id string Provider-specific VM identifier task TaskRef Optional task reference for async operations
DeleteRequest Delete a virtual machine
Field Type Label Description id string
DescribeRequest Describe virtual machine current state
Field Type Label Description id string
DescribeResponse Field Type Label Description exists bool power_state string ips string repeated console_url string provider_raw_json string Provider-specific additional data
DiskInfo Field Type Label Description id string Disk identifier path string Disk path size_gib int32 Disk size in GiB format string Disk format (qcow2, vmdk, raw, etc.)
Empty Empty message for operations with no parameters
ExportDiskRequest Disk export operations for migration
Field Type Label Description vm_id string VM identifier disk_id string Disk identifier (optional, defaults to primary disk) snapshot_id string Snapshot to export from (optional) destination_url string Where to upload the disk (S3, HTTP, etc.) format string Desired export format (qcow2, vmdk, raw) compress bool Enable compression during export credentials ExportDiskRequest.CredentialsEntry repeated Credentials for destination (access keys, tokens) backend_type string Staging backend: "pvc" transfer_mode string Transfer mode: "auto" storage_options_json string JSON-encoded backend-specific options (ADR-0006; empty in Slice 0)
ExportDiskRequest.CredentialsEntry
ExportDiskResponse Field Type Label Description export_id string Export operation identifier task TaskRef Task reference for async tracking estimated_size_bytes int64 Estimated size of export checksum string Checksum of exported disk (SHA256)
GetCapabilitiesRequest Capability check - what features does this provider support
GetCapabilitiesResponse Field Type Label Description supports_reconfigure_online bool supports_disk_expansion_online bool supports_snapshots bool supports_memory_snapshots bool supports_linked_clones bool supports_image_import bool supported_disk_types string repeated supported_network_types string repeated supports_disk_export bool Can export disks for migration supports_disk_import bool Can import disks from external sources supported_export_formats string repeated Supported export formats (qcow2, vmdk, raw) supported_import_formats string repeated Supported import formats supports_export_compression bool Supports compression during export supported_export_backends string repeated Export staging backends: "pvc" supported_import_backends string repeated Import staging backends: "pvc" supported_transfer_modes string repeated Transfer modes: "relay"
GetDiskInfoRequest Get disk information for migration planning
Field Type Label Description vm_id string VM identifier disk_id string Disk identifier (optional, defaults to primary disk) snapshot_id string Get info for specific snapshot (optional)
GetDiskInfoResponse Field Type Label Description disk_id string Disk identifier format string Disk format (qcow2, vmdk, raw) virtual_size_bytes int64 Virtual size (capacity) actual_size_bytes int64 Actual size (allocated) path string Path or location is_bootable bool Is this a boot disk snapshots string repeated Available snapshots backing_file string Backing file (for linked clones) metadata GetDiskInfoResponse.MetadataEntry repeated Additional provider-specific metadata
GetDiskInfoResponse.MetadataEntry
HardwareUpgradeRequest Upgrade VM hardware version
Field Type Label Description id string target_version int32 Target hardware version (e.g., 21)
ImagePrepareRequest Image preparation operations
Field Type Label Description image_json string JSON-encoded VMImage spec target_name string Target template/image name storage_hint string Storage location hint (datastore, pool, etc.)
ImagePrepareResponse ImagePrepareResponse reports where the provider placed the prepared image so the manager can later create VMs from that prepared location instead of re-resolving (and possibly re-downloading) the original source (issue #154, PR-6 / #214).
It mirrors the CloneResponse precedent: task stays at field 1 so this message is wire-compatible with the TaskResponse it replaces — a manager that still decodes a TaskResponse reads field 1 (the TaskRef) unchanged, and the new id/path fields are simply ignored by older decoders. The change is therefore additive and non-breaking.
Field Type Label Description task TaskRef task references an async prepare operation; an empty/nil task means the prepare completed synchronously. Field 1 is intentionally identical to TaskResponse.task for wire compatibility. prepared_image_id string prepared_image_id is the provider-specific identifier of the prepared image — e.g. a vSphere template name / MoRef value, or a Proxmox template name/VMID. The manager stamps this onto VMImage.status and uses it as the template ref at create time. Known at trigger time even for async prepares. prepared_image_path string prepared_image_path is the provider-specific path of the prepared image — e.g. a libvirt pool path (<poolPath>/<target>.qcow2). Empty for providers that address prepared images by id/name only (vSphere, Proxmox). Known at trigger time even for async prepares.
ImportDiskRequest Disk import operations for migration. See the ExportDiskRequest host-vs-pod execution contract above: disk bytes never traverse the gRPC channel; backend_type/transfer_mode carry the same meaning for the import (target) side (ADR-0006).
Field Type Label Description source_url string Where to download the disk from (S3, HTTP, etc.) storage_hint string Target storage location (datastore, pool, etc.) format string Source disk format (qcow2, vmdk, raw) target_name string Name for the imported disk verify_checksum bool Verify checksum after import expected_checksum string Expected checksum (SHA256) credentials ImportDiskRequest.CredentialsEntry repeated Credentials for source (access keys, tokens) backend_type string Staging backend: "pvc" transfer_mode string Transfer mode: "auto" storage_options_json string JSON-encoded backend-specific options (ADR-0006; empty in Slice 0)
ImportDiskRequest.CredentialsEntry
ImportDiskResponse Field Type Label Description disk_id string Imported disk identifier path string Path to imported disk task TaskRef Task reference for async tracking actual_size_bytes int64 Actual size of imported disk checksum string Checksum of imported disk (SHA256)
ListVMsRequest List all VMs managed by this provider
ListVMsResponse Field Type Label Description vms VMInfo repeated
NetworkInfo Field Type Label Description name string Network name mac string MAC address ip_address string IP address if static
PowerRequest Power control operations
Field Type Label Description id string op PowerOp graceful_timeout_seconds int32 Timeout for graceful operations (shutdown/reboot)
Reconfigure virtual machine resources
Field Type Label Description id string desired_json string JSON-encoded desired state
SnapshotCreateRequest Snapshot operations
Field Type Label Description vm_id string name_hint string include_memory bool Include memory state if supported description string
SnapshotCreateResponse
SnapshotDeleteRequest Field Type Label Description vm_id string snapshot_id string
SnapshotRevertRequest Field Type Label Description vm_id string snapshot_id string
TaskRef Task reference for async operations
Field Type Label Description id string
TaskResponse Generic task response for async operations
Field Type Label Description task TaskRef
TaskStatusRequest Check async task status
Field Type Label Description task TaskRef
TaskStatusResponse Field Type Label Description done bool error string Error message if task failed
VMInfo Field Type Label Description id string Provider-specific VM identifier name string VM name power_state string Current power state ips string repeated IP addresses cpu int32 Number of virtual CPUs memory_mib int64 Memory in MiB disks DiskInfo repeated Disk information networks NetworkInfo repeated Network information provider_raw VMInfo.ProviderRawEntry repeated Provider-specific metadata
VMInfo.ProviderRawEntry
ValidateRequest Validate provider connectivity and configuration
ValidateResponse Field Type Label Description ok bool message string
PowerOp Power operations enum
Name Number Description POWER_OP_UNSPECIFIED 0 POWER_OP_ON 1 POWER_OP_OFF 2 POWER_OP_REBOOT 3 POWER_OP_SHUTDOWN_GRACEFUL 4 Graceful shutdown using guest tools
Provider Provider service definition
Scalar Value Types .proto Type Notes C++ Java Python Go C# PHP Ruby double double float float64 double float Float float float float float32 float float Float Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required) Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required) Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required) Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required) Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required) Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required) Always eight bytes. int64 long int/long int64 long integer/string Bignum bool boolean boolean bool bool boolean TrueClass/FalseClass A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8) May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)