etcd
Read and write etcd keys: prefixes, compare-and-set transactions, leases and cluster status. Typical uses: read shared configuration, coordinate servers.
etcd pingetcd infoetcd putetcd putetcd getetcd listetcd listetcd casetcd lease_grantetcd lease_keepaliveetcd lease_infoetcd lease_revokeetcd deleteetcd deleteetcd requestetcd request

etcd ping <config>


Description

    The versions of the server and of the cluster (GET /version, no authentication): {version, cluster_version}

Parameters

    config:   The etcd configuration as JSON: url (http://127.0.0.1:2379; endpoint is accepted as an alias; https checked with the trust store of the JDK), username and password (the name of a secret: secret set) when the authentication is enabled, allow_plain (false: a password over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB, the largest response) - String - required
admin
etcd ping "{\"url\": \"http://127.0.0.1:2379\"}"
mentdb
{"version": "3.5.17", "cluster_version": "3.5.0"}

etcd info <config>


Description

    The status of the member: {version, db_size, leader, member_id, revision, raft_index, raft_term, is_learner}

Parameters

    config:   The etcd configuration as JSON: url (http://127.0.0.1:2379; endpoint is accepted as an alias; https checked with the trust store of the JDK), username and password (the name of a secret: secret set) when the authentication is enabled, allow_plain (false: a password over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB, the largest response) - String - required
admin
etcd info "{\"url\": \"http://127.0.0.1:2379\"}"
mentdb
{"version": "3.5.17", "db_size": 98304, "leader": "3307425987971480646", "member_id": "3307425987971480646", "revision": 1, "raft_index": 4, "raft_term": 2, "is_learner": false}

etcd put <config> <key> <value>


Description

    Write a value. Returns {key, revision}

Parameters

    config:   The etcd configuration as JSON: url (http://127.0.0.1:2379; endpoint is accepted as an alias; https checked with the trust store of the JDK), username and password (the name of a secret: secret set) when the authentication is enabled, allow_plain (false: a password over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB, the largest response) - String - required
    key:   The key - String - required
    value:   The value - String - required
admin
etcd put "{\"url\": \"http://127.0.0.1:2379\"}" "app/db/host" "db1.local"
mentdb
{"key": "app/db/host", "revision": 2}
with the authentication enabled (fixed result: real etcd 3.5.17)
admin
etcd put "{\"url\": \"http://127.0.0.1:2379\", \"username\": \"root\", \"password\": \"etcd_password\"}" "app/db/port" "5432"
mentdb
{"key": "app/db/port", "revision": 3}

etcd put <config> <key> <value> <json_params>


Description

    Write with parameters: lease (the id of etcd lease_grant: the key is deleted with the lease), prev_kv (true: also returns the previous version as prev)

Parameters

    config:   The etcd configuration as JSON: url (http://127.0.0.1:2379; endpoint is accepted as an alias; https checked with the trust store of the JDK), username and password (the name of a secret: secret set) when the authentication is enabled, allow_plain (false: a password over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB, the largest response) - String - required
    key:   The key - String - required
    value:   The value - String - required
    json_params:   The parameters - String - required
admin
etcd put "{\"url\": \"http://127.0.0.1:2379\"}" "app/db/port" "5433" "{\"prev_kv\": true}"
mentdb
{"key": "app/db/port", "revision": 4, "prev": {"key": "app/db/port", "value": "5432", "create_revision": 3, "mod_revision": 3, "version": 1, "lease": "0"}}

etcd get <config> <key>


Description

    Read a value; null if the key does not exist

Parameters

    config:   The etcd configuration as JSON: url (http://127.0.0.1:2379; endpoint is accepted as an alias; https checked with the trust store of the JDK), username and password (the name of a secret: secret set) when the authentication is enabled, allow_plain (false: a password over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB, the largest response) - String - required
    key:   The key - String - required
admin
etcd get "{\"url\": \"http://127.0.0.1:2379\"}" "app/db/host"
mentdb
db1.local
no such key (fixed result: real etcd 3.5.17)
admin
etcd get "{\"url\": \"http://127.0.0.1:2379\"}" "nothing"
mentdb
null

etcd list <config> <prefix>


Description

    The keys under a prefix as rows sorted by key ("" = every key)

Parameters

    config:   The etcd configuration as JSON: url (http://127.0.0.1:2379; endpoint is accepted as an alias; https checked with the trust store of the JDK), username and password (the name of a secret: secret set) when the authentication is enabled, allow_plain (false: a password over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB, the largest response) - String - required
    prefix:   The prefix - String - required
admin
etcd list "{\"url\": \"http://127.0.0.1:2379\"}" "app/"
mentdb
[{"key": "app/db/host", "value": "db1.local", "create_revision": 2, "mod_revision": 2, "version": 1, "lease": "0"}, {"key": "app/db/port", "value": "5433", "create_revision": 3, "mod_revision": 4, "version": 2, "lease": "0"}]

etcd list <config> <prefix> <json_params>


Description

    List with parameters: limit (10000; more keys than this is an error), partial (true: return the first limit keys instead of the error), keys_only (true: no value), revision (read the past state at this revision)

Parameters

    config:   The etcd configuration as JSON: url (http://127.0.0.1:2379; endpoint is accepted as an alias; https checked with the trust store of the JDK), username and password (the name of a secret: secret set) when the authentication is enabled, allow_plain (false: a password over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB, the largest response) - String - required
    prefix:   The prefix - String - required
    json_params:   The parameters - String - required
admin
etcd list "{\"url\": \"http://127.0.0.1:2379\"}" "app/db/" "{\"keys_only\": true, \"limit\": 100}"
mentdb
[{"key": "app/db/host", "create_revision": 2, "mod_revision": 2, "version": 1, "lease": "0"}, {"key": "app/db/port", "create_revision": 3, "mod_revision": 4, "version": 2, "lease": "0"}]
as it was at the revision 2 (fixed result: real etcd 3.5.17)
admin
etcd list "{\"url\": \"http://127.0.0.1:2379\"}" "app/" "{\"revision\": 2}"
mentdb
[{"key": "app/db/host", "value": "db1.local", "create_revision": 2, "mod_revision": 2, "version": 1, "lease": "0"}]

etcd cas <config> <key> <value> <json_compare>


Description

    Write only if a comparison is true, in one transaction: {"value": "old"}, {"version": 0} (the key does not exist), {"mod_revision": n} (unchanged since that revision), {"create_revision": n} or {"lease": "id"} ("0": no lease). Returns {succeeded, revision}

Parameters

    config:   The etcd configuration as JSON: url (http://127.0.0.1:2379; endpoint is accepted as an alias; https checked with the trust store of the JDK), username and password (the name of a secret: secret set) when the authentication is enabled, allow_plain (false: a password over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB, the largest response) - String - required
    key:   The key - String - required
    value:   The new value - String - required
    json_compare:   The comparison: one field - String - required
admin
etcd cas "{\"url\": \"http://127.0.0.1:2379\"}" "app/db/port" "5434" "{\"value\": \"5433\"}"
mentdb
{"succeeded": true, "revision": 5}
it changed in between (fixed result: real etcd 3.5.17)
admin
etcd cas "{\"url\": \"http://127.0.0.1:2379\"}" "app/db/port" "6000" "{\"value\": \"5433\"}"
mentdb
{"succeeded": false, "revision": 5}
create once: first call (fixed result: real etcd 3.5.17)
admin
etcd cas "{\"url\": \"http://127.0.0.1:2379\"}" "election/leader" "node-a" "{\"version\": 0}"
mentdb
{"succeeded": true, "revision": 6}
create once: second call (fixed result: real etcd 3.5.17)
admin
etcd cas "{\"url\": \"http://127.0.0.1:2379\"}" "election/leader" "node-b" "{\"version\": 0}"
mentdb
{"succeeded": false, "revision": 6}
unchanged since the revision 6 (its mod_revision) (fixed result: real etcd 3.5.17)
admin
etcd cas "{\"url\": \"http://127.0.0.1:2379\"}" "election/leader" "node-a2" "{\"mod_revision\": 6}"
mentdb
{"succeeded": true, "revision": 7}
an old revision: refused (fixed result: real etcd 3.5.17)
admin
etcd cas "{\"url\": \"http://127.0.0.1:2379\"}" "election/leader" "node-b" "{\"mod_revision\": 6}"
mentdb
{"succeeded": false, "revision": 7}

etcd lease_grant <config> <ttl>


Description

    Create a lease of ttl seconds. Returns {id, ttl}

Parameters

    config:   The etcd configuration as JSON: url (http://127.0.0.1:2379; endpoint is accepted as an alias; https checked with the trust store of the JDK), username and password (the name of a secret: secret set) when the authentication is enabled, allow_plain (false: a password over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB, the largest response) - String - required
    ttl:   The seconds - Number - required
admin
etcd lease_grant "{\"url\": \"http://127.0.0.1:2379\"}" 60
mentdb
{"id": "8955022932371309076", "ttl": 60}

etcd lease_keepalive <config> <lease>


Description

    Renew a lease once. Returns {id, ttl}; ttl 0 means the lease expired or was revoked

Parameters

    config:   The etcd configuration as JSON: url (http://127.0.0.1:2379; endpoint is accepted as an alias; https checked with the trust store of the JDK), username and password (the name of a secret: secret set) when the authentication is enabled, allow_plain (false: a password over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB, the largest response) - String - required
    lease:   The lease id, as given by etcd lease_grant (a text: 19 digits do not fit in a number) - String - required
admin
etcd lease_keepalive "{\"url\": \"http://127.0.0.1:2379\"}" "7587883208513421620"
mentdb
{"id": "7587883208513421620", "ttl": 0}

etcd lease_info <config> <lease>


Description

    The time left of a lease and its keys: {id, ttl, granted_ttl, keys}; ttl -1 if it does not exist

Parameters

    config:   The etcd configuration as JSON: url (http://127.0.0.1:2379; endpoint is accepted as an alias; https checked with the trust store of the JDK), username and password (the name of a secret: secret set) when the authentication is enabled, allow_plain (false: a password over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB, the largest response) - String - required
    lease:   The lease id, as given by etcd lease_grant (a text: 19 digits do not fit in a number) - String - required
admin
etcd lease_info "{\"url\": \"http://127.0.0.1:2379\"}" "7587883208513421620"
mentdb
{"id": "7587883208513421620", "ttl": -1, "granted_ttl": 0, "keys": []}

etcd lease_revoke <config> <lease>


Description

    Revoke a lease: its keys are deleted. Returns 1 (an error if it does not exist)

Parameters

    config:   The etcd configuration as JSON: url (http://127.0.0.1:2379; endpoint is accepted as an alias; https checked with the trust store of the JDK), username and password (the name of a secret: secret set) when the authentication is enabled, allow_plain (false: a password over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB, the largest response) - String - required
    lease:   The lease id, as given by etcd lease_grant (a text: 19 digits do not fit in a number) - String - required
admin
etcd lease_revoke "{\"url\": \"http://127.0.0.1:2379\"}" "7587883208513421620"
mentdb
ERROR: Sorry, an error appears (etcd error: etcdserver: requested lease not found).

etcd delete <config> <key>


Description

    Delete a key. Returns {deleted: the number of deleted keys}

Parameters

    config:   The etcd configuration as JSON: url (http://127.0.0.1:2379; endpoint is accepted as an alias; https checked with the trust store of the JDK), username and password (the name of a secret: secret set) when the authentication is enabled, allow_plain (false: a password over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB, the largest response) - String - required
    key:   The key - String - required
admin
etcd delete "{\"url\": \"http://127.0.0.1:2379\"}" "election/leader"
mentdb
{"deleted": 1}

etcd delete <config> <key> <json_params>


Description

    Delete with parameters: prefix (true: every key under the prefix; an empty prefix, every key of etcd, also needs confirm true)

Parameters

    config:   The etcd configuration as JSON: url (http://127.0.0.1:2379; endpoint is accepted as an alias; https checked with the trust store of the JDK), username and password (the name of a secret: secret set) when the authentication is enabled, allow_plain (false: a password over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB, the largest response) - String - required
    key:   The key - String - required
    json_params:   The parameters - String - required
admin
etcd delete "{\"url\": \"http://127.0.0.1:2379\"}" "app/" "{\"prefix\": true}"
mentdb
{"deleted": 2}

etcd request <config> <method> <path>


Description

    The raw HTTP escape hatch: a GET or a DELETE on a path of the JSON gateway (with the token of the authentication). Returns the response text of a 2xx; keys and values stay in base64

Parameters

    config:   The etcd configuration as JSON: url (http://127.0.0.1:2379; endpoint is accepted as an alias; https checked with the trust store of the JDK), username and password (the name of a secret: secret set) when the authentication is enabled, allow_plain (false: a password over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB, the largest response) - String - required
    method:   GET, POST, PUT, DELETE, PATCH or HEAD - String - required
    path:   The path, like /v3/maintenance/status - String - required
admin
etcd request "{\"url\": \"http://127.0.0.1:2379\"}" "GET" "/version"
mentdb
{"etcdserver":"3.5.17","etcdcluster":"3.5.0"}

etcd request <config> <method> <path> <json_body>


Description

    The raw HTTP escape hatch with a JSON body

Parameters

    config:   The etcd configuration as JSON: url (http://127.0.0.1:2379; endpoint is accepted as an alias; https checked with the trust store of the JDK), username and password (the name of a secret: secret set) when the authentication is enabled, allow_plain (false: a password over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB, the largest response) - String - required
    method:   The method - String - required
    path:   The path - String - required
    json_body:   The JSON body - String - required
admin
etcd request "{\"url\": \"http://127.0.0.1:2379\"}" "POST" "/v3/cluster/member/list" "{}"
mentdb
{"header":{"cluster_id":"13767295136869288227","member_id":"3307425987971480646","raft_term":"2"},"members":[{"ID":"3307425987971480646","name":"default","peerURLs":["http://127.0.0.1:2380"],"clientURLs":["http://127.0.0.1:2379"]}]}