Skip to main content

A Client library for the Consul

Project description

Consulate: A Consul Client Library
==================================

Consulate is a Python client library and set of application for the Consul
service discovery and configuration system.

|Version| |Downloads| |Status| |Coverage| |License|

Installation
------------

Consulate is available via pypi_ and can be installed with easy_install or pip:

.. code:: bash

pip install consulate

Documentation
-------------
Documentation is available at https://consulate.readthedocs.org

Command Line Utilities
----------------------
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 and the ``passport`` application
implements configuration file templating.

consulate
^^^^^^^^^
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.

.. code:: bash

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-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:

.. code:: bash

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:

.. code:: bash

usage: consulate kv [-h] {backup,restore,get,set,del} ...

optional arguments:
-h, --help show this help message and exit

Key/Value Database Utilities:
{backup,restore,get,set,del}
backup Backup to a JSON file
restore Restore from a JSON file
get Get a key from the database
set Set a key in the database
del Delete a key from the database

passport
^^^^^^^^
Passport provides a template rendering engine that writes out configuration
files based upon information available in the consul cluster.

.. code:: bash

usage: passport [-h] [-t TEMPLATE] [-d DESTINATION]

Render templates from Consul

optional arguments:
-h, --help show this help message and exit
-t TEMPLATE, --template TEMPLATE
The path to the template
-d DESTINATION, --destination DESTINATION
The path to write the rendered template to

As an example, the following template is stored in the KV database as
``templates/memcached/memcached.conf``

.. code:: python

{% set nodes = ['%s:%s' % (r['Address'], r['ServicePort']) for r in consul.catalog.service('memcached')] %}

[memcached]
servers = {{ ','.join(nodes) }}

Invoking passport will render the file with a list of all memcached nodes to
``/etc/memcached.conf``.

.. code:: bash

passport templates/memcached/memcached.conf /etc/memcached.conf

And the output would look something like:

.. code:: ini

[memcached]
servers = 172.17.0.7:11211,172.17.0.8:11211

Template rendering is done via the `Tornado Template <https://tornado.readthedocs.org/en/latest/template.html>`_ engine.

API Usage Examples
------------------
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:`

.. code:: python

session = consulate.Consulate()

# Set the key named release_flag to True
session.kv.release_flag = True

# Get the value for the release_flag, if not set, raises AttributeError
try:
should_release_feature = session.kv.release_flag
except AttributeError:
should_release_feature = False

# Delete the release_flag key
del session.kv.release_flag

# Find all keys that start with "fl"
session.kv.find('fl')

# Check to see if a key called "foo" is set
if "foo" in session.kv:
print 'Already Set'

# Return all of the items in the key/value store
session.kv.items()

`Working with the Consulate.agent API:`

.. code:: python

session = consulate.Consulate()

# Get all of the service checks for the local agent
checks = session.agent.checks()

# Get all of the services registered with the local agent
services = session.agent.services()

# Add a service to the local agent
session.agent.service.register('redis',
port=6379,
tags=['master'],
check={'script': None,
'interval': None,
'ttl': '60s'})


`Fetching health information from Consul:`

.. code:: python

session = consulate.Consulate()

# Get the health of a individual node
health = session.health.node('my-node')

# Get all checks that are critical
checks = session.heath.state('critical')

For more examples, check out the Consulate documentation.

.. |Version| image:: https://badge.fury.io/py/consulate.svg?
:target: http://badge.fury.io/py/consulate

.. |Status| image:: https://travis-ci.org/gmr/consulate.svg?branch=master
:target: https://travis-ci.org/gmr/consulate

.. |Coverage| image:: https://coveralls.io/repos/gmr/consulate/badge.png
:target: https://coveralls.io/r/gmr/consulate

.. |Downloads| image:: https://pypip.in/d/consulate/badge.svg?
:target: https://pypi.python.org/pypi/consulate

.. |License| image:: https://pypip.in/license/consulate/badge.svg?
:target: https://consulate.readthedocs.org

Release history Release notifications

History Node

0.6.0

History Node

0.5.1

History Node

0.5.0

History Node

0.4.0

History Node

0.3.0

History Node

0.2.0

History Node

0.1.2

This version
History Node

0.1.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
consulate-0.1.1.tar.gz (13.4 kB) Copy SHA256 hash SHA256 Source None May 6, 2014

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page