Merge "Write A-B configuration guide and align with SDC guide"

3 files changed, 129 insertions, 39 deletions

diff --git a/docs/release/configguide/a_b_config_guide.rst b/docs/release/configguide/a_b_config_guide.rst
index b23afb7..2535ef2 100644
--- a/docs/release/configguide/a_b_config_guide.rst
+++ b/docs/release/configguide/a_b_config_guide.rst
@@ -1,19 +1,101 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 .. SPDX-License-Identifier CC-BY-4.0
-.. (c) optionally add copywriters name
+.. (c) Authors of Clover
 
 .. _a_b_config_guide:
 
+=========================================
+A-B Sample Validation Configuration Guide
+=========================================
+
+Istio supports the ability to have multiple service versions, which allows for use-cases
+such as staging services and moving to production when newer versions are vetted. Multiple variants
+of a service can run in parallel and Istio can perform request routing between the variants
+using configured route rules.
+
+This script sets up route rules between the two load balancer versions (http-lb-v1/v2) in the
+Service Delivery Controller (SDC) sample to modify the ratio of incoming request traffic to send
+to each. It then employs the overall request/response times obtained from the tracing module to
+validate the response time performance of v2 is within 120% of v1. The 120% condition can be
+configured in an input configuration yaml.
+
+Using the sample script
 =======================
-A-B Configuration Guide
-=======================
 
-This is a placeholder file for now
+Prerequisites
+-------------
+
+The following assumptions must be met before executing the sample script:
+
+ * The prerequisites stipulated at :ref:`sdc_prerequisites` are considered. The use of flannel
+   as the CNI network add-on is required.
+ * Ensure the SDC sample is deployed. The easiest way to accomplish this is using the Clover
+   container outlined in the SDC guide at :ref:`sdc_deploy_container`.
+ * Deploy Jaeger tracing and determine the tracing port. The instructions in the SDC guide
+   at :ref:`sdc_view_container` can be used for this purpose. The exposed tracing port is
+   required as the ``-p`` argument in the script.
+ * The http-lb-v2 in the SDC sample is load balancing across clover-server4/5 using the
+   command outlined at :ref:`sdc_modify_lb`
+ * Ensure Istio is in the path by downloading Istio separately into a directory with the
+   commands below:
+
+.. code-block:: bash
+
+    $ curl -L https://github.com/istio/istio/releases/download/0.6.0/istio-0.6.0-linux.tar.gz | tar xz
+    $ cd istio-0.6.0
+    $ export PATH=$PWD/bin:$PATH
+
+Environment setup
+------------------
+
+First setup the environment using the Clover source with the following commands:
+
+.. code-block:: bash
+
+    $ git clone https://gerrit.opnfv.org/gerrit/clover
+    $ cd clover
+    $ git checkout stable/fraser
+    $ pip install .
+    $ cd clover
+
+Edit the input configuration yaml file located at ``test/yaml/fraser_a_b_test.yaml``
+and modify the value under the ``params`` key with the istio-ingress port obtained using
+the SDC guide at :ref:`sdc_ingress_port`. The example of port 32580 is shown below in bold.
+
+.. code-block:: bash
+
+    traffic-test:
+      name: lb-test.sh
+      params:
+        - 10.244.0.1
+        - **32580**
+
+Execute toplevel script
+-----------------------
+
+To execute the script, use the command:
+
+.. code-block:: bash
+    $ python test/fraser_a_b_test.py -t test/yaml/fraser_a_b_test.yaml -p 30869
+
+The value to the argument ``-p`` must be the tracing port exposed outside of the Kubernetes
+cluster.
+
+Results
+-------
+
+The script uses ``wget`` to make twenty HTTP GET requests to the SDC sample. It fetches the
+total response time for the service mesh to respond to requests using the Clover tracing module
+and calculates and average. The script will pass if performance of http-lb-v2 has response times
+within 120% of v1 and fail otherwise.
+
+Troubleshooting
+===============
+
+If the script fails because a route rule with the same name exists from a
+previous test run, use the following command to delete the rule before executing the
+sample script::
+
+    istioctl -n default delete routerules lb-default
 
-- ensure Istio is in the path
-- ensure old route rule deleted
-- istioctl -n default delete routerules lb-default
-- redis port forward
-- clover/test/yaml/fraser_a_b_test.yaml
-- change ingress port
diff --git a/docs/release/configguide/index.rst b/docs/release/configguide/index.rst
index d2cffd5..daf8986 100644
--- a/docs/release/configguide/index.rst
+++ b/docs/release/configguide/index.rst
@@ -1,16 +1,16 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. This work is licensed under a Creative Commons Attribution 4.0 International
+.. License.
 .. http://creativecommons.org/licenses/by/4.0
-.. SPDX-License-Identifier CC-BY-4.0
-.. (c) optionally add copywriters name
+.. (c) OPNFV, Authors of Clover
 
 .. _clover_config_guides:
 
-********************************************************
-OPNFV Verified Program Testing User Guide
-********************************************************
+=================================
+OPNFV Clover Configuration Guides
+=================================
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
 
    sdc_config_guide.rst
    a_b_config_guide.rst
diff --git a/docs/release/configguide/sdc_config_guide.rst b/docs/release/configguide/sdc_config_guide.rst
index 9e523af..7b045ad 100644
--- a/docs/release/configguide/sdc_config_guide.rst
+++ b/docs/release/configguide/sdc_config_guide.rst
@@ -1,8 +1,9 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 .. SPDX-License-Identifier CC-BY-4.0
-.. (c) optionally add copywriters name
+.. (c) Authors of Clover
 
