diff --git a/apis/io-engine/protobuf/v1/pool.proto b/apis/io-engine/protobuf/v1/pool.proto index 62a8ff9..2392a41 100644 --- a/apis/io-engine/protobuf/v1/pool.proto +++ b/apis/io-engine/protobuf/v1/pool.proto @@ -16,6 +16,7 @@ service PoolRpc { rpc ExportPool (ExportPoolRequest) returns (google.protobuf.Empty) {} rpc ImportPool (ImportPoolRequest) returns (Pool) {} rpc ListPools (ListPoolOptions) returns (ListPoolsResponse) {} + rpc GrowPool (GrowPoolRequest) returns (GrowPoolResponse) {} } // Specifies the type of the pool @@ -33,14 +34,34 @@ message PoolTypeValue { // Create pool arguments. message CreatePoolRequest { - string name = 1; // name of the pool - google.protobuf.StringValue uuid = 2; // optional uuid for the pool to be created - repeated string disks = 3; // disk device paths or URIs to be claimed by the pool - PoolType pooltype = 4; // type of the pool + // Name of the pool. + string name = 1; + // Optional uuid for the pool to be created. + google.protobuf.StringValue uuid = 2; + // Disk device paths or URIs to be claimed by the pool. + repeated string disks = 3; + // Type of the pool. + PoolType pooltype = 4; // Default cluster size is 4MiB (4 * 1024 * 1024), input cluster size must be in "bytes" but // must be multiple of 1MiB, else default cluster size i.e 4MiB will be considered. Minimum // cluster size can be input as 1048576 (1024 * 1024) bytes (1MiB) optional uint32 cluster_size = 5; + // Hint for how much of the pool capacity should be reserved for metadata. + // This hint is ratio of the desired to the pool backend's default reservation. + // + // 1 is the default value, and it means to use the pool backend's default + // reservation amount. + // + // 0.5 means an attempt to reserve two times less capacity for the metadata than + // the backend would do by default, trading replica/snapshot count + // for the user data space. + // + // 2 means a battempt to reserve two times more space for the metadata than + // the backend would do by default, allowing pool to accomodate more + // replicas/snapshots by reducing user data capacity. + // + // A pool backend is allowed to ignore this hint. + optional float md_resv_hint = 6; } // Create pool arguments. @@ -61,15 +82,46 @@ enum PoolState { // Storage pool properties message Pool { - string uuid = 1; // uuid of the pool - string name = 2; // name of the pool - repeated string disks = 3; // absolute disk paths claimed by the pool - PoolState state = 4; // current state of the pool - uint64 capacity = 5; // size of the pool in bytes - uint64 used = 6; // used bytes from the pool - PoolType pooltype = 7; // type of the pool - uint64 committed = 8; // committed size of all pool replicas (sum of capacities of all replicas) - uint32 cluster_size = 9; // blobstor cluster size set (in bytes) during pool creation + // UUID of the storage pool. + string uuid = 1; + // Name of the storage pool. + string name = 2; + // Absolute path(s) of disk devices which are claimed by the pool. + repeated string disks = 3; + // Current state of the storage pool. + PoolState state = 4; + // Pool capacity in bytes available for user data. + uint64 capacity = 5; + // Storage capacity in bytes allocated for storing user data. + uint64 used = 6; + // Type of the pool. + PoolType pooltype = 7; + // Committed size of all pool's replicas: a sum of capacities of all replicas. + uint64 committed = 8; + // Cluster size in bytes. It defines the allocation granularity for replicas + // and snapshots. Cluster size can set during pool creation. + uint32 cluster_size = 9; + // Page size in bytes. This is the write and read granularity. + uint32 page_size = 10; + // Size of metadata allocation page in bytes. + uint32 md_page_size = 11; + // Number of metadata pages reserved on the pool for storing replica metadata. + // Metadata reservation capacity can be a limiting factor for the number + // of replicas and snaphots a pool can accommodate. + // Depending on the pool backend, this value can be defined on pool creation, + // or can dynamically change. + // If the pool backend does not support metadata capacity evaluation, zero is returned. + uint64 md_pages = 12; + // Number of metadata pages used for storing metadata for the currently + // existing replicas. + // If the pool backend does not support metadata capacity evaluation, zero is returned. + uint64 md_used_pages = 13; + // Usable capacity of the pool's underlying storage device(s). + // It changes when the device's capacity changes. + // This value is equal or large than the current pool capacity. If it is larger, + // pool can be grown to fill the entire device's capacity. + // If the pool backend does not support disk capacity evaluation, zero is returned. + uint64 disk_capacity = 14; } // Destroy pool arguments. @@ -94,3 +146,20 @@ message ListPoolOptions { PoolTypeValue pooltype = 2; // optional pooltype filter google.protobuf.StringValue uuid = 3; // get the pool matching the uuid if provided } + +// Grow pool arguments. +message GrowPoolRequest { + string name = 1; // name of the pool + google.protobuf.StringValue uuid = 2; // optional uuid for the pool to be grown +} + +// Grow pool response. +message GrowPoolResponse { + // Pool's state before expansion. + Pool previous_pool = 1; + // Pool's state after expansion. + // The difference between previous_pool and current_pool can be used + // to determine how much the pool has grown, and if the growth + // actually occurred. + Pool current_pool = 2; +} diff --git a/apis/io-engine/src/v1.rs b/apis/io-engine/src/v1.rs index fce5099..06d624b 100644 --- a/apis/io-engine/src/v1.rs +++ b/apis/io-engine/src/v1.rs @@ -36,8 +36,9 @@ pub mod pool { pub use super::pb::{ pool_rpc_client::PoolRpcClient, pool_rpc_server::{PoolRpc, PoolRpcServer}, - CreatePoolRequest, DestroyPoolRequest, ExportPoolRequest, ImportPoolRequest, - ListPoolOptions, ListPoolsResponse, Pool, PoolState, PoolType, PoolTypeValue, + CreatePoolRequest, DestroyPoolRequest, ExportPoolRequest, GrowPoolRequest, + GrowPoolResponse, ImportPoolRequest, ListPoolOptions, ListPoolsResponse, Pool, PoolState, + PoolType, PoolTypeValue, }; }