Storage API

The StorageService (pivirt.storage.v1) controls clustered storage pools, volume creation and dynamic resizing, sparse disk clones, and snapshot trees.

Service Definition

package pivirt.storage.v1;

service StorageService {
  // Pool operations
  rpc CreatePool(CreatePoolRequest) returns (StoragePool);
  rpc GetPool(GetPoolRequest) returns (StoragePool);
  rpc ListPools(ListPoolsRequest) returns (stream StoragePool);
  rpc DeletePool(DeletePoolRequest) returns (google.protobuf.Empty);

  // Volume operations
  rpc CreateVolume(CreateVolumeRequest) returns (Volume);
  rpc GetVolume(GetVolumeRequest) returns (Volume);
  rpc ListVolumes(ListVolumesRequest) returns (stream Volume);
  rpc DeleteVolume(DeleteVolumeRequest) returns (google.protobuf.Empty);
  rpc ResizeVolume(ResizeVolumeRequest) returns (Volume);
  rpc CloneVolume(CloneVolumeRequest) returns (Volume);

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

  // Pool stats
  rpc GetPoolStats(GetPoolStatsRequest) returns (PoolStats);
}

Messages

StoragePool

message StoragePool {
  string name = 1;
  PoolType type = 2;
  PoolStatus status = 3;
  int64 capacity_bytes = 4;
  int64 used_bytes = 5;
  int64 available_bytes = 6;
  map<string, string> config = 7;
  google.protobuf.Timestamp created_at = 8;
}

enum PoolType {
  POOL_TYPE_UNSPECIFIED = 0;
  POOL_TYPE_DIR = 1;
  POOL_TYPE_LVM = 2;
  POOL_TYPE_ISCSI = 3;
  POOL_TYPE_NFS = 4;
  POOL_TYPE_RBD = 5;
}

enum PoolStatus {
  POOL_STATUS_UNSPECIFIED = 0;
  POOL_STATUS_ACTIVE = 1;
  POOL_STATUS_INACTIVE = 2;
  POOL_STATUS_ERROR = 3;
}

Volume

message Volume {
  string id = 1;
  string name = 2;
  string pool = 3;
  int64 size_bytes = 4;
  int64 used_bytes = 5;
  VolumeFormat format = 6;
  VolumeStatus status = 7;
  map<string, string> labels = 8;
  google.protobuf.Timestamp created_at = 9;
  google.protobuf.Timestamp updated_at = 10;
}

enum VolumeFormat {
  VOLUME_FORMAT_UNSPECIFIED = 0;
  VOLUME_FORMAT_RAW = 1;
  VOLUME_FORMAT_QCOW2 = 2;
  VOLUME_FORMAT_VMDK = 3;
  VOLUME_FORMAT_VDI = 4;
}

enum VolumeStatus {
  VOLUME_STATUS_UNSPECIFIED = 0;
  VOLUME_STATUS_CREATING = 1;
  VOLUME_STATUS_READY = 2;
  VOLUME_STATUS_IN_USE = 3;
  VOLUME_STATUS_ERROR = 4;
}

Snapshot

message Snapshot {
  string id = 1;
  string name = 2;
  string volume_id = 3;
  int64 size_bytes = 4;
  SnapshotStatus status = 5;
  google.protobuf.Timestamp created_at = 6;
  string parent_snapshot_id = 7;
}

enum SnapshotStatus {
  SNAPSHOT_STATUS_UNSPECIFIED = 0;
  SNAPSHOT_STATUS_CREATING = 1;
  SNAPSHOT_STATUS_READY = 2;
  SNAPSHOT_STATUS_ERROR = 3;
}

Methods

CreatePool

message CreatePoolRequest {
  string name = 1;
  PoolType type = 2;
  map<string, string> config = 3;
}

Example:

grpcurl -plaintext -d '{
  "name": "fast-pool",
  "type": "POOL_TYPE_LVM",
  "config": {
    "volume_group": "pivirtd-vg",
    "thin_pool": "pivirtd-thin"
  }
}' localhost:9002 pivirt.storage.v1.StorageService/CreatePool

CreateVolume

message CreateVolumeRequest {
  string name = 1;
  string pool = 2;
  int64 size_bytes = 3;
  VolumeFormat format = 4;
  map<string, string> labels = 5;
}

Example:

grpcurl -plaintext -d '{
  "name": "data-01",
  "pool": "default",
  "size_bytes": 107374182400,
  "format": "VOLUME_FORMAT_QCOW2"
}' localhost:9002 pivirt.storage.v1.StorageService/CreateVolume

ResizeVolume

message ResizeVolumeRequest {
  string id = 1;
  int64 new_size_bytes = 2;
}

Example:

grpcurl -plaintext -d '{
  "id": "vol-abc123",
  "new_size_bytes": 214748364800
}' localhost:9002 pivirt.storage.v1.StorageService/ResizeVolume

CloneVolume

message CloneVolumeRequest {
  string source_id = 1;
  string name = 2;
  string pool = 3;
}

Example:

grpcurl -plaintext -d '{
  "source_id": "vol-abc123",
  "name": "data-01-clone",
  "pool": "default"
}' localhost:9002 pivirt.storage.v1.StorageService/CloneVolume

CreateSnapshot

message CreateSnapshotRequest {
  string volume_id = 1;
  string name = 2;
}

Example:

grpcurl -plaintext -d '{
  "volume_id": "vol-abc123",
  "name": "backup-01"
}' localhost:9002 pivirt.storage.v1.StorageService/CreateSnapshot

GetPoolStats

message GetPoolStatsRequest {
  string name = 1;
}

message PoolStats {
  string name = 1;
  int64 capacity_bytes = 2;
  int64 used_bytes = 3;
  int64 available_bytes = 4;
  int32 volume_count = 5;
  int32 snapshot_count = 6;
  double usage_percent = 7;
}

Example:

grpcurl -plaintext -d '{
  "name": "default"
}' localhost:9002 pivirt.storage.v1.StorageService/GetPoolStats

Error Codes

Code	Description
NOT_FOUND	Pool or volume not found
ALREADY_EXISTS	Pool or volume with same name exists
INVALID_ARGUMENT	Invalid pool/volume configuration
RESOURCE_EXHAUSTED	Insufficient storage space
FAILED_PRECONDITION	Volume in use, cannot delete

Related

• API Overview
• Storage Concepts
• pvcli Storage Commands
• iscsiman Component