Skip to main content
Donate to the Python Software Foundation or Purchase a PyCharm License to Benefit the PSF! Donate Now

Autodiscovery & Clustering for CouchDB 2.0 with Kubernetes

Project description

# couchdiscover

Maintainer: Joe Black <>

Other repositories:


## Description

Utilizes the Kubernetes and CouchDB 2.0 clustering API's for automating the process of creating a CouchDB 2.0 Cluster. The reqirements here vary significantly compared to the predecessor BigCouch.

This module has an entrypoint stub called `couchdiscover` that will be created upon installation with setuptools.

This tool is meant to be used in a kubernetes cluster as a sidecar container.

See the docker project for this: [github](

## Environment variables used by couchdiscover:

### `couchdb` container:
* `COUCHDB_ADMIN_USER`: username to use when enabling the node, required.
* `COUCHDB_ADMIN_PASS`: password to use when enabling the node, required.
* `ERLANG_COOKIE`: cookie value to use as the `.erlang.cookie`, not required, fails back to insecure cookie value when not set.
* `COUCHDB_CLUSTER_SIZE`: not required, overrides the value of `spec.replicas` in the statefulset, should rarely be necessary to set. Don't set unless you know what you're doing.

### `couchdiscover` container:
* `LOG_LEVEL`: logging level to output container logs for. Defaults to `INFO`, most logs are either INFO or WARNING level.

## How information is discovered

In order to best use something that is essentially "zero configuration," it helps to understand how the necessary information is obtained from the environment and api's.

1. Initially a great deal of information is obtained by grabbing the hostname of the container that's part of a statefulset and parsing it. This is how the namespace is determined, how hostnames are calculated later, the name of the statefulset to look for in the api, the name of the headless service, the node name, the index, whether a node is master or not, etc.

2. The kubernetes api is used to grab the statefulset and entrypoint objects. The entrypoint object is parsed to obtain the `hosts` list. Then the statefulset is parsed for the ports, then the environment is resolved, fetching any externally referenced configmaps or secrets that are necessary. Credentials are resolved by looking through the environment for the keys: `COUCHDB_ADMIN_USER`, `COUCHDB_ADMIN_PASS`. Finally the expected cluster size is set to the number of replicas in the fetched statefulset. You can override this as detailed in the above notes section, but should be completely unnecessary for most cases.

## Main logic

The main logic is performed in the `manage` module's `ClusterManager` object's `run` method. I think most of it is relatively straighforward.

# couchdiscover.manage.ClusterManager
def run(self):
"""Main logic here, this is where we begin once all environment
information has been retrieved."""'Starting couchdiscover: %s', self.couch)
if self.couch.disabled:'Cluster disabled, enabling')
elif self.couch.finished:'Cluster already finished')

if self.env.first_node:"Looks like I'm the first node")
if self.env.single_node_cluster:'Single node cluster detected')
else:"Looks like I'm not the first node")
if self.env.last_node:"Looks like I'm the last node")
else:"Looks like I'm not the last node")

Project details

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
couchdiscover-0.2.3.tar.gz (12.8 kB) Copy SHA256 hash SHA256 Source None

Supported by

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