etcd API Reference

This is a generated documentation. Please read the proto files for more.

service Auth (etcdserver/etcdserverpb/rpc.proto)
MethodRequest TypeResponse TypeDescription
AuthEnableAuthEnableRequestAuthEnableResponseAuthEnable enables authentication.
AuthDisableAuthDisableRequestAuthDisableResponseAuthDisable disables authentication.
AuthenticateAuthenticateRequestAuthenticateResponseAuthenticate processes an authenticate request.
UserAddAuthUserAddRequestAuthUserAddResponseUserAdd adds a new user.
UserGetAuthUserGetRequestAuthUserGetResponseUserGet gets detailed user information.
UserListAuthUserListRequestAuthUserListResponseUserList gets a list of all users.
UserDeleteAuthUserDeleteRequestAuthUserDeleteResponseUserDelete deletes a specified user.
UserChangePasswordAuthUserChangePasswordRequestAuthUserChangePasswordResponseUserChangePassword changes the password of a specified user.
UserGrantRoleAuthUserGrantRoleRequestAuthUserGrantRoleResponseUserGrant grants a role to a specified user.
UserRevokeRoleAuthUserRevokeRoleRequestAuthUserRevokeRoleResponseUserRevokeRole revokes a role of specified user.
RoleAddAuthRoleAddRequestAuthRoleAddResponseRoleAdd adds a new role.
RoleGetAuthRoleGetRequestAuthRoleGetResponseRoleGet gets detailed role information.
RoleListAuthRoleListRequestAuthRoleListResponseRoleList gets lists of all roles.
RoleDeleteAuthRoleDeleteRequestAuthRoleDeleteResponseRoleDelete deletes a specified role.
RoleGrantPermissionAuthRoleGrantPermissionRequestAuthRoleGrantPermissionResponseRoleGrantPermission grants a permission of a specified key or range to a specified role.
RoleRevokePermissionAuthRoleRevokePermissionRequestAuthRoleRevokePermissionResponseRoleRevokePermission revokes a key or range permission of a specified role.
service Cluster (etcdserver/etcdserverpb/rpc.proto)
MethodRequest TypeResponse TypeDescription
MemberAddMemberAddRequestMemberAddResponseMemberAdd adds a member into the cluster.
MemberRemoveMemberRemoveRequestMemberRemoveResponseMemberRemove removes an existing member from the cluster.
MemberUpdateMemberUpdateRequestMemberUpdateResponseMemberUpdate updates the member configuration.
MemberListMemberListRequestMemberListResponseMemberList lists all the members in the cluster.
service KV (etcdserver/etcdserverpb/rpc.proto)
MethodRequest TypeResponse TypeDescription
RangeRangeRequestRangeResponseRange gets the keys in the range from the key-value store.
PutPutRequestPutResponsePut puts the given key into the key-value store. A put request increments the revision of the key-value store and generates one event in the event history.
DeleteRangeDeleteRangeRequestDeleteRangeResponseDeleteRange deletes the given range from the key-value store. A delete request increments the revision of the key-value store and generates a delete event in the event history for every deleted key.
TxnTxnRequestTxnResponseTxn processes multiple requests in a single transaction. A txn request increments the revision of the key-value store and generates events with the same revision for every completed request. It is not allowed to modify the same key several times within one txn.
CompactCompactionRequestCompactionResponseCompact compacts the event history in the etcd key-value store. The key-value store should be periodically compacted or the event history will continue to grow indefinitely.
service Lease (etcdserver/etcdserverpb/rpc.proto)
MethodRequest TypeResponse TypeDescription
LeaseGrantLeaseGrantRequestLeaseGrantResponseLeaseGrant creates a lease which expires if the server does not receive a keepAlive within a given time to live period. All keys attached to the lease will be expired and deleted if the lease expires. Each expired key generates a delete event in the event history.
LeaseRevokeLeaseRevokeRequestLeaseRevokeResponseLeaseRevoke revokes a lease. All keys attached to the lease will expire and be deleted.
LeaseKeepAliveLeaseKeepAliveRequestLeaseKeepAliveResponseLeaseKeepAlive keeps the lease alive by streaming keep alive requests from the client to the server and streaming keep alive responses from the server to the client.
LeaseTimeToLiveLeaseTimeToLiveRequestLeaseTimeToLiveResponseLeaseTimeToLive retrieves lease information.
LeaseLeasesLeaseLeasesRequestLeaseLeasesResponseLeaseLeases lists all existing leases.
service Maintenance (etcdserver/etcdserverpb/rpc.proto)
MethodRequest TypeResponse TypeDescription
AlarmAlarmRequestAlarmResponseAlarm activates, deactivates, and queries alarms regarding cluster health.
StatusStatusRequestStatusResponseStatus gets the status of the member.
DefragmentDefragmentRequestDefragmentResponseDefragment defragments a member’s backend database to recover storage space.
HashHashRequestHashResponseHash computes the hash of whole backend keyspace, including key, lease, and other buckets in storage. This is designed for testing ONLY! Do not rely on this in production with ongoing transactions, since Hash operation does not hold MVCC locks. Use “HashKV” API instead for “key” bucket consistency checks.
HashKVHashKVRequestHashKVResponseHashKV computes the hash of all MVCC keys up to a given revision. It only iterates “key” bucket in backend storage.
SnapshotSnapshotRequestSnapshotResponseSnapshot sends a snapshot of the entire backend from a member over a stream to a client.
MoveLeaderMoveLeaderRequestMoveLeaderResponseMoveLeader requests current leader node to transfer its leadership to transferee.
service Watch (etcdserver/etcdserverpb/rpc.proto)
MethodRequest TypeResponse TypeDescription
WatchWatchRequestWatchResponseWatch watches for events happening or that have happened. Both input and output are streams; the input stream is for creating and canceling watchers and the output stream sends events. One watch RPC can watch on multiple key ranges, streaming events for several watches at once. The entire event history can be watched starting from the last compaction revision.
message AlarmMember (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
memberIDmemberID is the ID of the member associated with the raised alarm.uint64
alarmalarm is the type of alarm which has been raised.AlarmType
message AlarmRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
actionaction is the kind of alarm request to issue. The action may GET alarm statuses, ACTIVATE an alarm, or DEACTIVATE a raised alarm.AlarmAction
memberIDmemberID is the ID of the member associated with the alarm. If memberID is 0, the alarm request covers all members.uint64
alarmalarm is the type of alarm to consider for this request.AlarmType
message AlarmResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
alarmsalarms is a list of alarms associated with the alarm request.(slice of) AlarmMember
message AuthDisableRequest (etcdserver/etcdserverpb/rpc.proto)

Empty field.

message AuthDisableResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
message AuthEnableRequest (etcdserver/etcdserverpb/rpc.proto)

Empty field.

message AuthEnableResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
message AuthRoleAddRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
namename is the name of the role to add to the authentication system.string
message AuthRoleAddResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
message AuthRoleDeleteRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
rolestring
message AuthRoleDeleteResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
message AuthRoleGetRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
rolestring
message AuthRoleGetResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
perm(slice of) authpb.Permission
message AuthRoleGrantPermissionRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
namename is the name of the role which will be granted the permission.string
permperm is the permission to grant to the role.authpb.Permission
message AuthRoleGrantPermissionResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
message AuthRoleListRequest (etcdserver/etcdserverpb/rpc.proto)

Empty field.

message AuthRoleListResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
roles(slice of) string
message AuthRoleRevokePermissionRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
rolestring
keybytes
range_endbytes
message AuthRoleRevokePermissionResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
message AuthUserAddRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
namestring
passwordstring
message AuthUserAddResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
message AuthUserChangePasswordRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
namename is the name of the user whose password is being changed.string
passwordpassword is the new password for the user.string
message AuthUserChangePasswordResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
message AuthUserDeleteRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
namename is the name of the user to delete.string
message AuthUserDeleteResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
message AuthUserGetRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
namestring
message AuthUserGetResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
roles(slice of) string
message AuthUserGrantRoleRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
useruser is the name of the user which should be granted a given role.string
rolerole is the name of the role to grant to the user.string
message AuthUserGrantRoleResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
message AuthUserListRequest (etcdserver/etcdserverpb/rpc.proto)

Empty field.

message AuthUserListResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
users(slice of) string
message AuthUserRevokeRoleRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
namestring
rolestring
message AuthUserRevokeRoleResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
message AuthenticateRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
namestring
passwordstring
message AuthenticateResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
tokentoken is an authorized token that can be used in succeeding RPCsstring
message CompactionRequest (etcdserver/etcdserverpb/rpc.proto)

CompactionRequest compacts the key-value store up to a given revision. All superseded keys with a revision less than the compaction revision will be removed.

FieldDescriptionType
revisionrevision is the key-value store revision for the compaction operation.int64
physicalphysical is set so the RPC will wait until the compaction is physically applied to the local database such that compacted entries are totally removed from the backend database.bool
message CompactionResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
message Compare (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
resultresult is logical comparison operation for this comparison.CompareResult
targettarget is the key-value field to inspect for the comparison.CompareTarget
keykey is the subject key for the comparison operation.bytes
target_uniononeof
versionversion is the version of the given keyint64
create_revisioncreate_revision is the creation revision of the given keyint64
mod_revisionmod_revision is the last modified revision of the given key.int64
valuevalue is the value of the given key, in bytes.bytes
leaselease is the lease id of the given key.int64
range_endrange_end compares the given target to all keys in the range [key, range_end). See RangeRequest for more details on key ranges.bytes
message DefragmentRequest (etcdserver/etcdserverpb/rpc.proto)

Empty field.

message DefragmentResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
message DeleteRangeRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
keykey is the first key to delete in the range.bytes
range_endrange_end is the key following the last key to delete for the range [key, range_end). If range_end is not given, the range is defined to contain only the key argument. If range_end is one bit larger than the given key, then the range is all the keys with the prefix (the given key). If range_end is ‘\0’, the range is all keys greater than or equal to the key argument.bytes
prev_kvIf prev_kv is set, etcd gets the previous key-value pairs before deleting it. The previous key-value pairs will be returned in the delete response.bool
message DeleteRangeResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
deleteddeleted is the number of keys deleted by the delete range request.int64
prev_kvsif prev_kv is set in the request, the previous key-value pairs will be returned.(slice of) mvccpb.KeyValue
message HashKVRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
revisionrevision is the key-value store revision for the hash operation.int64
message HashKVResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
hashhash is the hash value computed from the responding member’s MVCC keys up to a given revision.uint32
compact_revisioncompact_revision is the compacted revision of key-value store when hash begins.int64
message HashRequest (etcdserver/etcdserverpb/rpc.proto)

Empty field.

message HashResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
hashhash is the hash value computed from the responding member’s KV’s backend.uint32
message LeaseCheckpoint (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
IDID is the lease ID to checkpoint.int64
remaining_TTLRemaining_TTL is the remaining time until expiry of the lease.int64
message LeaseCheckpointRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
checkpoints(slice of) LeaseCheckpoint
message LeaseCheckpointResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
message LeaseGrantRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
TTLTTL is the advisory time-to-live in seconds. Expired lease will return -1.int64
IDID is the requested ID for the lease. If ID is set to 0, the lessor chooses an ID.int64
message LeaseGrantResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
IDID is the lease ID for the granted lease.int64
TTLTTL is the server chosen lease time-to-live in seconds.int64
errorstring
message LeaseKeepAliveRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
IDID is the lease ID for the lease to keep alive.int64
message LeaseKeepAliveResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
IDID is the lease ID from the keep alive request.int64
TTLTTL is the new time-to-live for the lease.int64
message LeaseLeasesRequest (etcdserver/etcdserverpb/rpc.proto)

Empty field.

message LeaseLeasesResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
leases(slice of) LeaseStatus
message LeaseRevokeRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
IDID is the lease ID to revoke. When the ID is revoked, all associated keys will be deleted.int64
message LeaseRevokeResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
message LeaseStatus (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
IDint64
message LeaseTimeToLiveRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
IDID is the lease ID for the lease.int64
keyskeys is true to query all the keys attached to this lease.bool
message LeaseTimeToLiveResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
IDID is the lease ID from the keep alive request.int64
TTLTTL is the remaining TTL in seconds for the lease; the lease will expire in under TTL+1 seconds.int64
grantedTTLGrantedTTL is the initial granted time in seconds upon lease creation/renewal.int64
keysKeys is the list of keys attached to this lease.(slice of) bytes
message Member (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
IDID is the member ID for this member.uint64
namename is the human-readable name of the member. If the member is not started, the name will be an empty string.string
peerURLspeerURLs is the list of URLs the member exposes to the cluster for communication.(slice of) string
clientURLsclientURLs is the list of URLs the member exposes to clients for communication. If the member is not started, clientURLs will be empty.(slice of) string
message MemberAddRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
peerURLspeerURLs is the list of URLs the added member will use to communicate with the cluster.(slice of) string
message MemberAddResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
membermember is the member information for the added member.Member
membersmembers is a list of all members after adding the new member.(slice of) Member
message MemberListRequest (etcdserver/etcdserverpb/rpc.proto)

Empty field.

message MemberListResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
membersmembers is a list of all members associated with the cluster.(slice of) Member
message MemberRemoveRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
IDID is the member ID of the member to remove.uint64
message MemberRemoveResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
membersmembers is a list of all members after removing the member.(slice of) Member
message MemberUpdateRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
IDID is the member ID of the member to update.uint64
peerURLspeerURLs is the new list of URLs the member will use to communicate with the cluster.(slice of) string
message MemberUpdateResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
membersmembers is a list of all members after updating the member.(slice of) Member
message MoveLeaderRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
targetIDtargetID is the node ID for the new leader.uint64
message MoveLeaderResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
message PutRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
keykey is the key, in bytes, to put into the key-value store.bytes
valuevalue is the value, in bytes, to associate with the key in the key-value store.bytes
leaselease is the lease ID to associate with the key in the key-value store. A lease value of 0 indicates no lease.int64
prev_kvIf prev_kv is set, etcd gets the previous key-value pair before changing it. The previous key-value pair will be returned in the put response.bool
ignore_valueIf ignore_value is set, etcd updates the key using its current value. Returns an error if the key does not exist.bool
ignore_leaseIf ignore_lease is set, etcd updates the key using its current lease. Returns an error if the key does not exist.bool
message PutResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
prev_kvif prev_kv is set in the request, the previous key-value pair will be returned.mvccpb.KeyValue
message RangeRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
keykey is the first key for the range. If range_end is not given, the request only looks up key.bytes
range_endrange_end is the upper bound on the requested range [key, range_end). If range_end is ‘\0’, the range is all keys >= key. If range_end is key plus one (e.g., “aa”+1 == “ab”, “a\xff”+1 == “b”), then the range request gets all keys prefixed with key. If both key and range_end are ‘\0’, then the range request returns all keys.bytes
limitlimit is a limit on the number of keys returned for the request. When limit is set to 0, it is treated as no limit.int64
revisionrevision is the point-in-time of the key-value store to use for the range. If revision is less or equal to zero, the range is over the newest key-value store. If the revision has been compacted, ErrCompacted is returned as a response.int64
sort_ordersort_order is the order for returned sorted results.SortOrder
sort_targetsort_target is the key-value field to use for sorting.SortTarget
serializableserializable sets the range request to use serializable member-local reads. Range requests are linearizable by default; linearizable requests have higher latency and lower throughput than serializable requests but reflect the current consensus of the cluster. For better performance, in exchange for possible stale reads, a serializable range request is served locally without needing to reach consensus with other nodes in the cluster.bool
keys_onlykeys_only when set returns only the keys and not the values.bool
count_onlycount_only when set returns only the count of the keys in the range.bool
min_mod_revisionmin_mod_revision is the lower bound for returned key mod revisions; all keys with lesser mod revisions will be filtered away.int64
max_mod_revisionmax_mod_revision is the upper bound for returned key mod revisions; all keys with greater mod revisions will be filtered away.int64
min_create_revisionmin_create_revision is the lower bound for returned key create revisions; all keys with lesser create revisions will be filtered away.int64
max_create_revisionmax_create_revision is the upper bound for returned key create revisions; all keys with greater create revisions will be filtered away.int64
message RangeResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
kvskvs is the list of key-value pairs matched by the range request. kvs is empty when count is requested.(slice of) mvccpb.KeyValue
moremore indicates if there are more keys to return in the requested range.bool
countcount is set to the number of keys within the range when requested.int64
message RequestOp (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
requestrequest is a union of request types accepted by a transaction.oneof
request_rangeRangeRequest
request_putPutRequest
request_delete_rangeDeleteRangeRequest
request_txnTxnRequest
message ResponseHeader (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
cluster_idcluster_id is the ID of the cluster which sent the response.uint64
member_idmember_id is the ID of the member which sent the response.uint64
revisionrevision is the key-value store revision when the request was applied. For watch progress responses, the header.revision indicates progress. All future events received in this stream are guaranteed to have a higher revision number than the header.revision number.int64
raft_termraft_term is the raft term when the request was applied.uint64
message ResponseOp (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
responseresponse is a union of response types returned by a transaction.oneof
response_rangeRangeResponse
response_putPutResponse
response_delete_rangeDeleteRangeResponse
response_txnTxnResponse
message SnapshotRequest (etcdserver/etcdserverpb/rpc.proto)

Empty field.

message SnapshotResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerheader has the current key-value store information. The first header in the snapshot stream indicates the point in time of the snapshot.ResponseHeader
remaining_bytesremaining_bytes is the number of blob bytes to be sent after this messageuint64
blobblob contains the next chunk of the snapshot in the snapshot stream.bytes
message StatusRequest (etcdserver/etcdserverpb/rpc.proto)

Empty field.

message StatusResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
versionversion is the cluster protocol version used by the responding member.string
dbSizedbSize is the size of the backend database physically allocated, in bytes, of the responding member.int64
leaderleader is the member ID which the responding member believes is the current leader.uint64
raftIndexraftIndex is the current raft committed index of the responding member.uint64
raftTermraftTerm is the current raft term of the responding member.uint64
raftAppliedIndexraftAppliedIndex is the current raft applied index of the responding member.uint64
errorserrors contains alarm/health information and status.(slice of) string
dbSizeInUsedbSizeInUse is the size of the backend database logically in use, in bytes, of the responding member.int64
message TxnRequest (etcdserver/etcdserverpb/rpc.proto)

From google paxosdb paper: Our implementation hinges around a powerful primitive which we call MultiOp. All other database operations except for iteration are implemented as a single call to MultiOp. A MultiOp is applied atomically and consists of three components: 1. A list of tests called guard. Each test in guard checks a single entry in the database. It may check for the absence or presence of a value, or compare with a given value. Two different tests in the guard may apply to the same or different entries in the database. All tests in the guard are applied and MultiOp returns the results. If all tests are true, MultiOp executes t op (see item 2 below), otherwise it executes f op (see item 3 below). 2. A list of database operations called t op. Each operation in the list is either an insert, delete, or lookup operation, and applies to a single database entry. Two different operations in the list may apply to the same or different entries in the database. These operations are executed if guard evaluates to true. 3. A list of database operations called f op. Like t op, but executed if guard evaluates to false.

FieldDescriptionType
comparecompare is a list of predicates representing a conjunction of terms. If the comparisons succeed, then the success requests will be processed in order, and the response will contain their respective responses in order. If the comparisons fail, then the failure requests will be processed in order, and the response will contain their respective responses in order.(slice of) Compare
successsuccess is a list of requests which will be applied when compare evaluates to true.(slice of) RequestOp
failurefailure is a list of requests which will be applied when compare evaluates to false.(slice of) RequestOp
message TxnResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
succeededsucceeded is set to true if the compare evaluated to true or false otherwise.bool
responsesresponses is a list of responses corresponding to the results from applying success if succeeded is true or failure if succeeded is false.(slice of) ResponseOp
message WatchCancelRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
watch_idwatch_id is the watcher id to cancel so that no more events are transmitted.int64
message WatchCreateRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
keykey is the key to register for watching.bytes
range_endrange_end is the end of the range [key, range_end) to watch. If range_end is not given, only the key argument is watched. If range_end is equal to ‘\0’, all keys greater than or equal to the key argument are watched. If the range_end is one bit larger than the given key, then all keys with the prefix (the given key) will be watched.bytes
start_revisionstart_revision is an optional revision to watch from (inclusive). No start_revision is “now”.int64
progress_notifyprogress_notify is set so that the etcd server will periodically send a WatchResponse with no events to the new watcher if there are no recent events. It is useful when clients wish to recover a disconnected watcher starting from a recent known revision. The etcd server may decide how often it will send notifications based on current load.bool
filtersfilters filter the events at server side before it sends back to the watcher.(slice of) FilterType
prev_kvIf prev_kv is set, created watcher gets the previous KV before the event happens. If the previous KV is already compacted, nothing will be returned.bool
watch_idIf watch_id is provided and non-zero, it will be assigned to this watcher. Since creating a watcher in etcd is not a synchronous operation, this can be used ensure that ordering is correct when creating multiple watchers on the same stream. Creating a watcher with an ID already in use on the stream will cause an error to be returned.int64
fragmentfragment enables splitting large revisions into multiple watch responses.bool
message WatchProgressRequest (etcdserver/etcdserverpb/rpc.proto)

Requests the a watch stream progress status be sent in the watch response stream as soon as possible.

Empty field.

message WatchRequest (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
request_unionrequest_union is a request to either create a new watcher or cancel an existing watcher.oneof
create_requestWatchCreateRequest
cancel_requestWatchCancelRequest
progress_requestWatchProgressRequest
message WatchResponse (etcdserver/etcdserverpb/rpc.proto)
FieldDescriptionType
headerResponseHeader
watch_idwatch_id is the ID of the watcher that corresponds to the response.int64
createdcreated is set to true if the response is for a create watch request. The client should record the watch_id and expect to receive events for the created watcher from the same stream. All events sent to the created watcher will attach with the same watch_id.bool
canceledcanceled is set to true if the response is for a cancel watch request. No further events will be sent to the canceled watcher.bool
compact_revisioncompact_revision is set to the minimum index if a watcher tries to watch at a compacted index. This happens when creating a watcher at a compacted revision or the watcher cannot catch up with the progress of the key-value store. The client should treat the watcher as canceled and should not try to create any watcher with the same start_revision again.int64
cancel_reasoncancel_reason indicates the reason for canceling the watcher.string
fragmentframgment is true if large watch response was split over multiple responses.bool
events(slice of) mvccpb.Event
message Event (mvcc/mvccpb/kv.proto)
FieldDescriptionType
typetype is the kind of event. If type is a PUT, it indicates new data has been stored to the key. If type is a DELETE, it indicates the key was deleted.EventType
kvkv holds the KeyValue for the event. A PUT event contains current kv pair. A PUT event with kv.Version=1 indicates the creation of a key. A DELETE/EXPIRE event contains the deleted key with its modification revision set to the revision of deletion.KeyValue
prev_kvprev_kv holds the key-value pair before the event happens.KeyValue
message KeyValue (mvcc/mvccpb/kv.proto)
FieldDescriptionType
keykey is the key in bytes. An empty key is not allowed.bytes
create_revisioncreate_revision is the revision of last creation on this key.int64
mod_revisionmod_revision is the revision of last modification on this key.int64
versionversion is the version of the key. A deletion resets the version to zero and any modification of the key increases its version.int64
valuevalue is the value held by the key, in bytes.bytes
leaselease is the ID of the lease that attached to key. When the attached lease expires, the key will be deleted. If lease is 0, then no lease is attached to the key.int64
message Lease (lease/leasepb/lease.proto)
FieldDescriptionType
IDint64
TTLint64
RemainingTTLint64
message LeaseInternalRequest (lease/leasepb/lease.proto)
FieldDescriptionType
LeaseTimeToLiveRequestetcdserverpb.LeaseTimeToLiveRequest
message LeaseInternalResponse (lease/leasepb/lease.proto)
FieldDescriptionType
LeaseTimeToLiveResponseetcdserverpb.LeaseTimeToLiveResponse
message Permission (auth/authpb/auth.proto)

Permission is a single entity

FieldDescriptionType
permTypeType
keybytes
range_endbytes
message Role (auth/authpb/auth.proto)

Role is a single entry in the bucket authRoles

FieldDescriptionType
namebytes
keyPermission(slice of) Permission
message User (auth/authpb/auth.proto)

User is a single entry in the bucket authUsers

FieldDescriptionType
namebytes
passwordbytes
roles(slice of) string

Last modified April 9, 2022: Fix typos (a2da31e)