diff options
Diffstat (limited to 'docs/release/configguide/clovisor_config_guide.rst')
| -rw-r--r-- | docs/release/configguide/clovisor_config_guide.rst | 156 |
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 |