api.proto 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472
  1. syntax = "proto3";
  2. import "google/protobuf/timestamp.proto";
  3. package openstorage.api;
  4. option go_package = "api";
  5. option java_multiple_files = true;
  6. option java_package = "com.openstorage.api";
  7. enum Status {
  8. STATUS_NONE = 0;
  9. STATUS_INIT = 1;
  10. STATUS_OK = 2;
  11. STATUS_OFFLINE = 3;
  12. STATUS_ERROR = 4;
  13. STATUS_NOT_IN_QUORUM = 5;
  14. STATUS_DECOMMISSION = 6;
  15. STATUS_MAINTENANCE = 7;
  16. STATUS_STORAGE_DOWN = 8;
  17. STATUS_STORAGE_DEGRADED = 9;
  18. STATUS_NEEDS_REBOOT = 10;
  19. STATUS_STORAGE_REBALANCE = 11;
  20. STATUS_STORAGE_DRIVE_REPLACE = 12;
  21. // Add statuses before MAX and update the number for MAX
  22. STATUS_MAX = 13;
  23. }
  24. enum DriverType {
  25. DRIVER_TYPE_NONE = 0;
  26. DRIVER_TYPE_FILE = 1;
  27. DRIVER_TYPE_BLOCK = 2;
  28. DRIVER_TYPE_OBJECT = 3;
  29. DRIVER_TYPE_CLUSTERED = 4;
  30. DRIVER_TYPE_GRAPH = 5;
  31. }
  32. enum FSType {
  33. FS_TYPE_NONE = 0;
  34. FS_TYPE_BTRFS = 1;
  35. FS_TYPE_EXT4 = 2;
  36. FS_TYPE_FUSE = 3;
  37. FS_TYPE_NFS = 4;
  38. FS_TYPE_VFS = 5;
  39. FS_TYPE_XFS = 6;
  40. FS_TYPE_ZFS = 7;
  41. }
  42. enum GraphDriverChangeType {
  43. GRAPH_DRIVER_CHANGE_TYPE_NONE = 0;
  44. GRAPH_DRIVER_CHANGE_TYPE_MODIFIED = 1;
  45. GRAPH_DRIVER_CHANGE_TYPE_ADDED = 2;
  46. GRAPH_DRIVER_CHANGE_TYPE_DELETED = 3;
  47. }
  48. enum SeverityType {
  49. SEVERITY_TYPE_NONE = 0;
  50. SEVERITY_TYPE_ALARM = 1;
  51. SEVERITY_TYPE_WARNING = 2;
  52. SEVERITY_TYPE_NOTIFY = 3;
  53. }
  54. enum ResourceType {
  55. RESOURCE_TYPE_NONE = 0;
  56. RESOURCE_TYPE_VOLUME = 1;
  57. RESOURCE_TYPE_NODE = 2;
  58. RESOURCE_TYPE_CLUSTER = 3;
  59. RESOURCE_TYPE_DRIVE = 4;
  60. }
  61. enum AlertActionType {
  62. ALERT_ACTION_TYPE_NONE = 0;
  63. ALERT_ACTION_TYPE_DELETE = 1;
  64. ALERT_ACTION_TYPE_CREATE = 2;
  65. ALERT_ACTION_TYPE_UPDATE = 3;
  66. }
  67. enum VolumeActionParam {
  68. VOLUME_ACTION_PARAM_NONE = 0;
  69. // Maps to the boolean value false
  70. VOLUME_ACTION_PARAM_OFF = 1;
  71. // Maps to the boolean value true.
  72. VOLUME_ACTION_PARAM_ON = 2;
  73. }
  74. enum CosType {
  75. NONE = 0;
  76. LOW = 1;
  77. MEDIUM = 2;
  78. HIGH = 3;
  79. }
  80. enum IoProfile {
  81. IO_PROFILE_SEQUENTIAL = 0;
  82. IO_PROFILE_RANDOM= 1;
  83. IO_PROFILE_DB = 2;
  84. IO_PROFILE_DB_REMOTE = 3;
  85. }
  86. // VolumeState represents the state of a volume.
  87. enum VolumeState {
  88. VOLUME_STATE_NONE = 0;
  89. // Volume is transitioning to new state
  90. VOLUME_STATE_PENDING = 1;
  91. // Volume is ready to be assigned to a container
  92. VOLUME_STATE_AVAILABLE = 2;
  93. // Volume is attached to container
  94. VOLUME_STATE_ATTACHED = 3;
  95. // Volume is detached but associated with a container
  96. VOLUME_STATE_DETACHED = 4;
  97. // Volume detach is in progress
  98. VOLUME_STATE_DETATCHING = 5;
  99. // Volume is in error state
  100. VOLUME_STATE_ERROR = 6;
  101. // Volume is deleted, it will remain in this state
  102. // while resources are asynchronously reclaimed
  103. VOLUME_STATE_DELETED = 7;
  104. // Volume is trying to be detached
  105. VOLUME_STATE_TRY_DETACHING = 8;
  106. // Volume is undergoing restore
  107. VOLUME_STATE_RESTORE = 9;
  108. }
  109. // VolumeStatus represents a health status for a volume.
  110. enum VolumeStatus {
  111. VOLUME_STATUS_NONE = 0;
  112. // Volume is not present
  113. VOLUME_STATUS_NOT_PRESENT = 1;
  114. // Volume is healthy
  115. VOLUME_STATUS_UP = 2;
  116. // Volume is in fail mode
  117. VOLUME_STATUS_DOWN = 3;
  118. // Volume is up but with degraded performance
  119. // In a RAID group, this may indicate a problem with one or more drives
  120. VOLUME_STATUS_DEGRADED = 4;
  121. }
  122. enum StorageMedium {
  123. // Magnetic spinning disk.
  124. STORAGE_MEDIUM_MAGNETIC = 0;
  125. // SSD disk
  126. STORAGE_MEDIUM_SSD = 1;
  127. // NVME disk
  128. STORAGE_MEDIUM_NVME = 2;
  129. }
  130. enum ClusterNotify {
  131. // Node is down
  132. CLUSTER_NOTIFY_DOWN = 0;
  133. }
  134. enum AttachState {
  135. // Attached and available externally
  136. ATTACH_STATE_EXTERNAL = 0;
  137. // Attached but only available internally
  138. ATTACH_STATE_INTERNAL = 1;
  139. // Switching from External to Internal
  140. ATTACH_STATE_INTERNAL_SWITCH = 2;
  141. }
  142. // StorageResource groups properties of a storage device.
  143. message StorageResource {
  144. // Id is the LUN identifier.
  145. string id = 1;
  146. // Path device path for this storage resource.
  147. string path = 2;
  148. // Storage medium.
  149. StorageMedium medium = 3;
  150. // True if this device is online.
  151. bool online = 4;;
  152. // IOPS
  153. uint64 iops = 5;;
  154. // SeqWrite
  155. double seq_write = 6;
  156. // SeqRead
  157. double seq_read = 7;
  158. // RandRW
  159. double randRW = 8;
  160. // Total size in bytes.
  161. uint64 size = 9;;
  162. // Physical Bytes used.
  163. uint64 used = 10;
  164. // True if this device is rotational.
  165. string rotation_speed = 11;
  166. // Timestamp of last time this device was scanned.
  167. google.protobuf.Timestamp last_scan = 12;
  168. }
  169. // StoragePool groups different storage devices based on their CosType
  170. message StoragePool {
  171. // ID pool ID
  172. int32 ID = 1;
  173. // Cos reflects the capabilities of this drive pool
  174. CosType Cos = 2;
  175. // Medium underlying storage type
  176. StorageMedium Medium = 3;
  177. // RaidLevel storage raid level
  178. string RaidLevel = 4;
  179. // TotalSize of the pool
  180. uint64 TotalSize = 7;
  181. // Used size of the pool
  182. uint64 Used = 8;
  183. // Labels is a list of user defined name-value pairs
  184. map<string, string> labels = 9;
  185. }
  186. // VolumeLocator is a structure that is attached to a volume
  187. // and is used to carry opaque metadata.
  188. message VolumeLocator {
  189. // User friendly identifier
  190. string name = 1;
  191. // A set of name-value pairs that acts as search filters
  192. map<string, string> volume_labels = 2;
  193. }
  194. message Source {
  195. // A volume id, if specified will create a clone of the parent.
  196. string parent = 1;
  197. // Seed will seed the volume from the specified URI
  198. // Any additional config for the source comes from the labels in the spec
  199. string seed = 2;
  200. }
  201. message Group {
  202. // Id common identifier across volumes that have the same group.
  203. string id = 1;
  204. }
  205. // VolumeSpec has the properties needed to create a volume.
  206. message VolumeSpec {
  207. // Ephemeral storage
  208. bool ephemeral = 1;
  209. // Size specifies the thin provisioned volume size.
  210. uint64 size = 2;
  211. // Format specifies the filesystem for this volume.
  212. FSType format = 3;
  213. // BlockSize for the filesystem.
  214. int64 block_size = 4;
  215. // HaLevel specifies the number of copies of data.
  216. int64 ha_level = 5;
  217. // Cos specifies the relative class of service.
  218. CosType cos = 6;
  219. // IoProfile provides a hint about application using this volume.
  220. IoProfile io_profile = 7;
  221. // Dedupe specifies if the volume data is to be de-duplicated.
  222. bool dedupe = 8;
  223. // SnapshotInterval in minutes, set to 0 to disable snapshots
  224. uint32 snapshot_interval = 9;
  225. // VolumeLabels configuration labels
  226. map<string, string> volume_labels = 10;
  227. // Shared is true if this volume can be remotely accessed.
  228. bool shared = 11;
  229. // ReplicaSet is the desired set of nodes for the volume data.
  230. ReplicaSet replica_set = 12;
  231. // Aggregatiokn level Specifies the number of parts the volume can be aggregated from.
  232. uint32 aggregation_level = 13;
  233. // Encrypted is true if this volume will be cryptographically secured.
  234. bool encrypted = 14;
  235. // Passphrase for an encrypted volume
  236. string passphrase = 15;
  237. // SnapshotSchedule a well known string that specifies when snapshots should be taken.
  238. string snapshot_schedule = 16;
  239. // Scale allows autocreation of volumes.
  240. uint32 scale = 17;
  241. // Sticky volumes cannot be deleted until the flag is removed.
  242. bool sticky = 18;
  243. // Group identifies a consistency group
  244. Group group = 21;
  245. // GroupEnforced is true if consistency group creation is enforced.
  246. bool group_enforced = 22;
  247. // Compressed is true if this volume is to be compressed.
  248. bool compressed = 23;
  249. }
  250. // ReplicaSet set of machine IDs (nodes) to which part of this volume is erasure
  251. // coded - for clustered storage arrays
  252. message ReplicaSet {
  253. repeated string nodes = 1;
  254. }
  255. // RuntimeStateMap is a list of name value mapping of driver specific runtime
  256. // information.
  257. message RuntimeStateMap {
  258. map<string, string> runtime_state = 1;
  259. }
  260. // Volume represents an abstract storage volume.
  261. // Volume represents an abstract storage volume.
  262. message Volume {
  263. // Self referential volume ID.
  264. string id = 1;
  265. // Source specified seed data for the volume.
  266. Source source = 2;
  267. // Group volumes in the same group have the same group id.
  268. Group group = 3;
  269. // Readonly is true if this volume is to be mounted with readonly access.
  270. bool readonly = 4;
  271. // User specified locator
  272. VolumeLocator locator = 5;
  273. // Volume creation time
  274. google.protobuf.Timestamp ctime = 6;
  275. // User specified VolumeSpec
  276. VolumeSpec spec = 7;
  277. // Usage is bytes consumed by vtheis volume.
  278. uint64 usage = 8;
  279. // LastScan is the time when an integrity check was run.
  280. google.protobuf.Timestamp last_scan = 9;
  281. // Format specifies the filesytem for this volume.
  282. FSType format = 10;
  283. // Status is the availability status of this volume.
  284. VolumeStatus status = 11;
  285. // State is the current runtime state of this volume.
  286. VolumeState state = 12;
  287. // AttachedOn is the node instance identifier for clustered systems.
  288. string attached_on = 13;
  289. // AttachedState shows whether the device is attached for internal or external use.
  290. AttachState attached_state = 14;
  291. // DevicePath is the device exported by block device implementations.
  292. string device_path = 15;
  293. // SecureDevicePath is the device path for an encrypted volume.
  294. string secure_device_path = 16;
  295. // AttachPath is the mounted path in the host namespace.
  296. repeated string attach_path = 17;
  297. // AttachInfo is a list of name value mappings that provides attach information.
  298. map<string, string> attach_info = 18;
  299. // ReplicatSets storage for this volumefor clustered storage arrays.
  300. repeated ReplicaSet replica_sets = 19;
  301. // RuntimeState is a lst of name value mapping of driver specific runtime
  302. // information.
  303. repeated RuntimeStateMap runtime_state = 20;
  304. // Error is the Last recorded error.
  305. string error = 21;
  306. }
  307. message Stats {
  308. // Reads completed successfully
  309. uint64 reads = 1;
  310. // Time spent in reads in ms
  311. uint64 read_ms = 2;
  312. uint64 read_bytes = 3;
  313. // Writes completed successfully
  314. uint64 writes = 4;
  315. // Time spent in writes in ms
  316. uint64 write_ms = 5;
  317. uint64 write_bytes = 6;
  318. // IOs curently in progress
  319. uint64 io_progress = 7;
  320. // Time spent doing IOs ms
  321. uint64 io_ms = 8;
  322. // BytesUsed
  323. uint64 bytes_used = 9;
  324. // Interval in ms during which stats were collected
  325. uint64 interval_ms = 10;
  326. }
  327. message Alert {
  328. // Id for Alert
  329. int64 id = 1;
  330. // Severity of the Alert
  331. SeverityType severity = 2;
  332. // AlertType user defined alert type
  333. int64 alert_type = 3;
  334. // Message describing the Alert
  335. string message = 4;
  336. //Timestamp when Alert occured
  337. google.protobuf.Timestamp timestamp = 5;
  338. // ResourceId where Alert occured
  339. string resource_id = 6;
  340. // Resource where Alert occured
  341. ResourceType resource = 7;
  342. // Cleared Flag
  343. bool cleared = 8;
  344. // TTL in seconds for this Alert
  345. uint64 ttl = 9;
  346. // UniqueTag helps identify a unique alert for a given resouce
  347. string unique_tag = 10;
  348. }
  349. message Alerts {
  350. repeated Alert alert = 1;
  351. }
  352. message VolumeCreateRequest {
  353. // User specified volume name and labels
  354. VolumeLocator locator = 1;
  355. // Source to create volume
  356. Source source = 2;
  357. // The storage spec for the volume
  358. VolumeSpec spec = 3;
  359. }
  360. message VolumeResponse {
  361. string error = 1;
  362. }
  363. message VolumeCreateResponse {
  364. // ID of the newly created volume
  365. string id = 1;
  366. VolumeResponse volume_response = 2;
  367. }
  368. // VolumeStateAction specifies desired actions.
  369. message VolumeStateAction {
  370. // Attach or Detach volume
  371. VolumeActionParam attach = 1;
  372. // Mount or unmount volume
  373. VolumeActionParam mount = 2;
  374. // MountPath Path where the device is mounted
  375. string mount_path = 3;
  376. // DevicePath Path returned in attach
  377. string device_path = 4;
  378. // UnmountBeforeDetach is used to check whether unmount should be done before
  379. // a detach
  380. bool unmount_before_detach = 5;
  381. }
  382. message VolumeSetRequest {
  383. // User specified volume name and labels
  384. VolumeLocator locator = 1;
  385. // The storage spec for the volume
  386. VolumeSpec spec = 2;
  387. // State modification on this volume.
  388. VolumeStateAction action = 3;
  389. // additional options
  390. // required for the Set operation.
  391. map<string, string> options = 4;
  392. }
  393. message VolumeSetResponse {
  394. Volume volume = 1;
  395. VolumeResponse volume_response = 2;
  396. }
  397. message SnapCreateRequest {
  398. // volume id
  399. string id = 1;
  400. VolumeLocator locator = 2;
  401. bool readonly = 3;
  402. }
  403. message SnapCreateResponse {
  404. VolumeCreateResponse volume_create_response = 1;
  405. }
  406. message VolumeInfo {
  407. string volume_id = 1;
  408. string path = 2;
  409. VolumeSpec storage = 3;
  410. }
  411. // GraphDriverChanges represent a list of changes between the filesystem layers
  412. // specified by the ID and Parent. // Parent may be an empty string, in which
  413. // case there is no parent.
  414. // Where the Path is the filesystem path within the layered filesystem
  415. message GraphDriverChanges {
  416. string path = 1;
  417. GraphDriverChangeType kind = 2;
  418. }
  419. message ClusterResponse {
  420. string error = 1;
  421. }
  422. message ActiveRequest {
  423. map<int64, string> ReqestKV = 1;
  424. }
  425. message ActiveRequests {
  426. int64 RequestCount = 1;
  427. repeated ActiveRequest ActiveRequest = 2;
  428. }