From 9448ab28ef43fbf3674467a5a4c600558ca00333 Mon Sep 17 00:00:00 2001
From: Salvatore Orlando <salv.orlando@gmail.com>
Date: Mon, 21 Oct 2013 11:53:50 +0200
Subject: [PATCH] Document async status retrieval in NVP plugin

Document the Nicira plugin's asynchronous state retrieval
process and the configuration options that discipline it.

Bug 1250082

Change-Id: I63909184ebeb1cf080869c921b4aad983304ac82
---
 .../bk-admin-guide-cloud.xml                  |   7 ++
 .../section_networking_adv_features.xml       | 112 ++++++++++++++++++
 2 files changed, 119 insertions(+)

diff --git a/doc/admin-guide-cloud/bk-admin-guide-cloud.xml b/doc/admin-guide-cloud/bk-admin-guide-cloud.xml
index 53b2a3dfa6..12dfffe0a3 100644
--- a/doc/admin-guide-cloud/bk-admin-guide-cloud.xml
+++ b/doc/admin-guide-cloud/bk-admin-guide-cloud.xml
@@ -43,6 +43,13 @@
         </abstract>
         <revhistory>
             <!-- ... continue adding more revisions here as you change this document using the markup shown below... -->
+            <revision>
+                <date>2013-11-12</date>
+                <revdescription><itemizedlist>
+                    <listitem><para>Adds options for tuning operational status synchronization
+                        in the NVP plugin.</para></listitem>
+                </itemizedlist></revdescription>
+            </revision>
             <revision>
                 <date>2013-10-17</date>
                 <revdescription>
diff --git a/doc/admin-guide-cloud/section_networking_adv_features.xml b/doc/admin-guide-cloud/section_networking_adv_features.xml
index e946d389d1..1d6a35ba3d 100644
--- a/doc/admin-guide-cloud/section_networking_adv_features.xml
+++ b/doc/admin-guide-cloud/section_networking_adv_features.xml
@@ -1717,6 +1717,117 @@
 --provider:physical_network &lt;L3-Gateway-Service-UUID&gt; -provider:segmentation_id &lt;VLAN_ID&gt;</userinput></screen>
                 </section>
             </section>
+            <section xml:id="section_nicira_nvp_plugin_status_sync">
+                <title>Operational status synchronization in the
+                    Nicira NVP plugin</title>
+                <para>Starting with the Havana release, the Nicira NVP plugin
+                    provides an asynchronous mechanism for retrieving the
+                    operational status for neutron resources from the NVP
+                    backend; this applies to <emphasis>network</emphasis>,
+                    <emphasis>port</emphasis>, and <emphasis>router</emphasis> resources.</para>
+                <para>The backend is polled periodically, and the status for every resource is
+                    retrieved; then the status in the Neutron database is updated only for the
+                    resources for which a status change occurred. As operational status is now
+                    retrieved asynchronously, performance for <literal>GET</literal> operations is
+                    consistently improved.</para>
+                <para>Data to retrieve from the backend are divided in chunks in order to avoid
+                    expensive API requests; this is achieved leveraging NVP APIs response paging
+                    capabilities. The minimum chunk size can be specified using a configuration
+                    option; the actual chunk size is then determined dynamically according to:
+                    total number of resources to retrieve, interval between two synchronization task
+                    runs, minimum delay between two subsequent requests to the NVP backend.</para>
+                <para>The operational status synchronization can be tuned or disabled using the
+                    configuration options reported in the following table; it is however worth
+                    noting that the default values will work fine in most cases.</para>
+                <table rules="all">
+                    <caption>Configuration options for tuning operational status synchronization
+                        in the NVP plugin</caption>
+                    <col width="12%"/>
+                    <col width="8%"/>
+                    <col width="10%"/>
+                    <col width="20%"/>
+                    <col width="50%"/>
+                    <thead>
+                        <tr>
+                            <th>Option name</th>
+                            <th>Group</th>
+                            <th>Default value</th>
+                            <th>Type and constraints</th>
+                            <th>Notes</th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                        <tr>
+                            <td><literal>state_sync_interval</literal></td>
+                            <td><literal>nvp_sync</literal></td>
+                            <td>120 seconds</td>
+                            <td>Integer; no constraint.</td>
+                            <td>Interval in seconds between two run of the synchronization task.
+                                If the synchronization task takes more than
+                                    <literal>state_sync_interval</literal> seconds to execute, a
+                                new instance of the task is started as soon as the other is
+                                completed. Setting the value for this option to 0 will disable
+                                the synchronization task.</td>
+                        </tr>
+                        <tr>
+                            <td><literal>max_random_sync_delay</literal></td>
+                            <td><literal>nvp_sync</literal></td>
+                            <td>0 seconds</td>
+                            <td>Integer. Must not exceed
+                                <literal>min_sync_req_delay</literal></td>
+                            <td>When different from zero, a random delay between 0 and
+                                <literal>max_random_sync_delay</literal> will be added
+                                before processing the next chunk.</td>
+                        </tr>
+                        <tr>
+                            <td><literal>min_sync_req_delay</literal></td>
+                            <td><literal>nvp_sync</literal></td>
+                            <td>10 seconds</td>
+                            <td>Integer. Must not exceed
+                                <literal>state_sync_interval</literal>.</td>
+                            <td>The value of this option can be tuned according to the observed
+                                load on the NVP controllers. Lower values will result in faster
+                                synchronization, but might increase the load on the controller
+                                cluster.</td>
+                        </tr>
+                        <tr>
+                            <td><literal>min_chunk_size</literal></td>
+                            <td><literal>nvp_sync</literal></td>
+                            <td>500 resources</td>
+                            <td>Integer; no constraint.</td>
+                            <td>Minimum number of resources to retrieve from the backend for
+                                each synchronization chunk.  The expected number of
+                                synchronization chunks is given by the ratio between
+                                <literal>state_sync_interval</literal> and
+                                <literal>min_sync_req_delay</literal>. This size of a chunk
+                                might increase if the total number of resources is such that
+                                more than <literal>min_chunk_size</literal> resources must be
+                                fetched in one chunk with the current number of chunks.</td>
+                        </tr>
+                        <tr>
+                            <td><literal>always_read_status</literal></td>
+                            <td><literal>nvp_sync</literal></td>
+                            <td>False</td>
+                            <td>Boolean; no constraint.</td>
+                            <td>When this option is enabled, the operational status will always
+                                be retrieved from the NVP backend ad every
+                                <literal>GET</literal> request. In this case it is advisable
+                                to disable the synchronization task.</td>
+                        </tr>
+                    </tbody>
+                </table>
+                <para>When running multiple Neutron server instances, the status
+                    synchronization task should not run on every node; doing so will need to
+                    unnecessary traffic towards the NVP backend as well as unnecessary DB
+                    operations. The configuration option <literal>state_sync_interval</literal>
+                    should therefore be non-zero exclusively on a node designated for backend status
+                    synchronization.</para>
+                <para>Explicitly specifying the <emphasis role="italic">status</emphasis> attribute
+                    in Neutron API requests (e.g.: <literal>GET
+                        /v2.0/networks/&lt;net-id>?fields=status&amp;fields=name</literal>) will
+                    always trigger an explicit query to the NVP backend, even when asynchronous
+                    state synchronization is enabled.</para>
+            </section>
         </section>
 
         <section xml:id="section_bigswitch_extensions">
@@ -1827,3 +1938,4 @@ source=10.10.10.0/24,destination=10.20.20.20/24,action=deny</userinput></screen>
         </section>
     </section>
 </section>
+<!---->