Consul
Use HashiCorp Consul: key/value store with check-and-set, sessions and locks, services and health checks. Typical uses: read shared configuration, take a lock between servers, find a service.
consul putconsul putconsul getconsul listconsul listconsul deleteconsul deleteconsul pingconsul infoconsul session_createconsul session_createconsul lock_acquireconsul lock_acquireconsul lock_releaseconsul session_renewconsul session_destroyconsul registerconsul servicesconsul serviceconsul healthconsul healthconsul nodesconsul deregisterconsul requestconsul request

consul put <config> <key> <value>


Description

    Write a value. Returns {key, stored}: stored is false when a condition (cas, acquire) failed

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
    key:   The key, like app/config/db (no leading /) - String - required
    value:   The value - String - required
admin
consul put "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "app/config/db" "postgres://db1/sales"
mentdb
{"key": "app/config/db", "stored": true}

consul put <config> <key> <value> <json_params>


Description

    Write with parameters: flags (an integer kept with the value), cas (the modify_index read before: write only if unchanged; 0: only if absent), acquire or release (a session id: see consul lock_acquire)

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
    key:   The key, like app/config/db (no leading /) - String - required
    value:   The value - String - required
    json_params:   The parameters - String - required
admin
consul put "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "app/config/mode" "prod" "{\"flags\": 42}"
mentdb
{"key": "app/config/mode", "stored": true}
only if absent: it exists (fixed result: real Consul 1.20.1, -dev mode with ACL)
admin
consul put "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "app/config/mode" "dev" "{\"cas\": 0}"
mentdb
{"key": "app/config/mode", "stored": false}

consul get <config> <key>


Description

    Read a value; null if the key does not exist

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
    key:   The key, like app/config/db (no leading /) - String - required
admin
consul get "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "app/config/db"
mentdb
postgres://db1/sales
no such key (fixed result: real Consul 1.20.1, -dev mode with ACL)
admin
consul get "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "nothing"
mentdb
null

consul list <config> <prefix>


Description

    The keys under a prefix as rows (recurse)

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
    prefix:   The prefix ("" = every key) - String - required
admin
consul list "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "app/"
mentdb
[{"key": "app/config/db", "value": "postgres://db1/sales", "flags": 0, "create_index": 22, "modify_index": 22, "lock_index": 0, "session": null}, {"key": "app/config/mode", "value": "prod", "flags": 42, "create_index": 23, "modify_index": 23, "lock_index": 0, "session": null}]

consul list <config> <prefix> <json_params>


Description

    List with parameters: keys_only (true: a JSON array of keys), separator (with keys_only: stop at the separator, like folders), limit (10000; more keys than this is an error), partial (true: the first limit keys instead of the error)

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
    prefix:   The prefix - String - required
    json_params:   The parameters - String - required
admin
consul list "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "" "{\"keys_only\": true, \"separator\": \"/\"}"
mentdb
["app/"]

consul delete <config> <key>


Description

    Delete a key. Returns {deleted: 1} (also when it did not exist: Consul does not count the keys)

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
    key:   The key, like app/config/db (no leading /) - String - required
admin
consul delete "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "app/config/mode"
mentdb
{"deleted": 1}

consul delete <config> <key> <json_params>


Description

    Delete with parameters: recurse (true: every key under the prefix; an empty prefix, every key, also needs confirm true), cas (delete only if the modify_index is still this one: {deleted: 0} otherwise)

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
    key:   The key, like app/config/db (no leading /) - String - required
    json_params:   The parameters - String - required
admin
consul delete "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "app/" "{\"recurse\": true}"
mentdb
{"deleted": 1}

consul ping <config>


Description

    The address of the leader of the cluster (no ACL needed): {leader}

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
admin
consul ping "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}"
mentdb
{"leader": "127.0.0.1:8300"}

consul info <config>


Description

    The local agent: {version, revision, datacenter, primary_datacenter, node, node_id, server} (ACL agent:read)

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
admin
consul info "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}"
mentdb
{"version": "1.20.1", "revision": "920cc7c6", "datacenter": "dc1", "primary_datacenter": "dc1", "node": "kv-dev", "node_id": "6de840e1-1b1a-b66e-b434-eab2349585b4", "server": true}

consul session_create <config>


Description

    Create a session with the default settings (no ttl: it lives with the node). Returns its id

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
admin
consul session_create "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}"
mentdb
0f6c2b1e-8d3a-4b7c-9e15-3a2d4c6b8f01

consul session_create <config> <json_params>


Description

    Create a session with parameters: name, ttl (seconds, 10 to 86400: renew it with consul session_renew), behavior (release or delete: what happens to the locked keys when the session ends), lock_delay (seconds, 15 by default in Consul), node

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
    json_params:   The parameters - String - required
admin
consul session_create "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "{\"name\": \"import-job\", \"ttl\": 120, \"behavior\": \"release\"}"
mentdb
7a1e9c3d-2b4f-4e6a-8c0d-5f3b1a9e7d22

consul lock_acquire <config> <key> <session_id>


Description

    Take a lock on a key for a session (acquire). Returns 1, or 0 if another session holds it

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
    key:   The key, like app/config/db (no leading /) - String - required
    session_id:   The session id given by consul session_create - String - required
admin
consul lock_acquire "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "locks/import" "0f6c2b1e-8d3a-4b7c-9e15-3a2d4c6b8f01"
mentdb
1

consul lock_acquire <config> <key> <session_id> <value>


Description

    Take a lock and write a value at the same time (the name of the holder, for example)

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
    key:   The key, like app/config/db (no leading /) - String - required
    session_id:   The session id given by consul session_create - String - required
    value:   The value - String - required
admin
consul lock_acquire "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "locks/import" "7a1e9c3d-2b4f-4e6a-8c0d-5f3b1a9e7d22" "worker-2"
mentdb
0

consul lock_release <config> <key> <session_id>


Description

    Release a lock (release). Returns 1, or 0 if the session did not hold it

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
    key:   The key, like app/config/db (no leading /) - String - required
    session_id:   The session id given by consul session_create - String - required
admin
consul lock_release "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "locks/import" "0f6c2b1e-8d3a-4b7c-9e15-3a2d4c6b8f01"
mentdb
1

consul session_renew <config> <session_id>


Description

    Renew a session with a ttl. Returns 1, or 0 if it does not exist any more

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
    session_id:   The session id given by consul session_create - String - required
admin
consul session_renew "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "7a1e9c3d-2b4f-4e6a-8c0d-5f3b1a9e7d22"
mentdb
1

consul session_destroy <config> <session_id>


Description

    End a session: its locks are released (or their keys deleted). Returns 1

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
    session_id:   The session id given by consul session_create - String - required
admin
consul session_destroy "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "7a1e9c3d-2b4f-4e6a-8c0d-5f3b1a9e7d22"
mentdb
1

consul register <config> <json_service>


Description

    Register a service on the local agent: name, id, address, port, tags, meta (texts), check_ttl (seconds) or check_http (URL) with check_interval (10 s). Returns 1

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
    json_service:   The service - String - required
admin
consul register "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "{\"name\": \"billing\", \"id\": \"billing-1\", \"address\": \"10.0.0.5\", \"port\": 8080, \"tags\": [\"v2\"], \"meta\": {\"team\": \"finance\"}, \"check_ttl\": 60}"
mentdb
1

consul services <config>


Description

    The services of the catalog as rows {service, tags}, sorted by name

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
admin
consul services "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}"
mentdb
[{"service": "billing", "tags": ["v2"]}, {"service": "consul", "tags": []}]

consul service <config> <service>


Description

    The instances of a service in the catalog: rows {node, node_address, service_id, service, address, port, tags, meta}

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
    service:   The name of the service - String - required
admin
consul service "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "billing"
mentdb
[{"node": "kv-dev", "node_address": "127.0.0.1", "service_id": "billing-1", "service": "billing", "address": "10.0.0.5", "port": 8080, "tags": ["v2"], "meta": {"team": "finance"}}]

consul health <config> <service>


Description

    The instances of a service with their checks: rows {node, service_id, service, address, port, tags, status, checks}

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
    service:   The name of the service - String - required
admin
consul health "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "billing"
mentdb
[{"node": "kv-dev", "service_id": "billing-1", "service": "billing", "address": "10.0.0.5", "port": 8080, "tags": ["v2"], "status": "critical", "checks": [{"name": "Serf Health Status", "status": "passing", "output": "Agent alive and reachable"}, {"name": "Service 'billing' check", "status": "critical", "output": ""}]}]

consul health <config> <service> <json_params>


Description

    Health with parameters: passing (true: only the instances whose checks all pass), tag

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
    service:   The name of the service - String - required
    json_params:   The parameters - String - required
admin
consul health "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "billing" "{\"passing\": true}"
mentdb
[]

consul nodes <config>


Description

    The nodes of the catalog: rows {node, id, address, datacenter, meta}

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
admin
consul nodes "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}"
mentdb
[{"node": "kv-dev", "id": "6de840e1-1b1a-b66e-b434-eab2349585b4", "address": "127.0.0.1", "datacenter": "dc1", "meta": {"consul-version": "1.20.1"}}]

consul deregister <config> <service_id>


Description

    Remove a service instance from the local agent. Returns 1

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
    service_id:   The id of the instance - String - required
admin
consul deregister "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "billing-1"
mentdb
1

consul request <config> <method> <path>


Description

    The raw HTTP escape hatch: a path of the HTTP API (the token is sent). Returns the response text of a 2xx

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
    method:   GET, POST, PUT, DELETE, PATCH or HEAD - String - required
    path:   The path with its query, like /v1/catalog/datacenters - String - required
admin
consul request "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "GET" "/v1/catalog/datacenters"
mentdb
[ "dc1" ]

consul request <config> <method> <path> <json_body>


Description

    The raw HTTP escape hatch with a JSON body

Parameters

    config:   The Consul configuration as JSON: url (http://127.0.0.1:8500; endpoint is accepted as an alias), token (or token: the name of a secret (secret set); sent as X-Consul-Token), datacenter, allow_plain (false: a token over http is refused unless the host is localhost, 127.0.0.1 or ::1), timeout_ms (10000), max_bytes (64 MB) - String - required
    method:   The method - String - required
    path:   The path - String - required
    json_body:   The JSON body - String - required
admin
consul request "{\"url\": \"http://127.0.0.1:8500\", \"token\": \"consul_token\"}" "PUT" "/v1/txn" "[{\"KV\": {\"Verb\": \"set\", \"Key\": \"txn/a\", \"Value\": \"MQ==\"}}, {\"KV\": {\"Verb\": \"set\", \"Key\": \"txn/b\", \"Value\": \"Mg==\"}}]"
mentdb
{ "Results": [ { "KV": { "LockIndex": 0, "Key": "txn/a", "Flags": 0, "Value": null, "CreateIndex": 34, "ModifyIndex": 34 } }, { "KV": { "LockIndex": 0, "Key": "txn/b", "Flags": 0, "Value": null, "CreateIndex": 34, "ModifyIndex": 34 } } ], "Errors": null }