Update containers documentation

Change-Id: Ibd5478793c353d0d0c89c6b4113a319c60cbb5fe

README.rst

@@ -35,6 +35,7 @@ The cloud deployment configuration is specified in JSON/YAML format or Python di
 
 The library operates with 2 types of objects:
  * `service` - is a software that runs in the cloud, e.g. `nova-api`
+ * `container` - is a software that runs in the cloud, e.g. `neutron_api`
  * `nodes` - nodes that host the cloud, e.g. a server with a hostname
 
 
@@ -60,7 +61,7 @@ parameter `iface`. Note that user should have sudo permissions (by default DevSt
 DevStack driver is responsible for service discovery. For more details please refer
 to driver documentation: http://os-faults.readthedocs.io/en/latest/drivers.html#devstack-systemd-devstackmanagement
 
-Example 2. An OpenStack with services and power management
+Example 2. An OpenStack with services, containers and power management
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 An arbitrary OpenStack can be handled too with help of `universal` driver.
@@ -100,6 +101,14 @@ In this example os-faults is used as Python library.
                 }
             }
         },
+        'containers': {
+            'neutron_api': {
+                'driver': 'docker_container',
+                'args': {
+                    'container_name': 'neutron_api',
+                }
+            }
+        },
         'power_managements': [
             {
                 'driver': 'libvirt',
@@ -111,9 +120,9 @@ In this example os-faults is used as Python library.
     }
 
 The config contains all OpenStack nodes with credentials and all
-services. OS-Faults will automatically figure out the mapping between services
-and nodes. Power management configuration is flexible and supports
-mixed bare-metal / virtualized deployments.
+services/containers. OS-Faults will automatically figure out the mapping
+between services/containers and nodes. Power management configuration is
+flexible and supports mixed bare-metal / virtualized deployments.
 
 First let's establish a connection to the cloud and verify it:
 
@@ -135,6 +144,7 @@ Now let's make some destructive action:
 .. code-block:: python
 
     cloud_management.get_service(name='memcached').kill()
+    cloud_management.get_container(name='neutron_api').restart()
 
 
 Human API
@@ -153,6 +163,17 @@ Examples:
     * `kill nova-api service on one node` - kills Nova API on one
       randomly-picked node.
 
+**Container-oriented** command performs specified `action` against `container`
+on all, on one random node or on the node specified by FQDN::
+
+    <action> <container> container [on (random|one|single|<fqdn> node[s])]
+
+Examples:
+    * `Restart neutron_ovs_agent container` - restarts neutron_ovs_agent
+      container on all nodes.
+    * `Terminate neutron_api container on one node` - stops Neutron API
+      container on one randomly-picked node.
+
 **Node-oriented** command performs specified `action` on node specified by FQDN
 or set of service's nodes::
 
@@ -205,7 +226,7 @@ Get a container and restart it:
 .. code-block:: python
 
     cloud_management = os_faults.connect(cloud_config)
-    container = cloud_management.get_container(name='neutron-api')
+    container = cloud_management.get_container(name='neutron_api')
     container.restart()
 
 Available actions:
@@ -259,3 +280,14 @@ Restart a service on a single node:
     service = cloud_management.get_service(name='keystone')
     nodes = service.get_nodes().pick()
     service.restart(nodes)
+
+6. Operate with containers
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Terminate a container on a random node:
+
+.. code-block:: python
+
+    container = cloud_management.get_container(name='neutron_ovs_agent')
+    nodes = container.get_nodes().pick()
+    container.restart(nodes)

doc/source/api.rst

@@ -11,5 +11,8 @@ API Reference
 .. autoclass:: os_faults.api.service.Service
     :members:
 
+.. autoclass:: os_faults.api.container.Container
+    :members:
+
 .. autoclass:: os_faults.api.node_collection.NodeCollection
     :members:

doc/source/drivers.rst

@@ -48,3 +48,9 @@ Service drivers
 .. driver_doc:: pcs_service
 
 .. driver_doc:: pcs_or_linux_service
+
+
+Container drivers
+-----------------
+
+.. driver_doc:: docker_container

doc/source/quickstart/api.rst

@@ -5,6 +5,7 @@ API
 The library operates with 2 types of objects:
 
     * `service` - is a software that runs in the cloud, e.g. `nova-api`
+    * `containers` - is a software that runs in the cloud, e.g. `neutron-api`
     * `nodes` - nodes that host the cloud, e.g. a hardware server with a hostname
 
 
@@ -74,7 +75,23 @@ Available actions:
  * `unplug` - unplug Service out of network
  * `plug` - plug Service into network
 
-2. Node actions
+2. Container actions
+~~~~~~~~~~~~~~~~~~~~
+
+Get a container and restart it:
+
+.. code-block:: python
+
+    cloud_management = os_faults.connect(cloud_config)
+    container = cloud_management.get_container(name='neutron_api')
+    container.restart()
+
+Available actions:
+ * `start` - start Container
+ * `terminate` - terminate Container gracefully
+ * `restart` - restart Container
+
+3. Node actions
 ~~~~~~~~~~~~~~~
 
 Get all nodes in the cloud and reboot them:
@@ -92,7 +109,7 @@ Available actions:
  * `disconnect` - disable network with the specified name on all nodes
  * `connect` - enable network with the specified name on all nodes
 
-3. Operate with nodes
+4. Operate with nodes
 ~~~~~~~~~~~~~~~~~~~~~
 
 Get all nodes where a service runs, pick one of them and reset:
@@ -111,7 +128,7 @@ Get nodes where l3-agent runs and disable the management network on them:
     nodes = cloud_management.get_nodes(fqdns=fqdns)
     nodes.disconnect(network_name='management')
 
-4. Operate with services
+5. Operate with services
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 Restart a service on a single node:

doc/source/quickstart/config_spec.rst

@@ -8,6 +8,7 @@ Configuration file contains the following parameters:
     * power_managements
     * node_discover
     * services
+    * containers
 
 Each parameter specifies a driver or a list of drivers.
 
@@ -51,6 +52,12 @@ Example configuration:
         hosts:
         - 192.168.1.240
 
+    containers:
+      neutron_api:
+        driver: docker_container
+        args:
+          container_name: neutron_api
+
 
 cloud_management
 ----------------
@@ -156,3 +163,29 @@ discovering is disabled for this service and hosts specified in ``hosts`` will
 be used, otherwise, service will be searched across all nodes.
 
 List of supported drivers for services: :ref:`Service drivers`
+
+
+containers
+----------
+
+This parameter specifies list of containers and their types. This parameter
+allows updating/adding containers which are embedded in ``cloud_management``
+driver.
+
+.. code-block:: yaml
+
+    containers:
+      neutron_api:                     # name of the container
+        driver: docker_container       # name of the container driver
+        args:                          # arguments for the driver
+          container_name: neutron_api
+        hosts:                         # list of hosts where this container running
+        - 192.168.1.240
+
+
+Container driver contains optional ``hosts`` parameter which controls discovering
+of hosts where the container is running. If ``hosts`` specified, then container
+discovering is disabled for this container and hosts specified in ``hosts`` will
+be used, otherwise, container will be searched across all nodes.
+
+List of supported drivers for containers: :ref:`Container drivers`