consul.api.catalog module

class consul.api.catalog.Catalog(agent)

Bases: object

register(node, address, service=None, check=None, dc=None, token=None, node_meta=None)

A low level mechanism for directly registering or updating entries in the catalog. It is usually recommended to use agent.service.register and agent.check.register, as they are simpler and perform anti-entropy.

node is the name of the node to register.

address is the ip of the node.

service is an optional service to register. if supplied this is a dict:

{
    "Service": "redis",
    "ID": "redis1",
    "Tags": [
        "master",
        "v1"
    ],
    "Port": 8000
}

where

Service is required and is the name of the service

ID is optional, and will be set to Service if not provided. Note ID must be unique for the given node.

Tags and Port are optional.

check is an optional check to register. if supplied this is a dict:

{
    "Node": "foobar",
    "CheckID": "service:redis1",
    "Name": "Redis health check",
    "Notes": "Script based health check",
    "Status": "passing",
    "ServiceID": "redis1"
}

dc is the datacenter of the node and defaults to this agents datacenter.

token is an optional `ACL token`_ to apply to this request.

node_meta is an optional meta data used for filtering, a dictionary formatted as {k1:v1, k2:v2}.

This manipulates the health check entry, but does not setup a script or TTL to actually update the status. The full documentation is here.

Returns True on success.

Parameters:

token (str | None)

deregister(node, service_id=None, check_id=None, dc=None, token=None)

A low level mechanism for directly removing entries in the catalog. It is usually recommended to use the agent APIs, as they are simpler and perform anti-entropy.

node and dc specify which node on which datacenter to remove. If service_id and check_id are not provided, all associated services and checks are deleted. Otherwise only one of service_id and check_id should be provided and only that service or check will be removed.

token is an optional `ACL token`_ to apply to this request.

Returns True on success.

Parameters:

token (str | None)

datacenters()

Returns all the datacenters that are known by the Consul server.

nodes(index=None, wait=None, consistency=None, dc=None, near=None, token=None, node_meta=None)

Returns a tuple of (index, nodes) of all nodes known about in the dc datacenter. dc defaults to the current datacenter of this agent.

index is the current Consul index, suitable for making subsequent calls to wait for changes since this query was last run.

wait the maximum duration to wait (e.g. ’10s’) to retrieve a given index. this parameter is only applied if index is also specified. the wait time by default is 5 minutes.

near is a node name to sort the resulting list in ascending order based on the estimated round trip time from that node

consistency can be either ‘default’, ‘consistent’ or ‘stale’. if not specified consistency will the consistency level this client was configured with.

token is an optional `ACL token`_ to apply to this request.

node_meta is an optional meta data used for filtering, a dictionary formatted as {k1:v1, k2:v2}.

The response looks like this:

(index, [
    {
        "Node": "baz",
        "Address": "10.1.10.11"
    },
    {
        "Node": "foobar",
        "Address": "10.1.10.12"
    }
])

Parameters:

token (str | None)

services(index=None, wait=None, consistency=None, dc=None, token=None, node_meta=None)

Returns a tuple of (index, services) of all services known about in the dc datacenter. dc defaults to the current datacenter of this agent.

index is the current Consul index, suitable for making subsequent calls to wait for changes since this query was last run.

wait the maximum duration to wait (e.g. ’10s’) to retrieve a given index. this parameter is only applied if index is also specified. the wait time by default is 5 minutes.

consistency can be either ‘default’, ‘consistent’ or ‘stale’. if not specified consistency will the consistency level this client was configured with.

token is an optional `ACL token`_ to apply to this request.

node_meta is an optional meta data used for filtering, a dictionary formatted as {k1:v1, k2:v2}.

The response looks like this:

(index, {
    "consul": [],
    "redis": [],
    "postgresql": [
        "master",
        "slave"
    ]
})

The main keys are the service names and the list provides all the known tags for a given service.

Parameters:

token (str | None)

node(node, index=None, wait=None, consistency=None, dc=None, token=None)

Returns a tuple of (index, services) of all services provided by node.

index is the current Consul index, suitable for making subsequent calls to wait for changes since this query was last run.

wait the maximum duration to wait (e.g. ’10s’) to retrieve a given index. this parameter is only applied if index is also specified. the wait time by default is 5 minutes.

consistency can be either ‘default’, ‘consistent’ or ‘stale’. if not specified consistency will the consistency level this client was configured with.

dc is the datacenter of the node and defaults to this agents datacenter.

token is an optional `ACL token`_ to apply to this request.

The response looks like this:

(index, {
    "Node": {
        "Node": "foobar",
        "Address": "10.1.10.12"
    },
    "Services": {
        "consul": {
            "ID": "consul",
            "Service": "consul",
            "Tags": null,
            "Port": 8300
        },
        "redis": {
            "ID": "redis",
            "Service": "redis",
            "Tags": [
                "v1"
            ],
            "Port": 8000
        }
    }
})

Parameters:

token (str | None)

service(service, **kwargs)

Returns a tuple of (index, nodes) of the nodes providing service in the dc datacenter. dc defaults to the current datacenter of this agent.

index is the current Consul index, suitable for making subsequent calls to wait for changes since this query was last run.

wait the maximum duration to wait (e.g. ’10s’) to retrieve a given index. this parameter is only applied if index is also specified. the wait time by default is 5 minutes.

If tag is provided, the list of nodes returned will be filtered by that tag.

near is a node name to sort the resulting list in ascending order based on the estimated round trip time from that node

consistency can be either ‘default’, ‘consistent’ or ‘stale’. if not specified consistency will the consistency level this client was configured with.

token is an optional `ACL token`_ to apply to this request.

node_meta is an optional meta data used for filtering, a dictionary formatted as {k1:v1, k2:v2}.

The response looks like this:

(index, [
    {
        "Node": "foobar",
        "Address": "10.1.10.12",
        "ServiceID": "redis",
        "ServiceName": "redis",
        "ServiceTags": null,
        "ServicePort": 8000
    }
])

Parameters:

service (str)

connect(service, **kwargs)

Returns a tuple of (index, nodes) of the nodes providing connect-capable service in the dc datacenter. dc defaults to the current datacenter of this agent.

Request arguments and response format are the same as catalog.service

Parameters:

service (str)