Client Endpoints

Common parameters

dc:By default, the datacenter of the agent is queried ; however, the dc can be provided. watch:Performs a blocking query. Value can be a ObjectIndex, or a Tuple[ObjectIndex, timedelta]. consistency:Change client behavior about consistency. session:A session Object. index:An index Object. token:A token Object.

Most of endpoints that returns ConsulValue supports blocking queries and consistency modes.

ACL

Create, update, destroy, and query ACL tokens.

Most of the operations relies on ACL token with sufficant rights. Here is the way aioconsul manage tokens:

token = {"Name": "my-app-token"}
token_id = await client.acl.create(token)
token.update(token_id)
token.update({"Rules": """
    key "" {
        policy = "read"
    }
    key "private/" {
        policy = "deny"
    }
"""})
token_id = await client.acl.update(token)

token, meta = await client.acl.info(token_id)
clone_id, meta = await client.acl.clone(token_id)

destroyed = await client.acl.destroy(token_id)

tokens, meta = await client.acl.items()
info = await client.acl.replication()

Agent

Interact with the local Consul agent.

Example:

obj = await client.agent.info()
disabled = await client.agent.disable(reason="migrating")
enabled = await client.agent.enable(reason="migration done")

Agent’s Checks

Manage local checks.

Example:

check = {
    "ID": "mem",
    "Name": "Memory utilization",
    "TTL": "15s"
    "Interval": "10s"
}
registered = await client.checks.register(check)
mapping = await client.checks.items()
marked = await client.checks.critical(check, note="Fatal")
marked = await client.checks.warning(check, note="Warning")
marked = await client.checks.passing(check, note="Back to normal")
deregistered = await client.checks.deregister(check)

Agent’s Members

Manage local serf agent cluster

Example:

joined = await client.checks.join("10.11.12.13", wan=True)
members = await client.members.items()
leaving = await client.checks.force_leave("my-node")

Agent’s Services

Manage local services.

Example:

service = {
    "ID": "redis1",
    "Name": "redis",
    "Tags": [
        "master",
        "v1"
    ],
}
registered = await client.services.register(service)
services = await client.services.items()
disabled = await client.services.disable(service, reason="migrating")
enabled = await client.services.enable(service, reason="migration done")
deregistered = await client.services.deregister(service)

Catalog

Manage catalog.

Example:

definitions = {
  "Node": "foobar",
  "Address": "192.168.10.10",
  "Service": {
    "ID": "redis1",
    "Service": "redis",
    "Tags": [ "master", "v1" ],
    "Address": "127.0.0.1",
    "Port": 8000
  },
  "Check": {
    "Node": "foobar",
    "CheckID": "service:redis1",
    "Name": "Redis health check",
    "Notes": "Script based health check",
    "Status": "passing",
    "ServiceID": "redis1"
  }
}

registered = await client.catalog.register(definitions)
datacenters = await client.catalog.datacenters()
nodes, meta = await client.catalog.nodes(near="_self")
services, meta = await client.catalog.node("foobar", watch=(meta, "30s"))
services, meta = await client.catalog.services(consistency="stale")
nodes, meta = await client.catalog.service("redis1", tag="prod")
deregistered = await client.catalog.deregister({
    "Node": "foobar",
    "Address": "192.168.10.10"
})

Events

Manage events.

Example:

id = await client.event.fire("my-event", service="my-service")
collection, meta = await client.event.items("my-event")

Health Checks

Consult health.

Example:

collection, meta = await client.health.node("my-node")
collection, meta = await client.health.checks("my-service")
collection, meta = await client.health.state("passing", near="_self")

Key/Value Store

Manage kv store.

Common operations example:

keys, meta = await client.kv.keys("my/key", separator="/")
setted = await client.kv.set("my/key", b"my value")
obj, meta = await client.kv.get("my/key")
deleted = await client.kv.delete("my/key")

Tree operations example:

collection, meta = await client.kv.get_tree("my/key", separator="/")
deleted = await client.kv.delete_tree("my/key", separator="/")

CAS operations example:

setted = await client.kv.cas("my/key", b"my value", index=meta)
deleted = await client.kv.delete_cas("my/key", index=meta)

Locked operations example:

locked = await client.kv.lock("my/key", b"my value", session=session_id)
unlocked = await client.kv.unlock("my/key", b"my value", session=session_id)

Key/Value Transactions

These same operations can be done in a transactional way:

results, meta = await client.kv.prepare()\
                        .set("my/key", b"my value")\
                        .get("my/key")\
                        .execute()

Network Coordinates

Consult network coordinates.

Example:

datacenters = await client.coordinate.datacenters()
collection, meta = await client.coordinate.nodes()

Operator

Manage raft.

Example:

obj = await client.operator.configuration()
obj = await client.operator.peer_delete("10.11.12.13")

Prepared Queries

Manage prepared queries.

Example:

collection = await client.query.items()
obj = await client.query.create({""})
obj = await client.query.read({""})
obj = await client.query.explain({""})
updated = await client.query.update({""})
deleted = await client.query.delete({""})
results = await client.query.execute({""})

Session

Manage sessions.

Example:

obj = await client.session.create({""})
destroyed = await client.session.destroy({""})
obj, meta = await client.session.info({""})
obj, meta = await client.session.renew({""})
collection, meta = await client.session.node("my-node")
collection, meta = await client.session.items()

Status

Consult status.

Example:

addr = await client.status.leader()
addrs = await client.status.peers()