Merge "Editing pass over docs"

doc/source/api.rst

@@ -118,7 +118,7 @@ GET     .../rows?trace=true    List rows with explanation (use 'printf' to displ
 ======= ====================== =====================================================
 
 
-5. DEPRECATED: Drivers (/v1/system/)
+5. Drivers (/v1/system/)
 ====================================
 A driver is a piece of code that once instantiated and configured interacts
 with a specific cloud service like Nova or Neutron.  A driver has the following
@@ -135,9 +135,8 @@ GET     .../drivers              List drivers
 GET     .../drivers/<driver-id>  Read driver properties
 ======= ======================== ==============================================
 
-Drivers are deprecated as of liberty.  The upcoming distributed architecture
-replaces API-level datasource management with configuration-level datasource
-management.
+Drivers were deprecated in Liberty, but the design changed slightly so that
+we could retain them.
 
 
 6. Data sources (/v1/)
@@ -173,10 +172,6 @@ GET     .../data-sources/<ds-id>/status  Show data source status
 GET     .../data-sources/<ds-id>/actions List supported data source actions
 ======= ================================ ======================================
 
-Datasource creation and deletion via the API will be deprecated in future. The
-upcoming distributed architecture replaces API-level datasource management with
-configuration-level datasource management.
-
 
 
 7. Data source Tables (/v1/data-sources/<ds-id>/...)

doc/source/deployment.rst

@@ -1,10 +1,35 @@
 .. include:: aliases.rst
 
+.. _deployment:
+
+==========
+Deployment
+==========
+Congress has two modes for deployment: single-process and multi-process.
+If you are interested in test-driving Congress or are not concerned
+about high-availability, the single-process deployment is best because it
+is easiest to set up.  If you are interested in making Congress highly-available
+you want the multi-process deployment.
+
+In the single-process version, you run Congress as a single operating-system
+process on one node (i.e. container, VM, physical machine).
+
+In the multi-process version, you start with the 3 components of Congress
+(the API, the policy engine, and the datasource drivers).  You choose how many
+copies of each component you want to run, how you want to distribute those
+components across processes, and how you want to distribute those processes
+across nodes.
+
+Section :ref:`config` describes the common configuration options for both
+single-process and multi-process deployments.  After that :ref:`ha_overview`
+and :ref:`ha_deployment` describe how to set up the multi-process deployment.
+
+
 .. _config:
 
-=====================
+---------------------
 Configuration Options
-=====================
+---------------------
 
 In this section we highlight the configuration options that are specific
 to Congress.  To generate a sample configuration file that lists all
@@ -39,11 +64,6 @@ One of Congress's new experimental features is distributing its services
 across multiple services and even hosts.  Here are the options for using
 that feature.
 
-``distributed_architecture``
-    Whether to enable the distributed architecture.  Don't set it to true in
-    before Newton release since the new architecture is still under
-    development as of Newton.  Default is false.  Appears in [DEFAULT] section.
-
 ``node_id``
     Unique ID of this Congress instance.  Can be any string.  Useful if
     you want to create multiple, distributed instances of Congress.  Appears
@@ -64,3 +84,6 @@ are specified in the [DEFAULT] section of the configuration file.
 
 ``debug``
     Whether or not the DEBUG-level of logging is enabled. Default is false.
+
+.. include:: ha-overview.rst
+.. include:: ha-deployment.rst

doc/source/ha-deployment.rst

@@ -3,9 +3,9 @@
 .. _ha_deployment:
 
 
-=============
+-------------
 HA Deployment
-=============
+-------------
 
 Overview
 --------

doc/source/ha-overview.rst

@@ -3,9 +3,9 @@
 
 .. _ha_overview:
 
-===========
+-----------
 HA Overview
-===========
+-----------
 Some applications require Congress to be highly available. Some
 applications require a Congress Policy Engine (PE) to handle a high volume of
 queries. This guide describes Congress support for High Availability (HA)
@@ -72,21 +72,21 @@ oslo-messaging to all policy engines.
   |  Oslo Msg  |   | DBs (policy, config, push data, exec log)|
   +------------+   +------------------------------------------+
 
+- Performance impact of HAHT deployment:
 
-- Downtime: < 1s for queries, ~2s for reactive enforcement
-- Deployment considerations:
-
-  - Cluster manager (eg. Pacemaker + Corosync) can be used to manage warm
-    standby
-  - Does not require global leader election
-- Performance considerations:
-
-  - Multi-process, multi-node query throughput
-  - No redundant data-pulling load on datasources
-  - DSDs node separate from PE, allowing high load DSDs to operate more
+  - Downtime: < 1s for queries, ~2s for reactive enforcement
+  - Throughput and latency: leverages multi-process and multi-node parallelism
+  - DSDs nodes are separated from PE, allowing high load DSDs to operate more
     smoothly and avoid affecting PE performance.
   - PE nodes are symmetric in configuration, making it easy to load balance
     evenly.
+  - No redundant data-pulling load on datasources
+
+- Requirements for HAHT deployment
+
+  - Cluster manager (eg. Pacemaker + Corosync) to manage warm
+    standby
+  - Does not require global leader election
 
 Details
 ~~~~~~~
@@ -177,6 +177,3 @@ making each user sticky to a particular PE instance. But if a PE instance
 goes down, the end user reaches a different instance and may experience
 out-of-sync artifacts.
 
-Installation
-============
-Please see :ref:`HA Deployment <ha_deployment>` for details.

doc/source/index.rst

@@ -6,7 +6,7 @@
 Welcome to Congress!
 ====================
 
-Contents:
+**For Users**
 
 .. toctree::
    :maxdepth: 2
@@ -18,21 +18,27 @@ Contents:
    policy
    enforcement
    api
-   config
-   ha-overview
-   ha-deployment
 
-   contributing
-   codeoverview
-   release
+   tutorial-tenant-sharing
+   troubleshooting
 
-Tutorials:
+**For Operators**
 
 .. toctree::
    :maxdepth: 2
 
-   tutorial-tenant-sharing
-   troubleshooting
+   deployment
+   release
+
+
+**For Developers**
+
+.. toctree::
+   :maxdepth: 2
+
+   contributing
+   codeoverview
+
 
 Indices and tables
 ==================