diff --git a/doc/source/api.rst b/doc/source/api.rst index 1b5329e2d..ed426d035 100644 --- a/doc/source/api.rst +++ b/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/ 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//status Show data source status GET .../data-sources//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//...) diff --git a/doc/source/config.rst b/doc/source/deployment.rst similarity index 67% rename from doc/source/config.rst rename to doc/source/deployment.rst index c618f6013..e113b0913 100644 --- a/doc/source/config.rst +++ b/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 diff --git a/doc/source/ha-deployment.rst b/doc/source/ha-deployment.rst index e4837292e..e607c6255 100644 --- a/doc/source/ha-deployment.rst +++ b/doc/source/ha-deployment.rst @@ -3,9 +3,9 @@ .. _ha_deployment: -============= +------------- HA Deployment -============= +------------- Overview -------- diff --git a/doc/source/ha-overview.rst b/doc/source/ha-overview.rst index 9f3c209aa..ba65a0a17 100644 --- a/doc/source/ha-overview.rst +++ b/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 ` for details. \ No newline at end of file diff --git a/doc/source/index.rst b/doc/source/index.rst index 2934d127c..03c36bb99 100644 --- a/doc/source/index.rst +++ b/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 ==================