.. 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 **clovisor** 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 **clovisor** namespace Using redis-cli =============== Install ``redis-cli`` on the client machine, and look up redis IP address: .. code-block:: bash $ kubectl get services -n clovisor 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 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:: kubectl exec -n clovisor -it redis redis-cli Jaeger Collector Configuration ============================== Clovisor allows user to specify the Jaeger service for which Clovisor would send the network traces to, by default it is Jaegar service running in **clovisor** namespace. To change, user can configure 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: ---------------------------------- [: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: ---------------------------------- :[:] 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 Clovisor in Hunter release supports the ability to run user-defined protocol analyzer as a plugin library --- and the corresponding traces will be sent to Jaeger just like all the default Clovisor network tracing. User needs to implement the following interface (only golang is supported at this time):: type Parser interface { Parse(session_key string, is_req bool, data []byte)([]byte, map[string]string) } and compile it with the following command:: go build --buildmode=plugin -o .so .go then, for Hunter, one needs to push the .so to each Clovisor instance:: kubectl cp .so clovisor/clovisor-bnh2v:/proto/.so do that for each Clovisor pods, and afterward, configure via:: redis> HSET clovisor_proto_cfg "/proto/.so" (integer) 1 redis> PUBLISH clovisor_proto_plugin_cfg_chan (integer) 6