1syntax = "proto3";
2package etcdserverpb;
3
4import "gogoproto/gogo.proto";
5import "etcd/api/mvccpb/kv.proto";
6import "etcd/api/authpb/auth.proto";
7
8// for grpc-gateway
9import "google/api/annotations.proto";
10
11option (gogoproto.marshaler_all) = true;
12option (gogoproto.unmarshaler_all) = true;
13
14service KV {
15 // Range gets the keys in the range from the key-value store.
16 rpc Range(RangeRequest) returns (RangeResponse) {
17 option (google.api.http) = {
18 post: "/v3/kv/range"
19 body: "*"
20 };
21 }
22
23 // Put puts the given key into the key-value store.
24 // A put request increments the revision of the key-value store
25 // and generates one event in the event history.
26 rpc Put(PutRequest) returns (PutResponse) {
27 option (google.api.http) = {
28 post: "/v3/kv/put"
29 body: "*"
30 };
31 }
32
33 // DeleteRange deletes the given range from the key-value store.
34 // A delete request increments the revision of the key-value store
35 // and generates a delete event in the event history for every deleted key.
36 rpc DeleteRange(DeleteRangeRequest) returns (DeleteRangeResponse) {
37 option (google.api.http) = {
38 post: "/v3/kv/deleterange"
39 body: "*"
40 };
41 }
42
43 // Txn processes multiple requests in a single transaction.
44 // A txn request increments the revision of the key-value store
45 // and generates events with the same revision for every completed request.
46 // It is not allowed to modify the same key several times within one txn.
47 rpc Txn(TxnRequest) returns (TxnResponse) {
48 option (google.api.http) = {
49 post: "/v3/kv/txn"
50 body: "*"
51 };
52 }
53
54 // Compact compacts the event history in the etcd key-value store. The key-value
55 // store should be periodically compacted or the event history will continue to grow
56 // indefinitely.
57 rpc Compact(CompactionRequest) returns (CompactionResponse) {
58 option (google.api.http) = {
59 post: "/v3/kv/compaction"
60 body: "*"
61 };
62 }
63}
64
65service Watch {
66 // Watch watches for events happening or that have happened. Both input and output
67 // are streams; the input stream is for creating and canceling watchers and the output
68 // stream sends events. One watch RPC can watch on multiple key ranges, streaming events
69 // for several watches at once. The entire event history can be watched starting from the
70 // last compaction revision.
71 rpc Watch(stream WatchRequest) returns (stream WatchResponse) {
72 option (google.api.http) = {
73 post: "/v3/watch"
74 body: "*"
75 };
76 }
77}
78
79service Lease {
80 // LeaseGrant creates a lease which expires if the server does not receive a keepAlive
81 // within a given time to live period. All keys attached to the lease will be expired and
82 // deleted if the lease expires. Each expired key generates a delete event in the event history.
83 rpc LeaseGrant(LeaseGrantRequest) returns (LeaseGrantResponse) {
84 option (google.api.http) = {
85 post: "/v3/lease/grant"
86 body: "*"
87 };
88 }
89
90 // LeaseRevoke revokes a lease. All keys attached to the lease will expire and be deleted.
91 rpc LeaseRevoke(LeaseRevokeRequest) returns (LeaseRevokeResponse) {
92 option (google.api.http) = {
93 post: "/v3/lease/revoke"
94 body: "*"
95 additional_bindings {
96 post: "/v3/kv/lease/revoke"
97 body: "*"
98 }
99 };
100 }
101
102 // LeaseKeepAlive keeps the lease alive by streaming keep alive requests from the client
103 // to the server and streaming keep alive responses from the server to the client.
104 rpc LeaseKeepAlive(stream LeaseKeepAliveRequest) returns (stream LeaseKeepAliveResponse) {
105 option (google.api.http) = {
106 post: "/v3/lease/keepalive"
107 body: "*"
108 };
109 }
110
111 // LeaseTimeToLive retrieves lease information.
112 rpc LeaseTimeToLive(LeaseTimeToLiveRequest) returns (LeaseTimeToLiveResponse) {
113 option (google.api.http) = {
114 post: "/v3/lease/timetolive"
115 body: "*"
116 additional_bindings {
117 post: "/v3/kv/lease/timetolive"
118 body: "*"
119 }
120 };
121 }
122
123 // LeaseLeases lists all existing leases.
124 rpc LeaseLeases(LeaseLeasesRequest) returns (LeaseLeasesResponse) {
125 option (google.api.http) = {
126 post: "/v3/lease/leases"
127 body: "*"
128 additional_bindings {
129 post: "/v3/kv/lease/leases"
130 body: "*"
131 }
132 };
133 }
134}
135
136service Cluster {
137 // MemberAdd adds a member into the cluster.
138 rpc MemberAdd(MemberAddRequest) returns (MemberAddResponse) {
139 option (google.api.http) = {
140 post: "/v3/cluster/member/add"
141 body: "*"
142 };
143 }
144
145 // MemberRemove removes an existing member from the cluster.
146 rpc MemberRemove(MemberRemoveRequest) returns (MemberRemoveResponse) {
147 option (google.api.http) = {
148 post: "/v3/cluster/member/remove"
149 body: "*"
150 };
151 }
152
153 // MemberUpdate updates the member configuration.
154 rpc MemberUpdate(MemberUpdateRequest) returns (MemberUpdateResponse) {
155 option (google.api.http) = {
156 post: "/v3/cluster/member/update"
157 body: "*"
158 };
159 }
160
161 // MemberList lists all the members in the cluster.
162 rpc MemberList(MemberListRequest) returns (MemberListResponse) {
163 option (google.api.http) = {
164 post: "/v3/cluster/member/list"
165 body: "*"
166 };
167 }
168
169 // MemberPromote promotes a member from raft learner (non-voting) to raft voting member.
170 rpc MemberPromote(MemberPromoteRequest) returns (MemberPromoteResponse) {
171 option (google.api.http) = {
172 post: "/v3/cluster/member/promote"
173 body: "*"
174 };
175 }
176}
177
178service Maintenance {
179 // Alarm activates, deactivates, and queries alarms regarding cluster health.
180 rpc Alarm(AlarmRequest) returns (AlarmResponse) {
181 option (google.api.http) = {
182 post: "/v3/maintenance/alarm"
183 body: "*"
184 };
185 }
186
187 // Status gets the status of the member.
188 rpc Status(StatusRequest) returns (StatusResponse) {
189 option (google.api.http) = {
190 post: "/v3/maintenance/status"
191 body: "*"
192 };
193 }
194
195 // Defragment defragments a member's backend database to recover storage space.
196 rpc Defragment(DefragmentRequest) returns (DefragmentResponse) {
197 option (google.api.http) = {
198 post: "/v3/maintenance/defragment"
199 body: "*"
200 };
201 }
202
203 // Hash computes the hash of whole backend keyspace,
204 // including key, lease, and other buckets in storage.
205 // This is designed for testing ONLY!
206 // Do not rely on this in production with ongoing transactions,
207 // since Hash operation does not hold MVCC locks.
208 // Use "HashKV" API instead for "key" bucket consistency checks.
209 rpc Hash(HashRequest) returns (HashResponse) {
210 option (google.api.http) = {
211 post: "/v3/maintenance/hash"
212 body: "*"
213 };
214 }
215
216 // HashKV computes the hash of all MVCC keys up to a given revision.
217 // It only iterates "key" bucket in backend storage.
218 rpc HashKV(HashKVRequest) returns (HashKVResponse) {
219 option (google.api.http) = {
220 post: "/v3/maintenance/hashkv"
221 body: "*"
222 };
223 }
224
225 // Snapshot sends a snapshot of the entire backend from a member over a stream to a client.
226 rpc Snapshot(SnapshotRequest) returns (stream SnapshotResponse) {
227 option (google.api.http) = {
228 post: "/v3/maintenance/snapshot"
229 body: "*"
230 };
231 }
232
233 // MoveLeader requests current leader node to transfer its leadership to transferee.
234 rpc MoveLeader(MoveLeaderRequest) returns (MoveLeaderResponse) {
235 option (google.api.http) = {
236 post: "/v3/maintenance/transfer-leadership"
237 body: "*"
238 };
239 }
240
241 // Downgrade requests downgrades, verifies feasibility or cancels downgrade
242 // on the cluster version.
243 // Supported since etcd 3.5.
244 rpc Downgrade(DowngradeRequest) returns (DowngradeResponse) {
245 option (google.api.http) = {
246 post: "/v3/maintenance/downgrade"
247 body: "*"
248 };
249 }
250}
251
252service Auth {
253 // AuthEnable enables authentication.
254 rpc AuthEnable(AuthEnableRequest) returns (AuthEnableResponse) {
255 option (google.api.http) = {
256 post: "/v3/auth/enable"
257 body: "*"
258 };
259 }
260
261 // AuthDisable disables authentication.
262 rpc AuthDisable(AuthDisableRequest) returns (AuthDisableResponse) {
263 option (google.api.http) = {
264 post: "/v3/auth/disable"
265 body: "*"
266 };
267 }
268
269 // AuthStatus displays authentication status.
270 rpc AuthStatus(AuthStatusRequest) returns (AuthStatusResponse) {
271 option (google.api.http) = {
272 post: "/v3/auth/status"
273 body: "*"
274 };
275 }
276
277 // Authenticate processes an authenticate request.
278 rpc Authenticate(AuthenticateRequest) returns (AuthenticateResponse) {
279 option (google.api.http) = {
280 post: "/v3/auth/authenticate"
281 body: "*"
282 };
283 }
284
285 // UserAdd adds a new user. User name cannot be empty.
286 rpc UserAdd(AuthUserAddRequest) returns (AuthUserAddResponse) {
287 option (google.api.http) = {
288 post: "/v3/auth/user/add"
289 body: "*"
290 };
291 }
292
293 // UserGet gets detailed user information.
294 rpc UserGet(AuthUserGetRequest) returns (AuthUserGetResponse) {
295 option (google.api.http) = {
296 post: "/v3/auth/user/get"
297 body: "*"
298 };
299 }
300
301 // UserList gets a list of all users.
302 rpc UserList(AuthUserListRequest) returns (AuthUserListResponse) {
303 option (google.api.http) = {
304 post: "/v3/auth/user/list"
305 body: "*"
306 };
307 }
308
309 // UserDelete deletes a specified user.
310 rpc UserDelete(AuthUserDeleteRequest) returns (AuthUserDeleteResponse) {
311 option (google.api.http) = {
312 post: "/v3/auth/user/delete"
313 body: "*"
314 };
315 }
316
317 // UserChangePassword changes the password of a specified user.
318 rpc UserChangePassword(AuthUserChangePasswordRequest) returns (AuthUserChangePasswordResponse) {
319 option (google.api.http) = {
320 post: "/v3/auth/user/changepw"
321 body: "*"
322 };
323 }
324
325 // UserGrant grants a role to a specified user.
326 rpc UserGrantRole(AuthUserGrantRoleRequest) returns (AuthUserGrantRoleResponse) {
327 option (google.api.http) = {
328 post: "/v3/auth/user/grant"
329 body: "*"
330 };
331 }
332
333 // UserRevokeRole revokes a role of specified user.
334 rpc UserRevokeRole(AuthUserRevokeRoleRequest) returns (AuthUserRevokeRoleResponse) {
335 option (google.api.http) = {
336 post: "/v3/auth/user/revoke"
337 body: "*"
338 };
339 }
340
341 // RoleAdd adds a new role. Role name cannot be empty.
342 rpc RoleAdd(AuthRoleAddRequest) returns (AuthRoleAddResponse) {
343 option (google.api.http) = {
344 post: "/v3/auth/role/add"
345 body: "*"
346 };
347 }
348
349 // RoleGet gets detailed role information.
350 rpc RoleGet(AuthRoleGetRequest) returns (AuthRoleGetResponse) {
351 option (google.api.http) = {
352 post: "/v3/auth/role/get"
353 body: "*"
354 };
355 }
356
357 // RoleList gets lists of all roles.
358 rpc RoleList(AuthRoleListRequest) returns (AuthRoleListResponse) {
359 option (google.api.http) = {
360 post: "/v3/auth/role/list"
361 body: "*"
362 };
363 }
364
365 // RoleDelete deletes a specified role.
366 rpc RoleDelete(AuthRoleDeleteRequest) returns (AuthRoleDeleteResponse) {
367 option (google.api.http) = {
368 post: "/v3/auth/role/delete"
369 body: "*"
370 };
371 }
372
373 // RoleGrantPermission grants a permission of a specified key or range to a specified role.
374 rpc RoleGrantPermission(AuthRoleGrantPermissionRequest) returns (AuthRoleGrantPermissionResponse) {
375 option (google.api.http) = {
376 post: "/v3/auth/role/grant"
377 body: "*"
378 };
379 }
380
381 // RoleRevokePermission revokes a key or range permission of a specified role.
382 rpc RoleRevokePermission(AuthRoleRevokePermissionRequest) returns (AuthRoleRevokePermissionResponse) {
383 option (google.api.http) = {
384 post: "/v3/auth/role/revoke"
385 body: "*"
386 };
387 }
388}
389
390message ResponseHeader {
391 // cluster_id is the ID of the cluster which sent the response.
392 uint64 cluster_id = 1;
393 // member_id is the ID of the member which sent the response.
394 uint64 member_id = 2;
395 // revision is the key-value store revision when the request was applied.
396 // For watch progress responses, the header.revision indicates progress. All future events
397 // recieved in this stream are guaranteed to have a higher revision number than the
398 // header.revision number.
399 int64 revision = 3;
400 // raft_term is the raft term when the request was applied.
401 uint64 raft_term = 4;
402}
403
404message RangeRequest {
405 enum SortOrder {
406 NONE = 0; // default, no sorting
407 ASCEND = 1; // lowest target value first
408 DESCEND = 2; // highest target value first
409 }
410 enum SortTarget {
411 KEY = 0;
412 VERSION = 1;
413 CREATE = 2;
414 MOD = 3;
415 VALUE = 4;
416 }
417
418 // key is the first key for the range. If range_end is not given, the request only looks up key.
419 bytes key = 1;
420 // range_end is the upper bound on the requested range [key, range_end).
421 // If range_end is '\0', the range is all keys >= key.
422 // If range_end is key plus one (e.g., "aa"+1 == "ab", "a\xff"+1 == "b"),
423 // then the range request gets all keys prefixed with key.
424 // If both key and range_end are '\0', then the range request returns all keys.
425 bytes range_end = 2;
426 // limit is a limit on the number of keys returned for the request. When limit is set to 0,
427 // it is treated as no limit.
428 int64 limit = 3;
429 // revision is the point-in-time of the key-value store to use for the range.
430 // If revision is less or equal to zero, the range is over the newest key-value store.
431 // If the revision has been compacted, ErrCompacted is returned as a response.
432 int64 revision = 4;
433
434 // sort_order is the order for returned sorted results.
435 SortOrder sort_order = 5;
436
437 // sort_target is the key-value field to use for sorting.
438 SortTarget sort_target = 6;
439
440 // serializable sets the range request to use serializable member-local reads.
441 // Range requests are linearizable by default; linearizable requests have higher
442 // latency and lower throughput than serializable requests but reflect the current
443 // consensus of the cluster. For better performance, in exchange for possible stale reads,
444 // a serializable range request is served locally without needing to reach consensus
445 // with other nodes in the cluster.
446 bool serializable = 7;
447
448 // keys_only when set returns only the keys and not the values.
449 bool keys_only = 8;
450
451 // count_only when set returns only the count of the keys in the range.
452 bool count_only = 9;
453
454 // min_mod_revision is the lower bound for returned key mod revisions; all keys with
455 // lesser mod revisions will be filtered away.
456 int64 min_mod_revision = 10;
457
458 // max_mod_revision is the upper bound for returned key mod revisions; all keys with
459 // greater mod revisions will be filtered away.
460 int64 max_mod_revision = 11;
461
462 // min_create_revision is the lower bound for returned key create revisions; all keys with
463 // lesser create revisions will be filtered away.
464 int64 min_create_revision = 12;
465
466 // max_create_revision is the upper bound for returned key create revisions; all keys with
467 // greater create revisions will be filtered away.
468 int64 max_create_revision = 13;
469}
470
471message RangeResponse {
472 ResponseHeader header = 1;
473 // kvs is the list of key-value pairs matched by the range request.
474 // kvs is empty when count is requested.
475 repeated mvccpb.KeyValue kvs = 2;
476 // more indicates if there are more keys to return in the requested range.
477 bool more = 3;
478 // count is set to the number of keys within the range when requested.
479 int64 count = 4;
480}
481
482message PutRequest {
483 // key is the key, in bytes, to put into the key-value store.
484 bytes key = 1;
485 // value is the value, in bytes, to associate with the key in the key-value store.
486 bytes value = 2;
487 // lease is the lease ID to associate with the key in the key-value store. A lease
488 // value of 0 indicates no lease.
489 int64 lease = 3;
490
491 // If prev_kv is set, etcd gets the previous key-value pair before changing it.
492 // The previous key-value pair will be returned in the put response.
493 bool prev_kv = 4;
494
495 // If ignore_value is set, etcd updates the key using its current value.
496 // Returns an error if the key does not exist.
497 bool ignore_value = 5;
498
499 // If ignore_lease is set, etcd updates the key using its current lease.
500 // Returns an error if the key does not exist.
501 bool ignore_lease = 6;
502}
503
504message PutResponse {
505 ResponseHeader header = 1;
506 // if prev_kv is set in the request, the previous key-value pair will be returned.
507 mvccpb.KeyValue prev_kv = 2;
508}
509
510message DeleteRangeRequest {
511 // key is the first key to delete in the range.
512 bytes key = 1;
513 // range_end is the key following the last key to delete for the range [key, range_end).
514 // If range_end is not given, the range is defined to contain only the key argument.
515 // If range_end is one bit larger than the given key, then the range is all the keys
516 // with the prefix (the given key).
517 // If range_end is '\0', the range is all keys greater than or equal to the key argument.
518 bytes range_end = 2;
519
520 // If prev_kv is set, etcd gets the previous key-value pairs before deleting it.
521 // The previous key-value pairs will be returned in the delete response.
522 bool prev_kv = 3;
523}
524
525message DeleteRangeResponse {
526 ResponseHeader header = 1;
527 // deleted is the number of keys deleted by the delete range request.
528 int64 deleted = 2;
529 // if prev_kv is set in the request, the previous key-value pairs will be returned.
530 repeated mvccpb.KeyValue prev_kvs = 3;
531}
532
533message RequestOp {
534 // request is a union of request types accepted by a transaction.
535 oneof request {
536 RangeRequest request_range = 1;
537 PutRequest request_put = 2;
538 DeleteRangeRequest request_delete_range = 3;
539 TxnRequest request_txn = 4;
540 }
541}
542
543message ResponseOp {
544 // response is a union of response types returned by a transaction.
545 oneof response {
546 RangeResponse response_range = 1;
547 PutResponse response_put = 2;
548 DeleteRangeResponse response_delete_range = 3;
549 TxnResponse response_txn = 4;
550 }
551}
552
553message Compare {
554 enum CompareResult {
555 EQUAL = 0;
556 GREATER = 1;
557 LESS = 2;
558 NOT_EQUAL = 3;
559 }
560 enum CompareTarget {
561 VERSION = 0;
562 CREATE = 1;
563 MOD = 2;
564 VALUE = 3;
565 LEASE = 4;
566 }
567 // result is logical comparison operation for this comparison.
568 CompareResult result = 1;
569 // target is the key-value field to inspect for the comparison.
570 CompareTarget target = 2;
571 // key is the subject key for the comparison operation.
572 bytes key = 3;
573 oneof target_union {
574 // version is the version of the given key
575 int64 version = 4;
576 // create_revision is the creation revision of the given key
577 int64 create_revision = 5;
578 // mod_revision is the last modified revision of the given key.
579 int64 mod_revision = 6;
580 // value is the value of the given key, in bytes.
581 bytes value = 7;
582 // lease is the lease id of the given key.
583 int64 lease = 8;
584 // leave room for more target_union field tags, jump to 64
585 }
586
587 // range_end compares the given target to all keys in the range [key, range_end).
588 // See RangeRequest for more details on key ranges.
589 bytes range_end = 64;
590 // TODO: fill out with most of the rest of RangeRequest fields when needed.
591}
592
593// From google paxosdb paper:
594// Our implementation hinges around a powerful primitive which we call MultiOp. All other database
595// operations except for iteration are implemented as a single call to MultiOp. A MultiOp is applied atomically
596// and consists of three components:
597// 1. A list of tests called guard. Each test in guard checks a single entry in the database. It may check
598// for the absence or presence of a value, or compare with a given value. Two different tests in the guard
599// may apply to the same or different entries in the database. All tests in the guard are applied and
600// MultiOp returns the results. If all tests are true, MultiOp executes t op (see item 2 below), otherwise
601// it executes f op (see item 3 below).
602// 2. A list of database operations called t op. Each operation in the list is either an insert, delete, or
603// lookup operation, and applies to a single database entry. Two different operations in the list may apply
604// to the same or different entries in the database. These operations are executed
605// if guard evaluates to
606// true.
607// 3. A list of database operations called f op. Like t op, but executed if guard evaluates to false.
608message TxnRequest {
609 // compare is a list of predicates representing a conjunction of terms.
610 // If the comparisons succeed, then the success requests will be processed in order,
611 // and the response will contain their respective responses in order.
612 // If the comparisons fail, then the failure requests will be processed in order,
613 // and the response will contain their respective responses in order.
614 repeated Compare compare = 1;
615 // success is a list of requests which will be applied when compare evaluates to true.
616 repeated RequestOp success = 2;
617 // failure is a list of requests which will be applied when compare evaluates to false.
618 repeated RequestOp failure = 3;
619}
620
621message TxnResponse {
622 ResponseHeader header = 1;
623 // succeeded is set to true if the compare evaluated to true or false otherwise.
624 bool succeeded = 2;
625 // responses is a list of responses corresponding to the results from applying
626 // success if succeeded is true or failure if succeeded is false.
627 repeated ResponseOp responses = 3;
628}
629
630// CompactionRequest compacts the key-value store up to a given revision. All superseded keys
631// with a revision less than the compaction revision will be removed.
632message CompactionRequest {
633 // revision is the key-value store revision for the compaction operation.
634 int64 revision = 1;
635 // physical is set so the RPC will wait until the compaction is physically
636 // applied to the local database such that compacted entries are totally
637 // removed from the backend database.
638 bool physical = 2;
639}
640
641message CompactionResponse {
642 ResponseHeader header = 1;
643}
644
645message HashRequest {
646}
647
648message HashKVRequest {
649 // revision is the key-value store revision for the hash operation.
650 int64 revision = 1;
651}
652
653message HashKVResponse {
654 ResponseHeader header = 1;
655 // hash is the hash value computed from the responding member's MVCC keys up to a given revision.
656 uint32 hash = 2;
657 // compact_revision is the compacted revision of key-value store when hash begins.
658 int64 compact_revision = 3;
659}
660
661message HashResponse {
662 ResponseHeader header = 1;
663 // hash is the hash value computed from the responding member's KV's backend.
664 uint32 hash = 2;
665}
666
667message SnapshotRequest {
668}
669
670message SnapshotResponse {
671 // header has the current key-value store information. The first header in the snapshot
672 // stream indicates the point in time of the snapshot.
673 ResponseHeader header = 1;
674
675 // remaining_bytes is the number of blob bytes to be sent after this message
676 uint64 remaining_bytes = 2;
677
678 // blob contains the next chunk of the snapshot in the snapshot stream.
679 bytes blob = 3;
680}
681
682message WatchRequest {
683 // request_union is a request to either create a new watcher or cancel an existing watcher.
684 oneof request_union {
685 WatchCreateRequest create_request = 1;
686 WatchCancelRequest cancel_request = 2;
687 WatchProgressRequest progress_request = 3;
688 }
689}
690
691message WatchCreateRequest {
692 // key is the key to register for watching.
693 bytes key = 1;
694
695 // range_end is the end of the range [key, range_end) to watch. If range_end is not given,
696 // only the key argument is watched. If range_end is equal to '\0', all keys greater than
697 // or equal to the key argument are watched.
698 // If the range_end is one bit larger than the given key,
699 // then all keys with the prefix (the given key) will be watched.
700 bytes range_end = 2;
701
702 // start_revision is an optional revision to watch from (inclusive). No start_revision is "now".
703 int64 start_revision = 3;
704
705 // progress_notify is set so that the etcd server will periodically send a WatchResponse with
706 // no events to the new watcher if there are no recent events. It is useful when clients
707 // wish to recover a disconnected watcher starting from a recent known revision.
708 // The etcd server may decide how often it will send notifications based on current load.
709 bool progress_notify = 4;
710
711 enum FilterType {
712 // filter out put event.
713 NOPUT = 0;
714 // filter out delete event.
715 NODELETE = 1;
716 }
717
718 // filters filter the events at server side before it sends back to the watcher.
719 repeated FilterType filters = 5;
720
721 // If prev_kv is set, created watcher gets the previous KV before the event happens.
722 // If the previous KV is already compacted, nothing will be returned.
723 bool prev_kv = 6;
724
725 // If watch_id is provided and non-zero, it will be assigned to this watcher.
726 // Since creating a watcher in etcd is not a synchronous operation,
727 // this can be used ensure that ordering is correct when creating multiple
728 // watchers on the same stream. Creating a watcher with an ID already in
729 // use on the stream will cause an error to be returned.
730 int64 watch_id = 7;
731
732 // fragment enables splitting large revisions into multiple watch responses.
733 bool fragment = 8;
734}
735
736message WatchCancelRequest {
737 // watch_id is the watcher id to cancel so that no more events are transmitted.
738 int64 watch_id = 1;
739}
740
741// Requests the a watch stream progress status be sent in the watch response stream as soon as
742// possible.
743message WatchProgressRequest {
744}
745
746message WatchResponse {
747 ResponseHeader header = 1;
748 // watch_id is the ID of the watcher that corresponds to the response.
749 int64 watch_id = 2;
750
751 // created is set to true if the response is for a create watch request.
752 // The client should record the watch_id and expect to receive events for
753 // the created watcher from the same stream.
754 // All events sent to the created watcher will attach with the same watch_id.
755 bool created = 3;
756
757 // canceled is set to true if the response is for a cancel watch request.
758 // No further events will be sent to the canceled watcher.
759 bool canceled = 4;
760
761 // compact_revision is set to the minimum index if a watcher tries to watch
762 // at a compacted index.
763 //
764 // This happens when creating a watcher at a compacted revision or the watcher cannot
765 // catch up with the progress of the key-value store.
766 //
767 // The client should treat the watcher as canceled and should not try to create any
768 // watcher with the same start_revision again.
769 int64 compact_revision = 5;
770
771 // cancel_reason indicates the reason for canceling the watcher.
772 string cancel_reason = 6;
773
774 // framgment is true if large watch response was split over multiple responses.
775 bool fragment = 7;
776
777 repeated mvccpb.Event events = 11;
778}
779
780message LeaseGrantRequest {
781 // TTL is the advisory time-to-live in seconds. Expired lease will return -1.
782 int64 TTL = 1;
783 // ID is the requested ID for the lease. If ID is set to 0, the lessor chooses an ID.
784 int64 ID = 2;
785}
786
787message LeaseGrantResponse {
788 ResponseHeader header = 1;
789 // ID is the lease ID for the granted lease.
790 int64 ID = 2;
791 // TTL is the server chosen lease time-to-live in seconds.
792 int64 TTL = 3;
793 string error = 4;
794}
795
796message LeaseRevokeRequest {
797 // ID is the lease ID to revoke. When the ID is revoked, all associated keys will be deleted.
798 int64 ID = 1;
799}
800
801message LeaseRevokeResponse {
802 ResponseHeader header = 1;
803}
804
805message LeaseCheckpoint {
806 // ID is the lease ID to checkpoint.
807 int64 ID = 1;
808
809 // Remaining_TTL is the remaining time until expiry of the lease.
810 int64 remaining_TTL = 2;
811}
812
813message LeaseCheckpointRequest {
814 repeated LeaseCheckpoint checkpoints = 1;
815}
816
817message LeaseCheckpointResponse {
818 ResponseHeader header = 1;
819}
820
821message LeaseKeepAliveRequest {
822 // ID is the lease ID for the lease to keep alive.
823 int64 ID = 1;
824}
825
826message LeaseKeepAliveResponse {
827 ResponseHeader header = 1;
828 // ID is the lease ID from the keep alive request.
829 int64 ID = 2;
830 // TTL is the new time-to-live for the lease.
831 int64 TTL = 3;
832}
833
834message LeaseTimeToLiveRequest {
835 // ID is the lease ID for the lease.
836 int64 ID = 1;
837 // keys is true to query all the keys attached to this lease.
838 bool keys = 2;
839}
840
841message LeaseTimeToLiveResponse {
842 ResponseHeader header = 1;
843 // ID is the lease ID from the keep alive request.
844 int64 ID = 2;
845 // TTL is the remaining TTL in seconds for the lease; the lease will expire in under TTL+1 seconds.
846 int64 TTL = 3;
847 // GrantedTTL is the initial granted time in seconds upon lease creation/renewal.
848 int64 grantedTTL = 4;
849 // Keys is the list of keys attached to this lease.
850 repeated bytes keys = 5;
851}
852
853message LeaseLeasesRequest {
854}
855
856message LeaseStatus {
857 int64 ID = 1;
858 // TODO: int64 TTL = 2;
859}
860
861message LeaseLeasesResponse {
862 ResponseHeader header = 1;
863 repeated LeaseStatus leases = 2;
864}
865
866message Member {
867 // ID is the member ID for this member.
868 uint64 ID = 1;
869 // name is the human-readable name of the member. If the member is not started, the name will be an empty string.
870 string name = 2;
871 // peerURLs is the list of URLs the member exposes to the cluster for communication.
872 repeated string peerURLs = 3;
873 // clientURLs is the list of URLs the member exposes to clients for communication. If the member is not started, clientURLs will be empty.
874 repeated string clientURLs = 4;
875 // isLearner indicates if the member is raft learner.
876 bool isLearner = 5;
877}
878
879message MemberAddRequest {
880 // peerURLs is the list of URLs the added member will use to communicate with the cluster.
881 repeated string peerURLs = 1;
882 // isLearner indicates if the added member is raft learner.
883 bool isLearner = 2;
884}
885
886message MemberAddResponse {
887 ResponseHeader header = 1;
888 // member is the member information for the added member.
889 Member member = 2;
890 // members is a list of all members after adding the new member.
891 repeated Member members = 3;
892}
893
894message MemberRemoveRequest {
895 // ID is the member ID of the member to remove.
896 uint64 ID = 1;
897}
898
899message MemberRemoveResponse {
900 ResponseHeader header = 1;
901 // members is a list of all members after removing the member.
902 repeated Member members = 2;
903}
904
905message MemberUpdateRequest {
906 // ID is the member ID of the member to update.
907 uint64 ID = 1;
908 // peerURLs is the new list of URLs the member will use to communicate with the cluster.
909 repeated string peerURLs = 2;
910}
911
912message MemberUpdateResponse{
913 ResponseHeader header = 1;
914 // members is a list of all members after updating the member.
915 repeated Member members = 2;
916}
917
918message MemberListRequest {
919 bool linearizable = 1;
920}
921
922message MemberListResponse {
923 ResponseHeader header = 1;
924 // members is a list of all members associated with the cluster.
925 repeated Member members = 2;
926}
927
928message MemberPromoteRequest {
929 // ID is the member ID of the member to promote.
930 uint64 ID = 1;
931}
932
933message MemberPromoteResponse {
934 ResponseHeader header = 1;
935 // members is a list of all members after promoting the member.
936 repeated Member members = 2;
937}
938
939message DefragmentRequest {
940}
941
942message DefragmentResponse {
943 ResponseHeader header = 1;
944}
945
946message MoveLeaderRequest {
947 // targetID is the node ID for the new leader.
948 uint64 targetID = 1;
949}
950
951message MoveLeaderResponse {
952 ResponseHeader header = 1;
953}
954
955enum AlarmType {
956 NONE = 0; // default, used to query if any alarm is active
957 NOSPACE = 1; // space quota is exhausted
958 CORRUPT = 2; // kv store corruption detected
959}
960
961message AlarmRequest {
962 enum AlarmAction {
963 GET = 0;
964 ACTIVATE = 1;
965 DEACTIVATE = 2;
966 }
967 // action is the kind of alarm request to issue. The action
968 // may GET alarm statuses, ACTIVATE an alarm, or DEACTIVATE a
969 // raised alarm.
970 AlarmAction action = 1;
971 // memberID is the ID of the member associated with the alarm. If memberID is 0, the
972 // alarm request covers all members.
973 uint64 memberID = 2;
974 // alarm is the type of alarm to consider for this request.
975 AlarmType alarm = 3;
976}
977
978message AlarmMember {
979 // memberID is the ID of the member associated with the raised alarm.
980 uint64 memberID = 1;
981 // alarm is the type of alarm which has been raised.
982 AlarmType alarm = 2;
983}
984
985message AlarmResponse {
986 ResponseHeader header = 1;
987 // alarms is a list of alarms associated with the alarm request.
988 repeated AlarmMember alarms = 2;
989}
990
991message DowngradeRequest {
992 enum DowngradeAction {
993 VALIDATE = 0;
994 ENABLE = 1;
995 CANCEL = 2;
996 }
997
998 // action is the kind of downgrade request to issue. The action may
999 // VALIDATE the target version, DOWNGRADE the cluster version,
1000 // or CANCEL the current downgrading job.
1001 DowngradeAction action = 1;
1002 // version is the target version to downgrade.
1003 string version = 2;
1004}
1005
1006message DowngradeResponse {
1007 ResponseHeader header = 1;
1008 // version is the current cluster version.
1009 string version = 2;
1010}
1011
1012message StatusRequest {
1013}
1014
1015message StatusResponse {
1016 ResponseHeader header = 1;
1017 // version is the cluster protocol version used by the responding member.
1018 string version = 2;
1019 // dbSize is the size of the backend database physically allocated, in bytes, of the responding member.
1020 int64 dbSize = 3;
1021 // leader is the member ID which the responding member believes is the current leader.
1022 uint64 leader = 4;
1023 // raftIndex is the current raft committed index of the responding member.
1024 uint64 raftIndex = 5;
1025 // raftTerm is the current raft term of the responding member.
1026 uint64 raftTerm = 6;
1027 // raftAppliedIndex is the current raft applied index of the responding member.
1028 uint64 raftAppliedIndex = 7;
1029 // errors contains alarm/health information and status.
1030 repeated string errors = 8;
1031 // dbSizeInUse is the size of the backend database logically in use, in bytes, of the responding member.
1032 int64 dbSizeInUse = 9;
1033 // isLearner indicates if the member is raft learner.
1034 bool isLearner = 10;
1035}
1036
1037message AuthEnableRequest {
1038}
1039
1040message AuthDisableRequest {
1041}
1042
1043message AuthStatusRequest {
1044}
1045
1046message AuthenticateRequest {
1047 string name = 1;
1048 string password = 2;
1049}
1050
1051message AuthUserAddRequest {
1052 string name = 1;
1053 string password = 2;
1054 authpb.UserAddOptions options = 3;
1055 string hashedPassword = 4;
1056}
1057
1058message AuthUserGetRequest {
1059 string name = 1;
1060}
1061
1062message AuthUserDeleteRequest {
1063 // name is the name of the user to delete.
1064 string name = 1;
1065}
1066
1067message AuthUserChangePasswordRequest {
1068 // name is the name of the user whose password is being changed.
1069 string name = 1;
1070 // password is the new password for the user. Note that this field will be removed in the API layer.
1071 string password = 2;
1072 // hashedPassword is the new password for the user. Note that this field will be initialized in the API layer.
1073 string hashedPassword = 3;
1074}
1075
1076message AuthUserGrantRoleRequest {
1077 // user is the name of the user which should be granted a given role.
1078 string user = 1;
1079 // role is the name of the role to grant to the user.
1080 string role = 2;
1081}
1082
1083message AuthUserRevokeRoleRequest {
1084 string name = 1;
1085 string role = 2;
1086}
1087
1088message AuthRoleAddRequest {
1089 // name is the name of the role to add to the authentication system.
1090 string name = 1;
1091}
1092
1093message AuthRoleGetRequest {
1094 string role = 1;
1095}
1096
1097message AuthUserListRequest {
1098}
1099
1100message AuthRoleListRequest {
1101}
1102
1103message AuthRoleDeleteRequest {
1104 string role = 1;
1105}
1106
1107message AuthRoleGrantPermissionRequest {
1108 // name is the name of the role which will be granted the permission.
1109 string name = 1;
1110 // perm is the permission to grant to the role.
1111 authpb.Permission perm = 2;
1112}
1113
1114message AuthRoleRevokePermissionRequest {
1115 string role = 1;
1116 bytes key = 2;
1117 bytes range_end = 3;
1118}
1119
1120message AuthEnableResponse {
1121 ResponseHeader header = 1;
1122}
1123
1124message AuthDisableResponse {
1125 ResponseHeader header = 1;
1126}
1127
1128message AuthStatusResponse {
1129 ResponseHeader header = 1;
1130 bool enabled = 2;
1131 // authRevision is the current revision of auth store
1132 uint64 authRevision = 3;
1133}
1134
1135message AuthenticateResponse {
1136 ResponseHeader header = 1;
1137 // token is an authorized token that can be used in succeeding RPCs
1138 string token = 2;
1139}
1140
1141message AuthUserAddResponse {
1142 ResponseHeader header = 1;
1143}
1144
1145message AuthUserGetResponse {
1146 ResponseHeader header = 1;
1147
1148 repeated string roles = 2;
1149}
1150
1151message AuthUserDeleteResponse {
1152 ResponseHeader header = 1;
1153}
1154
1155message AuthUserChangePasswordResponse {
1156 ResponseHeader header = 1;
1157}
1158
1159message AuthUserGrantRoleResponse {
1160 ResponseHeader header = 1;
1161}
1162
1163message AuthUserRevokeRoleResponse {
1164 ResponseHeader header = 1;
1165}
1166
1167message AuthRoleAddResponse {
1168 ResponseHeader header = 1;
1169}
1170
1171message AuthRoleGetResponse {
1172 ResponseHeader header = 1;
1173
1174 repeated authpb.Permission perm = 2;
1175}
1176
1177message AuthRoleListResponse {
1178 ResponseHeader header = 1;
1179
1180 repeated string roles = 2;
1181}
1182
1183message AuthUserListResponse {
1184 ResponseHeader header = 1;
1185
1186 repeated string users = 2;
1187}
1188
1189message AuthRoleDeleteResponse {
1190 ResponseHeader header = 1;
1191}
1192
1193message AuthRoleGrantPermissionResponse {
1194 ResponseHeader header = 1;
1195}
1196
1197message AuthRoleRevokePermissionResponse {
1198 ResponseHeader header = 1;
1199}
View as plain text