Clover Doc Patches: Update release note, user guide, and add Clovisor

configuration guide

Change-Id: I65da13cb9ce503f9b5b2fd2457f147549a13b9f6
Signed-off-by: Stephen Wong <stephen.kf.wong@gmail.com>

1 files changed, 156 insertions, 0 deletions

diff --git a/docs/release/configguide/clovisor_config_guide.rst b/docs/release/configguide/clovisor_config_guide.rst
new file mode 100644
index 0000000..9b5f4a3
--- /dev/null
+++ b/docs/release/configguide/clovisor_config_guide.rst
@@ -0,0 +1,156 @@
+.. 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) Authors of Clover
+
+.. _clovisor_config_guide:
+
+============================
+Clovisor Configuration Guide
+============================
+
+Clovisor requires minimal to no configurations to function as a network tracer.
+It expects configurations to be set at a redis sever running at clover-system
+namespace.
+
+No Configuration
+================
+
+If redis server isn't running as service name **redis** in namespace
+**clover-system** or there isn't any configuration related to Clovisor in that
+redis service, then Clovisor would monitor all pods under the **default**
+namespace. The traces would be sent to **jaeger-collector** service under the
+**clover-system** namespace
+
+Using redis-cli
+===============
+
+Install ``redis-cli`` on the client machine, and look up redis IP address:
+
+.. code-block:: bash
+
+    $ kubectl get services -n clover-system
+
+which one may get something like the following:
+
+.. code-block:: bash
+
+    $
+    NAME      TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
+    redis     ClusterIP   10.109.151.40   <none>        6379/TCP   16s
+
+if (like above), the external IP isn't visible, one may be able to get the pod
+IP address directly via the pod (for example, it works with Flannel as CNI
+plugin):
+
+.. code-block:: bash
+
+    $ kubectl get pods -n clover-system -o=wide
+    NAME      READY     STATUS    RESTARTS   AGE       IP             NODE
+    redis     2/2       Running   0          34m       10.244.0.187   clover1804
+
+and one can connect to redis via::
+
+    redis-cli -h 10.244.0.187 -p 6379
+
+Jaeger Collector Configuration
+==============================
+
+Clovisor allows user to specify the Jaeger service for which Clovisor would send
+the network traces to. This is configured via setting the values for
+keys **clovisor_jaeger_collector** and **clovisor_jaeger_agent**::
+
+    redis> SET clovisor_jaeger_collector "jaeger-collector.istio-system:14268"
+    "OK"
+    redis> SET clovisor_jaeger_agent "jaeger-agent.istio-system:6831"
+    "OK"
+
+Configure Monitoring Namespace and Labels
+=========================================
+
+Configruation Value String Format:
+----------------------------------
+
+    <namespace>[:label-key:label-value]
+
+User can configure namespace(s) for Clovisor to tap into via adding namespace
+configuration in redis list **clovisor_labels**::
+
+    redis> LPUSH clovisor_labels "my-namespace"
+    (integer) 1
+
+the above command will cause Clovisor to **NOT** monitor the pods in **default**
+namespace, and only monitor the pods under **my-namespace**.
+
+If user wants to monitor both 'default' and 'my-namespace', she needs to
+explicitly add 'default' namespace back to the list::
+
+    redis> LPUSH clovisor_labels "default"
+    (integer) 2
+    redis> LRANGE clovisor_labels 0 -1
+    1.) "default"
+    2.) "my-namespace"
+
+Clovisor allows user to optionally specify which label match on pods to further
+filter the pods to monitor::
+
+    redis> LPUSH clovisor_labels "my-2nd-ns:app:database"
+    (integer) 1
+
+the above configuration would result in Clovisor only monitoring pods in
+my-2nd-ns namespace which matches the label "app:database"
+
+User can specify multiple labels to filter via adding more configuration
+entries::
+
+    redis> LPUSH clovisor_labels "my-2nd-ns:app:web"
+    (integer) 2
+    redis> LRANGE clovisor_labels 0 -1
+    1.) "my-2nd-ns:app:web"
+    2.) "my-2nd-ns:app:database"
+
+the result is that Clovisor would monitor pods under namespace my-2nd-ns which
+match **EITHER** app:database **OR** app:web
+
+Currently Clovisor does **NOT** support filtering of more than one label per
+filter, i.e., no configuration option to specify a case where a pod in a
+namespace needs to be matched with TWO or more labels to be monitored
+
+Configure Egress Match IP address, Port Number, and Matching Pods
+=================================================================
+
+Configruation Value String Format:
+----------------------------------
+
+    <IP Address>:<TCP Port Number>[:<Pod Name Prefix>]
+
+By default, Clovisor only traces packets that goes to a pod via its service
+port, and the response packets, i.e., from pod back to client. User can
+configure tracing packet going **OUT** of the pod to the next microservice, or
+an external service also via the **clovior_egress_match** list::
+
+    redis> LPUSH clovior_egress_match "10.0.0.1:3456"
+    (integer) 1
+
+the command above will cause Clovisor to trace packet going out of ALL pods
+under monitoring to match IP address 10.0.0.1 and destination TCP port 3456 on
+the **EGRESS** side --- that is, packets going out of the pod.
+
+User can also choose to ignore the outbound IP address, and only specify the
+port to trace via setting IP address to zero::
+
+    redis> LPUSH clovior_egress_match "0:3456"
+    (integer) 1
+
+the command above will cause Clovisor to trace packets going out of all the pods
+under monitoring that match destination TCP port 3456.
+
+User can further specify a specific pod prefix for such egress rule to be
+applied::
+
+    redis> LPUSH clovior_egress_match "0:3456:proxy"
+    (integer) 1
+
+the command above will cause Clovisor to trace packets going out of pods under
+monitoring which have name starting with the string "proxy" that match destination
+TCP port 3456