diff options
| -rw-r--r-- | docs/release/configguide/a_b_config_guide.rst | 102 | ||||
| -rw-r--r-- | docs/release/configguide/index.rst | 14 | ||||
| -rw-r--r-- | docs/release/configguide/sdc_config_guide.rst | 52 |
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 ---------------------------------- |