Skip to main content

clusterdock is a framework for creating Docker-based container clusters

Project description


.. image::

.. image::

.. image::
:alt: Documentation Status

.. image::


**clusterdock** is a Python 3 project that enables users to build,
start, and manage Docker container-based clusters. It uses a pluggable
system for defining new types of clusters using folders called *topologies* and
is a swell project, if I may say so myself.


"I hate reading, make this quick."

Before doing anything, install a recent version of `Docker`_ to your machine. Next,
clone a clusterdock topology to your machine. For this example,
we'll use the `nodebase topology`_.
Assuming that you've already installed **clusterdock**, you could start a 2-node cluster:

.. _Docker:
.. _nodebase topology:

.. code-block:: console

$ git clone
$ clusterdock start topology_nodebase
2017-08-03 10:04:18 PM clusterdock.models INFO Starting cluster on network (cluster) ...
2017-08-03 10:04:18 PM clusterdock.models INFO Starting node node-1.cluster ...
2017-08-03 10:04:19 PM clusterdock.models INFO Starting node node-2.cluster ...
2017-08-03 10:04:20 PM clusterdock.models INFO Cluster started successfully (total time: 00:00:01.621).

To SSH into a node and look around:

.. code-block:: console

$ clusterdock ssh node-1.cluster
[root@node-1 ~]# ls -l / | head
total 64
dr-xr-xr-x 1 root root 4096 May 19 20:48 bin
drwxr-xr-x 5 root root 360 Aug 4 05:04 dev
drwxr-xr-x 1 root root 4096 Aug 4 05:04 etc
drwxr-xr-x 2 root root 4096 Sep 23 2011 home
dr-xr-xr-x 7 root root 4096 Mar 4 2015 lib
dr-xr-xr-x 1 root root 4096 May 19 20:48 lib64
drwx------ 2 root root 4096 Mar 4 2015 lost+found
drwxr-xr-x 2 root root 4096 Sep 23 2011 media
drwxr-xr-x 2 root root 4096 Sep 23 2011 mnt
[root@node-1 ~]# exit

To see the complete usage message for the topology:

.. code-block:: console

$ clusterdock start topology_nodebase -h
usage: clusterdock start [-h] [--node-disks map] [--always-pull]
[--namespace ns] [--network nw] [-o sys] [-r url]
[--nodes node [node ...]]

Start a nodebase cluster

positional arguments:
topology A clusterdock topology directory

optional arguments:
-h, --help show this help message and exit
--always-pull Pull latest images, even if they're available locally
(default: False)
--namespace ns Namespace to use when looking for images (default:
--network nw Docker network to use (default: cluster)
-o sys, --operating-system sys
Operating system to use for cluster nodes (default:
-r url, --registry url
Docker Registry from which to pull images (default:

nodebase arguments:
--node-disks map Map of node names to block devices (default: None)

Node groups:
--nodes node [node ...]
Nodes of the nodes group (default: ['node-1',

When you're done and want to clean up:

.. code-block:: console

$ clusterdock manage nuke
2017-08-03 10:06:28 PM clusterdock.actions.manage INFO Stopping and removing all containers ...
2017-08-03 10:06:30 PM clusterdock.actions.manage INFO Removing all user-defined networks ...


1.2.0 (2017.10.23)

* Changed return type of :py:meth:`clusterdock.models.Cluster.execute`
and :py:meth:`clusterdock.models.NodeGroup.execute`.
* Added support for node devices.

1.1.0 (2017.09.21)

* Updated :py:meth:`clusterdock.models.Node.execute` to return a namedtuple with the
command's exit code and output.
* Fixed bug around ``quiet`` argument to :py:meth:`clusterdock.models.Node.execute`.
* Added support for specifying ``host:container`` port mappings when creating a node.
* Added ``ip_address`` attribute to :py:class:`clusterdock.models.Node`.

1.0.7 (2017.09.18)

* Removed :py:const:`DEFAULT_NAMESPACE` to let topologies define their own.

1.0.6 (2017.09.04)

* Added :py:meth:`clusterdock.models.Node.put_file` and :py:meth:`clusterdock.models.Node.get_file`.
* Made ``network`` an instance attribute of :py:class:`clusterdock.models.Cluster`.

1.0.5 (2017.09.02)

* Added logic to pull missing images to :py:mod:`clusterdock.models`.

1.0.4 (2017.09.02)

* Fixed missing install requirement.

1.0.3 (2017.09.02)

* Cleaned up :py:class:`clusterdock.models.Node` API.
* Added wait_for_permission and join_url_parts utility functions.

1.0.2 (2017.08.04)

* Updated how Cluster and Node objects are initialized.
* Added project logo.
* Doc improvements.

1.0.1 (2017.08.03)

* First release on PyPI.

Project details

Download files

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

Files for clusterdock, version 1.2.0
Filename, size File type Python version Upload date Hashes
Filename, size clusterdock-1.2.0.tar.gz (35.2 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page