Skip to content

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

Field Type Label Description
target_vm_id string
task TaskRef

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)

ExportDiskRequest.CredentialsEntry

Field Type Label Description
key string
value string

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

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

Field Type Label Description
key string
value string

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.)

ImportDiskRequest

Disk import operations for migration

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)

ImportDiskRequest.CredentialsEntry

Field Type Label Description
key string
value string

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)

ReconfigureRequest

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

Field Type Label Description
snapshot_id string
task TaskRef

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

Field Type Label Description
key string
value string

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

Method Name Request Type Response Type Description
Validate ValidateRequest ValidateResponse Validate provider configuration and connectivity
Create CreateRequest CreateResponse Create a new virtual machine
Delete DeleteRequest TaskResponse Delete a virtual machine
Power PowerRequest TaskResponse Perform power operations on a virtual machine
Reconfigure ReconfigureRequest TaskResponse Reconfigure virtual machine resources
HardwareUpgrade HardwareUpgradeRequest TaskResponse Upgrade VM hardware version
Describe DescribeRequest DescribeResponse Describe current virtual machine state
TaskStatus TaskStatusRequest TaskStatusResponse Check the status of an async task
SnapshotCreate SnapshotCreateRequest SnapshotCreateResponse Snapshot operations
SnapshotDelete SnapshotDeleteRequest TaskResponse
SnapshotRevert SnapshotRevertRequest TaskResponse
Clone CloneRequest CloneResponse Clone operations
ImagePrepare ImagePrepareRequest TaskResponse Image preparation and import
GetCapabilities GetCapabilitiesRequest GetCapabilitiesResponse Get provider capabilities
ExportDisk ExportDiskRequest ExportDiskResponse Disk migration operations
ImportDisk ImportDiskRequest ImportDiskResponse
GetDiskInfo GetDiskInfoRequest GetDiskInfoResponse
ListVMs ListVMsRequest ListVMsResponse List all VMs managed by this provider

Scalar Value Types

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 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)
int64 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
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 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)
sint64 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
fixed32 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)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)