etcd v3 uses gRPC for its messaging protocol. The etcd project includes a gRPC-based Go client and a command line utility, etcdctl, for communicating with an etcd cluster through gRPC. For languages with no gRPC support, etcd provides a JSON grpc-gateway. This gateway serves a RESTful proxy that translates HTTP/JSON requests into gRPC messages.
The gateway accepts a JSON mapping for etcd's protocol buffer message definitions. Note that key
and value
fields are defined as byte arrays and therefore must be base64 encoded in JSON. The following examples use curl
, but any HTTP/JSON client should work all the same.
Use the /v3beta/kv/range
and /v3beta/kv/put
services to read and write keys:
<<COMMENT https://www.base64encode.org/ foo is 'Zm9v' in Base64 bar is 'YmFy' COMMENT curl -L http://localhost:2379/v3beta/kv/put \ -X POST -d '{"key": "Zm9v", "value": "YmFy"}' # {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"3"}} curl -L http://localhost:2379/v3beta/kv/range \ -X POST -d '{"key": "Zm9v"}' # {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"3"},"kvs":[{"key":"Zm9v","create_revision":"2","mod_revision":"2","version":"1","value":"YmFy"}],"count":"1"} # get all keys prefixed with "foo" curl -L http://localhost:2379/v3beta/kv/range \ -X POST -d '{"key": "Zm9v", "range_end": "Zm9w"}' # {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"3"},"kvs":[{"key":"Zm9v","create_revision":"2","mod_revision":"2","version":"1","value":"YmFy"}],"count":"1"}
Use the /v3beta/watch
service to watch keys:
curl http://localhost:2379/v3beta/watch \ -X POST -d '{"create_request": {"key":"Zm9v"} }' & # {"result":{"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"1","raft_term":"2"},"created":true}} curl -L http://localhost:2379/v3beta/kv/put \ -X POST -d '{"key": "Zm9v", "value": "YmFy"}' >/dev/null 2>&1 # {"result":{"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"2"},"events":[{"kv":{"key":"Zm9v","create_revision":"2","mod_revision":"2","version":"1","value":"YmFy"}}]}}
Issue a transaction with /v3beta/kv/txn
:
curl -L http://localhost:2379/v3beta/kv/txn \ -X POST \ -d '{"compare":[{"target":"CREATE","key":"Zm9v","createRevision":"2"}],"success":[{"requestPut":{"key":"Zm9v","value":"YmFy"}}]}' # {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"3","raft_term":"2"},"succeeded":true,"responses":[{"response_put":{"header":{"revision":"3"}}}]}
Set up authentication with the /v3beta/auth
service:
# create root user curl -L http://localhost:2379/v3beta/auth/user/add \ -X POST -d '{"name": "root", "password": "pass"}' # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}} # create root role curl -L http://localhost:2379/v3beta/auth/role/add \ -X POST -d '{"name": "root"}' # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}} # grant root role curl -L http://localhost:2379/v3beta/auth/user/grant \ -X POST -d '{"user": "root", "role": "root"}' # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}} # enable auth curl -L http://localhost:2379/v3beta/auth/enable -X POST -d '{}' # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}
Authenticate with etcd for an authentication token using /v3beta/auth/authenticate
:
# get the auth token for the root user curl -L http://localhost:2379/v3beta/auth/authenticate \ -X POST -d '{"name": "root", "password": "pass"}' # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"},"token":"sssvIpwfnLAcWAQH.9"}
Set the Authorization
header to the authentication token to fetch a key using authentication credentials:
curl -L http://localhost:2379/v3beta/kv/put \ -H 'Authorization : sssvIpwfnLAcWAQH.9' \ -X POST -d '{"key": "Zm9v", "value": "YmFy"}' # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"2","raft_term":"2"}}
Generated Swagger API definitions can be found at rpc.swagger.json.