<type>documentation</type>
<domain>plugins</domain>
<id>cluster</id>
<title>Cluster Plugins</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>pro+</product>

Cluster plugins can be used to add support for a new type of container orchestration
system to Wing Pro's support for containers. Wing Pro comes with support for Docker
Compose, which is implemented by the file ``plugins/cluster/dockercompose.py`` in the Wing
installation directory. Other container orchestration systems may be supported by adding a
similar file for each container orchestration system.

**Requirements**

In order to work with Wing, container orchestration systems must satisfy the following
requirements:

(1) The cluster configuration used by the container orchestration system must allow
    adding environment variables and host->container file mappings to specific services 
    in the cluster
(2) Containers in a cluster that are to host debugged parts of the application must be able 
    to connect to Wing on the host system using TCP/IP
(3) Plugins must exist for the container system(s) used by the orchestration system and
    it must be possible to start instances of individual containers using the container
    system plugins.

**API**

Container plugins need to implement the following two classes:

**Cluster** represents the cluster defined by the container orchestration system.  Wing uses
an instance of this class to start (with or without debug) and stop the cluster as a whole.

**ClusterSystemSupport** provides some top-level meta data and control for the supported container
orchestration system, including parsing configuration files and tracking cluster runtime status.

The details of the API are documented in the file ``src/plugins/cluster/api.py`` in the
Wing installation directory.  A reference implementation for Docker Compose is provided in 
``plugins/cluster/dockercompose.py``.