+.. _sdc_config_guide:
 
 =======================================
 Clover SDC Sample Configuration Guide
@@ -11,17 +12,13 @@ Clover SDC Sample Configuration Guide
 This document provides a guide to use the Service Delivery Controller (SDC) sample, which is
 initially delivered in the Clover Fraser release.
 
-.. contents::
-   :depth: 3
-   :local:
-
-
 Overview
 =========
 
-The SDC is a sample application that allows the flow of ingress HTTP traffic to be controlled
-and inspected in an Istio service mesh. It provides the ability to demonstrate the Istio sandbox
-including a service mesh and surrounding tools including tracing, monitoring, and logging.
+The SDC is a sample set of web-oriented network services that allow the flow of ingress HTTP
+traffic to be controlled and inspected in an Istio service mesh. It provides the ability to
+demonstrate the Istio sandbox including a service mesh and surrounding tools including tracing,
+monitoring, and logging.
 
 The SDC sample comprises the following services:
 
@@ -31,17 +28,17 @@ The SDC sample comprises the following services:
 
  * **Load Balancer** - provides basic round-robin load balancing to other downstream
    services without Istio provisions. Istio features built-in load balancing to provide
-   request routing for canary and A/B scenarios. The sample application employs both tiers
+   request routing for canary and A/B scenarios. The SDC sample employs both tiers
    of load balancing to demonstrate how load balancing algorithms can be controlled to
    address both network and application requirements.
 
- * **Intrusion Detection System** - used to detect web vulnerabilities using limited set of
-   rules/signatures and send security alerts to the proxy.
+ * **Intrusion Detection System** - used to detect web security vulnerabilities using limited
+   set of rules/signatures and send security alerts to the proxy.
 
  * **Server** - simple web servers used to terminate web requests from the load balancing
-   services for end-to-end traffic flow.
+   services to enable end-to-end traffic flow.
 
-The table below shows key details of the sample application Kubernetes manifest for the services
+The table below shows key details of the sample Kubernetes manifest for the services
 outlined above:
 
 +---------------------+----------------------+------------------------+-----------------------+
@@ -103,12 +100,14 @@ in round-robin fashion.
 A controlling agent that can reside inside or outside of the mesh can be used to modify the
 run-time configuration of the services, which is denoted in green. Python sample scripts that
 implement a GRPC client act as a control-agent and are used to reconfigure http-lb-v2 to load
-balance across clover-server4/5 instead of servers 1/2/3. The sample application provides
-additional examples of modifying run-time configurations such as adding user-defined rules
-to the snort-ids service to trigger alerts on other network events.
+balance across clover-server4/5 instead of servers 1/2/3. The sample provides additional examples
+of modifying run-time configurations such as adding user-defined rules to the snort-ids service
+to trigger alerts on other network events.
 
-Deploying the sample app
-========================
+Deploying the sample
+====================
+
+.. _sdc_prerequisites:
 
 Prerequisites
 -------------
@@ -123,6 +122,8 @@ The following assumptions must be met before continuing on to deployment:
    recommended to use flannel, as most development work employed this network add-on.
  * Installation of Istio and Istio client (istioctl) is in your PATH (for deploy from source)
 
+.. _sdc_deploy_container:
+
 Deploy with Clover container
 ----------------------------
 
@@ -226,6 +227,8 @@ The result of the Istio deployment must include the following pods:
     istio-system   istio-mixer-7f4fd7dff-mjpr8        3/3       Running
     istio-system   istio-pilot-5f5f76ddc8-cglxs       2/2       Running
 
+.. _sdc_ingress_port:
+
 Determining the ingress IP and port
 -----------------------------------
 
@@ -247,8 +250,8 @@ configured ingress rule, which defines a gateway for external traffic to enter
 the Istio service mesh. This makes the traffic management and policy features of Istio available
 for edge services.
 
-Using the sample app
-====================
+Using the sample
+================
 
 To confirm the scenario is running properly, HTTP GET requests can be made from an external
 host with a destination of the Kubernetes cluster. Requests can be invoked from the host OS
@@ -266,6 +269,8 @@ is operating correctly. However, the visibility into what services were accessed
 the service mesh remains hidden. The next section `Exposing tracing and monitoring`_ shows how
 to inspect the internals of the Istio service mesh.
 
+.. _sdc_view_container:
+
 Exposing tracing and monitoring
 -------------------------------
 
@@ -317,9 +322,10 @@ Where node IP is an IP from one of the Kubernetes cluster node(s).
     :align: center
     :scale: 100%
 
+
 The diagram above shows the Jaeger tracing UI after traces have been fetched for the
 proxy-access-control service. After executing an HTTP request using the simple curl/wget
-commands outlined in `Using the sample app`_ , a list of SDC services will be displayed
+commands outlined in `Using the sample`_ , a list of SDC services will be displayed
 in the top left drop-down box labelled ``Service``. Choose ``proxy-access-control`` in
 the drop-down and click the ``Find Traces`` button at the bottom of the left controls.
 The blue box denotes what should be displayed for the services that were involved in
@@ -341,6 +347,8 @@ For this example, it is conducted from the host OS of a Kubernetes cluster node.
 **Note, the subsequent instructions assume the flannel network CNI plugin is installed. Other
 Kubernetes networking plugins may work but have not been validated.**
 
+.. _sdc_modify_lb:
+
 Modifying the http-lb server list
 ----------------------------------