Version 3.3.13 home Download and build Libraries and tools Metrics Branch management Demo Discovery service protocol etcd release guide Frequently Asked Questions (FAQ) Logging conventions Production users Reporting bugs Tuning Benchmarks Benchmarking etcd v2.1.0 Benchmarking etcd v2.2.0 Benchmarking etcd v2.2.0-rc Benchmarking etcd v2.2.0-rc-memory Benchmarking etcd v3 Storage Memory Usage Benchmark Watch Memory Usage Benchmark Developer guide etcd API Reference etcd concurrency API Reference Experimental APIs and features gRPC naming and discovery Interacting with etcd Set up a local cluster System limits Why gRPC gateway etcd v3 API Learning etcd client architecture Client feature matrix Data model etcd v3 authentication design etcd versus other key-value stores etcd3 API Glossary KV API guarantees Learner Operations guide Clustering Guide Configuration flags Design of runtime reconfiguration Disaster recovery etcd gateway Failure modes gRPC proxy Hardware recommendations Maintenance Migrate applications from using API v2 to API v3 Monitoring etcd Performance Role-based access control Run etcd clusters inside containers Runtime reconfiguration Supported systems Transport security model Versioning Platforms Amazon Web Services Container Linux with systemd FreeBSD Upgrading Upgrade etcd from 2.3 to 3.0 Upgrade etcd from 3.0 to 3.1 Upgrade etcd from 3.1 to 3.2 Upgrade etcd from 3.2 to 3.3 Upgrade etcd from 3.3 to 3.4 Upgrade etcd from 3.4 to 3.5 Upgrading etcd clusters and applications

etcd concurrency API Reference

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

service Lock (etcdserver/api/v3lock/v3lockpb/v3lock.proto)

The lock service exposes client-side locking facilities as a gRPC interface.

MethodRequest TypeResponse TypeDescription
LockLockRequestLockResponseLock acquires a distributed shared lock on a given named lock. On success, it will return a unique key that exists so long as the lock is held by the caller. This key can be used in conjunction with transactions to safely ensure updates to etcd only occur while holding lock ownership. The lock is held until Unlock is called on the key or the lease associate with the owner expires.
UnlockUnlockRequestUnlockResponseUnlock takes a key returned by Lock and releases the hold on lock. The next Lock caller waiting for the lock will then be woken up and given ownership of the lock.
message LockRequest (etcdserver/api/v3lock/v3lockpb/v3lock.proto)
FieldDescriptionType
namename is the identifier for the distributed shared lock to be acquired.bytes
leaselease is the ID of the lease that will be attached to ownership of the lock. If the lease expires or is revoked and currently holds the lock, the lock is automatically released. Calls to Lock with the same lease will be treated as a single acquisition; locking twice with the same lease is a no-op.int64
message LockResponse (etcdserver/api/v3lock/v3lockpb/v3lock.proto)
FieldDescriptionType
headeretcdserverpb.ResponseHeader
keykey is a key that will exist on etcd for the duration that the Lock caller owns the lock. Users should not modify this key or the lock may exhibit undefined behavior.bytes
message UnlockRequest (etcdserver/api/v3lock/v3lockpb/v3lock.proto)
FieldDescriptionType
keykey is the lock ownership key granted by Lock.bytes
message UnlockResponse (etcdserver/api/v3lock/v3lockpb/v3lock.proto)
FieldDescriptionType
headeretcdserverpb.ResponseHeader
service Election (etcdserver/api/v3election/v3electionpb/v3election.proto)

The election service exposes client-side election facilities as a gRPC interface.

MethodRequest TypeResponse TypeDescription
CampaignCampaignRequestCampaignResponseCampaign waits to acquire leadership in an election, returning a LeaderKey representing the leadership if successful. The LeaderKey can then be used to issue new values on the election, transactionally guard API requests on leadership still being held, and resign from the election.
ProclaimProclaimRequestProclaimResponseProclaim updates the leader’s posted value with a new value.
LeaderLeaderRequestLeaderResponseLeader returns the current election proclamation, if any.
ObserveLeaderRequestLeaderResponseObserve streams election proclamations in-order as made by the election’s elected leaders.
ResignResignRequestResignResponseResign releases election leadership so other campaigners may acquire leadership on the election.
message CampaignRequest (etcdserver/api/v3election/v3electionpb/v3election.proto)
FieldDescriptionType
namename is the election’s identifier for the campaign.bytes
leaselease is the ID of the lease attached to leadership of the election. If the lease expires or is revoked before resigning leadership, then the leadership is transferred to the next campaigner, if any.int64
valuevalue is the initial proclaimed value set when the campaigner wins the election.bytes
message CampaignResponse (etcdserver/api/v3election/v3electionpb/v3election.proto)
FieldDescriptionType
headeretcdserverpb.ResponseHeader
leaderleader describes the resources used for holding leadereship of the election.LeaderKey
message LeaderKey (etcdserver/api/v3election/v3electionpb/v3election.proto)
FieldDescriptionType
namename is the election identifier that correponds to the leadership key.bytes
keykey is an opaque key representing the ownership of the election. If the key is deleted, then leadership is lost.bytes
revrev is the creation revision of the key. It can be used to test for ownership of an election during transactions by testing the key’s creation revision matches rev.int64
leaselease is the lease ID of the election leader.int64
message LeaderRequest (etcdserver/api/v3election/v3electionpb/v3election.proto)
FieldDescriptionType
namename is the election identifier for the leadership information.bytes
message LeaderResponse (etcdserver/api/v3election/v3electionpb/v3election.proto)
FieldDescriptionType
headeretcdserverpb.ResponseHeader
kvkv is the key-value pair representing the latest leader update.mvccpb.KeyValue
message ProclaimRequest (etcdserver/api/v3election/v3electionpb/v3election.proto)
FieldDescriptionType
leaderleader is the leadership hold on the election.LeaderKey
valuevalue is an update meant to overwrite the leader’s current value.bytes
message ProclaimResponse (etcdserver/api/v3election/v3electionpb/v3election.proto)
FieldDescriptionType
headeretcdserverpb.ResponseHeader
message ResignRequest (etcdserver/api/v3election/v3electionpb/v3election.proto)
FieldDescriptionType
leaderleader is the leadership to relinquish by resignation.LeaderKey
message ResignResponse (etcdserver/api/v3election/v3electionpb/v3election.proto)
FieldDescriptionType
headeretcdserverpb.ResponseHeader
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

© etcd Authors 2020 | Documentation Distributed under CC-BY-4.0

© 2020 The Linux Foundation. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks.
For a list of trademarks of The Linux Foundation, please see our Trademark Usage page.

etcd concurrency API Reference