Consulate is a Python client library and set of application for the Consul service discovery and configuration system.
Consulate is available via via pypi and can be installed with easy_install or pip:
pip install consulate
Consulate comes with two command line utilities that make working with Consul easier from a management perspective. The consulate
application provides a cli wrapper for common tasks performed.
The passport
application has been moved to a stand-alone application and is available at https://github.com/gmr/passport.
The consulate application provides a CLI interface for registering a service, backing up and restoring the contents of the KV database, and actions for getting, setting, and deleting keys from the KV database.
usage: consulate [-h] [--api-host API_HOST] [--api-port API_PORT]
[--datacenter DATACENTER]
{register,kv} ...
optional arguments:
-h, --help show this help message and exit
--api-scheme API_SCHEME
The scheme to use for connecting to Consul with
--api-host API_HOST The consul host to connect on
--api-port API_PORT The consul API port to connect to
--datacenter DATACENTER
The datacenter to specify for the connection
Commands:
{register,kv}
register Register a service for this node
kv Key/Value Database Utilities
Service Registration Help:
usage: consulate register [-h] [-s SERVICE_ID] [-t TAGS]
{check,no-check,ttl} ... name port
positional arguments:
name The service name
port The port the service runs on
optional arguments:
-h, --help show this help message and exit
-s SERVICE_ID, --service-id SERVICE_ID
Specify a service ID
-t TAGS, --tags TAGS Specify a comma delimited list of tags
Service Check Options:
{check,no-check,ttl}
check Define an external script-based check
no-check Do not enable service monitoring
ttl Define a duration based TTL check
KV Database Utilities Help:
usage: consulate kv [-h] {backup,restore,ls,mkdir,get,set,rm,del} ...
optional arguments:
-h, --help show this help message and exit
Key/Value Database Utilities:
{backup,restore,ls,mkdir,get,set,rm,del}
backup Backup to stdout or a JSON file
restore Restore from stdin or a JSON file
ls List all of the keys
mkdir Create a folder
get Get a key from the database
set Set a key in the database
rm Remove a key from the database
del Deprecated method to remove a key
Locking Operations Help:
usage: consulate [-h] run_once [-i INTERVAL] prefix command
positional arguments:
prefix the name of the lock which will be held in Consul.
command the command to run
optional arguments:
-h, --help show this help message and exit
-i, --interval hold the lock for INTERVAL seconds
The following examples highlight the usage of Consulate and does not document the scope of the full Consulate API.
Using Consulate with the Consul kv database:
consul = consulate.Consul()
# Set the key named release_flag to True
consul.kv['release_flag'] = True
# Get the value for the release_flag, if not set, raises AttributeError
try:
should_release_feature = consul.kv['release_flag']
except AttributeError:
should_release_feature = False
# Delete the release_flag key
del consul.kv['release_flag']
# Find all keys that start with "fl"
consul.kv.find('fl')
# Find all keys that start with "feature_flag" terminated by "/" separator
consul.kv.find('feature_flag', separator='/')
# Check to see if a key called "foo" is set
if "foo" in consul.kv:
print 'Already Set'
# Return all of the items in the key/value store
consul.kv.items()
Working with the Consulate.agent API:
consul = consulate.Consul()
# Get all of the service checks for the local agent
checks = consul.agent.checks()
# Get all of the services registered with the local agent
services = consul.agent.services()
# Add a service to the local agent
consul.agent.service.register('redis',
port=6379,
tags=['master'],
ttl='10s')
Fetching health information from Consul:
consul = consulate.Session()
# Get the health of a individual node
health = consul.health.node('my-node')
# Get all checks that are critical
checks = consul.heath.state('critical')
For more examples, check out the Consulate documentation.