diff options
18 files changed, 918 insertions, 195 deletions
@@ -35,3 +35,4 @@ cover/ .tox/ # work env work/ +.pytest_cache diff --git a/clover/logging/conftest.py b/clover/logging/conftest.py new file mode 100644 index 0000000..d464fab --- /dev/null +++ b/clover/logging/conftest.py @@ -0,0 +1,15 @@ +# Copyright (c) Authors of Clover +# +# All rights reserved. This program and the accompanying materials +# are made available under the terms of the Apache License, Version 2.0 +# which accompanies this distribution, and is available at +# http://www.apache.org/licenses/LICENSE-2.0 + +from elasticsearch import Elasticsearch +import pytest + +ES_HOST="localhost:9200" + +@pytest.fixture +def es(): + return Elasticsearch([ES_HOST]) diff --git a/clover/logging/es_test.py b/clover/logging/es_test.py new file mode 100644 index 0000000..bd0e359 --- /dev/null +++ b/clover/logging/es_test.py @@ -0,0 +1,30 @@ +# Copyright (c) Authors of Clover +# +# All rights reserved. This program and the accompanying materials +# are made available under the terms of the Apache License, Version 2.0 +# which accompanies this distribution, and is available at +# http://www.apache.org/licenses/LICENSE-2.0 + +INDEX_PATTERN='logstash-*' +TAG='newlog.logentry.istio-system' + +def test_health(es): + assert es.cat.health(h='status') != 'red\n' + +def test_indices(es): + assert len(es.cat.indices(INDEX_PATTERN)) > 0 + +def test_logentry(es): + assert es.count( + index=INDEX_PATTERN, + body={"query":{"match":{"tag":TAG}}})['count'] > 0 + +def test_lb(es): + """requests in and out load balance should match""" + from_lb = es.count( + index=INDEX_PATTERN, + body={"query":{"match":{"source": "http-lb"}}}) + to_lb = es.count( + index=INDEX_PATTERN, + body={"query":{"match":{"destination": "http-lb"}}}) + assert from_lb['count'] == to_lb['count'] diff --git a/clover/logging/validate.py b/clover/logging/validate.py index 821f912..aca0394 100644 --- a/clover/logging/validate.py +++ b/clover/logging/validate.py @@ -9,6 +9,8 @@ from kubernetes import client, config from kubernetes.stream import stream import sh import re +import os +import pytest FLUENTD_NAMESPACE = 'logging' FLUENTD_PATTERN = 'fluentd-.*' @@ -54,3 +56,4 @@ def main(): if __name__ == '__main__': main() + pytest.main([os.path.dirname(os.path.realpath(__file__))]) diff --git a/docs/development/design/logging.rst b/docs/development/design/logging.rst index 196ba40..05f3f5b 100644 --- a/docs/development/design/logging.rst +++ b/docs/development/design/logging.rst @@ -26,3 +26,139 @@ It validates the installation with the following criterias #. existence of fluented pod #. fluentd input is configured correctly #. TBD + +************************** +Understanding how it works +************************** + +In clover stack, Istio is configured to automatically gather logs for services +in a mesh. More specificly, it is configured in `Mixer`_:: + +- when to log +- what to log +- where to log + +.. _Mixer: https://istio.io/docs/concepts/policy-and-control/mixer.html + +When to log +=========== + +Istio defines when to log by creating a custom resource ``rule``. For example: + +.. code-block:: yaml + + apiVersion: "config.istio.io/v1alpha2" + kind: rule + metadata: + name: newlogtofluentd + namespace: istio-system + spec: + match: "true" # match for all requests + actions: + - handler: handler.fluentd + instances: + - newlog.logentry + +This rule specifies that all instances of ``newlog.logentry`` that matches the +expression will be handled by the specified handler ``handler.fluentd``. We +shall explain ``instances`` and ``handler`` later. The expression ``true`` means +whenever a request arrive at Mixer, it will trigger the actions defined belows. + +``rule`` is a custom resource definition from `Istio installation`_. + +.. code-block:: yaml + + # Rule to send logentry instances to the fluentd handler + kind: CustomResourceDefinition + apiVersion: apiextensions.k8s.io/v1beta1 + metadata: + name: rules.config.istio.io + labels: + package: istio.io.mixer + istio: core + spec: + group: config.istio.io + names: + kind: rule + plural: rules + singular: rule + scope: Namespaced + version: v1alpha2 + +.. _Istio installation: https://github.com/istio/istio/blob/master/install/kubernetes/templates/istio-mixer.yaml.tmpl + +What to log +=========== + +The instance defines what content to be logged. + +> A (request) instance is the result of applying request attributes to the +> template mapping. The mapping is specified as an instance configuration. + +For example: + +.. code-block:: yaml + + # Configuration for logentry instances + apiVersion: "config.istio.io/v1alpha2" + kind: logentry + metadata: + name: newlog + namespace: istio-system + spec: + severity: '"info"' + timestamp: request.time + variables: + source: source.labels["app"] | source.service | "unknown" + user: source.user | "unknown" + destination: destination.labels["app"] | destination.service | "unknown" + responseCode: response.code | 0 + responseSize: response.size | 0 + latency: response.duration | "0ms" + monitored_resource_type: '"UNSPECIFIED"' + +The keys under ``spec`` should conform to the template. To learn what fields +are available and valid type, you may need to reference the corresponding +template, in this case, `Log Entry template`_. + +The values of each field could be either `Istio attributes`_ or an expression. + +> A given Istio deployment has a fixed vocabulary of attributes that it +> understands. The specific vocabulary is determined by the set of attribute +> producers being used in the deployment. The primary attribute producer in +> Istio is Envoy, although Mixer and services can also introduce attributes. + +Refer to the `Attribute Vocabulary`_ to learn the full set. + +By the way, ``logentry`` is also a custom resource definition created by Istio. + +.. _Istio attributes: https://istio.io/docs/concepts/policy-and-control/attributes.html +.. _Attribute Vocabulary: https://istio.io/docs/reference/config/mixer/attribute-vocabulary.html +.. _Log Entry template: https://istio.io/docs/reference/config/template/logentry.html + +Where to log +============ + +For log, the handler defines where these information will be handled, in this +example, a fluentd daemon on fluentd-es.logging:24224. + +.. code-block:: yaml + + # Configuration for a fluentd handler + apiVersion: "config.istio.io/v1alpha2" + kind: fluentd + metadata: + name: handler + namespace: istio-system + spec: + address: "fluentd-es.logging:24224" + +In this example, handlers (``handler.fluentd``) configure `Adapters`_ +(``fluentd``) to handle the data delivered from the created instances +(``newlog.logentry``). + +An adapter only accepts instance of specified kind. For example, +`fluentd adapter`_ accepts logentry but not other kinds. + +.. _Adapters: https://istio.io/docs/concepts/policy-and-control/mixer.html#adapters +.. _fluentd adapter: https://istio.io/docs/reference/config/adapters/fluentd.html diff --git a/docs/release/configguide/a_b_config_guide.rst b/docs/release/configguide/a_b_config_guide.rst new file mode 100644 index 0000000..b23afb7 --- /dev/null +++ b/docs/release/configguide/a_b_config_guide.rst @@ -0,0 +1,19 @@ +.. 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 + +.. _a_b_config_guide: + +======================= +A-B Configuration Guide +======================= + +This is a placeholder file for now + +- 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/imgs/sdc_sample.png b/docs/release/configguide/imgs/sdc_sample.png Binary files differnew file mode 100644 index 0000000..fb9c89b --- /dev/null +++ b/docs/release/configguide/imgs/sdc_sample.png diff --git a/docs/release/configguide/imgs/sdc_sample.xcf b/docs/release/configguide/imgs/sdc_sample.xcf Binary files differnew file mode 100644 index 0000000..04a1d4d --- /dev/null +++ b/docs/release/configguide/imgs/sdc_sample.xcf diff --git a/docs/release/configguide/imgs/sdc_tracing.png b/docs/release/configguide/imgs/sdc_tracing.png Binary files differnew file mode 100644 index 0000000..0df7112 --- /dev/null +++ b/docs/release/configguide/imgs/sdc_tracing.png diff --git a/docs/release/configguide/index.rst b/docs/release/configguide/index.rst new file mode 100644 index 0000000..d2cffd5 --- /dev/null +++ b/docs/release/configguide/index.rst @@ -0,0 +1,16 @@ +.. 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 + +.. _clover_config_guides: + +******************************************************** +OPNFV Verified Program Testing User Guide +******************************************************** + +.. toctree:: + :maxdepth: 3 + + 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 new file mode 100644 index 0000000..9e523af --- /dev/null +++ b/docs/release/configguide/sdc_config_guide.rst @@ -0,0 +1,511 @@ +.. 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 + + +======================================= +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 sample comprises the following services: + + * **Proxy** - used to mirror traffic to security (snort-ids) services and propagate traffic to + load balancing services. In future releases, the proxy will process security alerts and + provide access control by blacklisting clients based on source IP address. + + * **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 + 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. + + * **Server** - simple web servers used to terminate web requests from the load balancing + services for end-to-end traffic flow. + +The table below shows key details of the sample application Kubernetes manifest for the services +outlined above: + ++---------------------+----------------------+------------------------+-----------------------+ +| Service | Kubernetes | Docker Image | Ports | +| | Deployment App Name | | | ++=====================+======================+========================+=======================+ +| Proxy | proxy-access-control | clover-ns-nginx-proxy | HTTP: 9180 | +| | | | GRPC: 50054 | ++---------------------+----------------------+------------------------+-----------------------+ +| Load Balancers | app: http-lb | clover-ns-nginx-lb | HTTP: 9180 | +| | version: http-lb-v1 | | GRPC: 50054 | +| | version: http-lb-v2 | | | ++---------------------+----------------------+------------------------+-----------------------+ +| Intrusion Detection | snort-ids | clover-ns-snort-ids | HTTP: 80, Redis: 6379 | +| System (IDS) | | | GRPC: 50052 (config) | +| | | | GRPC: 50054 (alerts) | ++---------------------+----------------------+------------------------+-----------------------+ +| Servers | clover-server1 | clover-ns-nginx-server | HTTP: 9180 | +| | clover-server2 | | GRPC: 50054 | +| | clover-server3 | | | +| | clover-server4 | | | +| | clover-server5 | | | ++---------------------+----------------------+------------------------+-----------------------+ + +Additionally, the sample uses other ancillary elements including: + + * A Redis in-memory data store for the snort IDS service to write alerts. It can also be used + by the Clover tracing module to analyze traces over time. Standard community containers of + Redis are employed by Clover. + + * A Kubernetes Ingress resource (proxy-gateway) to manage external access to the service mesh. + + * Clover docker container that is used to invoke deployment and cleanup scripts for the sample. + It can also be used to execute scripts that modify run-time service configurations. Using the + container avoids the need to clone the source code. + + * Optional deployment of Jaeger tracing and Prometheus monitoring tools with access to their + browser-based UIs. + +.. image:: imgs/sdc_sample.png + :align: center + :scale: 100% + +The diagram above shows the flow of web traffic where all blue arrows denote the path of incoming +HTTP requests through the service mesh. Requests are directed to the istio-ingress entry point +using the Ingress resource (proxy-gateway). Istio-ingress acts as a gateway and sends traffic to +the proxy-access-control service. Proxy-access-control mirrors traffic to the snort-ids +service for it to monitor all incoming HTTP requests. The snort-ids asynchronously sends alert +notifications to proxy-access-control over GRPC on port 50054, which is denoted in red, and +stores the details of the alert events into Redis for other services to potentially inspect. + +Proxy-access-control also sends traffic to the http-lb load balancing service. Http-lb deploys +two versions (http-lb-v1, http-lb-v2) of itself by sharing the same app name (http-lb) but using +a distinct version in the Kubernetes manifest. By default, without any further configuration, +Istio will load balance requests with a 50/50 percentage split among these two http-lb versions. +Both the load balancers are internally configured by default to send traffic to clover-server1/2/3 +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. + +Deploying the sample app +======================== + +Prerequisites +------------- + +The following assumptions must be met before continuing on to deployment: + + * Ubuntu 16.04 was used heavily for development and is advised for greenfield deployments. + * Installation of Docker has already been performed. It's preferable to install Docker CE. + * Installation of Kubernetes has already been performed. The installation in this guide was + executed in a single-node Kubernetes cluster on a modest virtual machine. + * Installation of a pod network that supports the Container Network Interface (CNI). It is + 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) + +Deploy with Clover container +---------------------------- + +The easiest way to deploy the sample is to use the Clover container by pulling the +container and executing a top-level deploy script using the following two commands: + +.. code-block:: bash + + $ docker pull opnfv/clover:<release_tag> + +The <release_tag> is **6.0.0** for the Fraser release. However, the latest +will be pulled if the tag is unspecified. + +.. code-block:: bash + + $ sudo docker run --rm \ + -v ~/.kube/config:/root/.kube/config \ + opnfv/clover \ + /bin/bash -c '/home/opnfv/repos/clover/samples/scenarios/deploy.sh' + +The deploy script invoked above begins by installing Istio 0.6.0 into your Kubernetes environment. +It proceeds to deploy the entire SDC manifest. If you've chosen to employ this method of +deployment, you may skip the next section. + +Deploy from source +------------------ + +Ensure Istio 0.6.0 is installed, as a prerequisite, using the following commands: + +.. 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 + $ kubectl apply -f install/kubernetes/istio.yaml + +The above sequence of commands installs Istio with manual sidecar injection without mutual TLS +authentication between sidecars. + +To continue to deploy from the source code, clone the Clover git repository and navigate +within the samples directory as shown below: + +.. code-block:: bash + + $ git clone https://gerrit.opnfv.org/gerrit/clover + $ cd clover/samples/scenarios + $ git checkout stable/fraser + +To deploy the sample in the default Kubernetes namespace, use the following command for Istio +manual sidecar injection: + +.. code-block:: bash + + $ kubectl apply -f <(istioctl kube-inject --debug -f service_delivery_controller_opnfv.yaml) + +To deploy in another namespace, use the '-n' option. An example namespace of 'sdc' is shown below: + +.. code-block:: bash + + $ kubectl create namespace sdc + $ kubectl apply -n sdc -f <(istioctl kube-inject --debug -f service_delivery_controller_opnfv.yaml) + +When using the above SDC manifest, all required docker images will automatically be pulled +from the OPNFV public Dockerhub registry. An example of using a Docker local registry is also +provided in the ``/clover/samples/scenario`` directory. + +Verifying the deployment +------------------------ + +To verify the entire SDC sample is deployed, ensure the following pods have been deployed +with the command below: + +.. code-block:: bash + + $ kubectl get pod --all-namespaces + +The listing below must include the following SDC pods assuming deployment in the default +Kubernetes namespace: + +.. code-block:: bash + + $ NAMESPACE NAME READY STATUS + default clover-server1-68c4755d9c-7s5q8 2/2 Running + default clover-server2-57d8b786-rf5x7 2/2 Running + default clover-server3-556d5f79cf-hk6rv 2/2 Running + default clover-server4-6d9469b884-8srbk 2/2 Running + default clover-server5-5d64f74bf-l7wqc 2/2 Running + default http-lb-v1-59946c5744-w658d 2/2 Running + default http-lb-v2-5df78b6849-splp9 2/2 Running + default proxy-access-control-6b564b95d9-jg5wm 2/2 Running + default redis 2/2 Running + default snort-ids-5cc97fc6f-zhh5l 2/2 Running + +The result of the Istio deployment must include the following pods: + +.. code-block:: bash + + $ NAMESPACE NAME READY STATUS + istio-system istio-ca-59f6dcb7d9-9frgt 1/1 Running + istio-system istio-ingress-779649ff5b-mcpgr 1/1 Running + istio-system istio-mixer-7f4fd7dff-mjpr8 3/3 Running + istio-system istio-pilot-5f5f76ddc8-cglxs 2/2 Running + +Determining the ingress IP and port +----------------------------------- + +To determine how incoming http traffic on port 80 will be translated, use the following command: + +.. code-block:: bash + + $ kubectl get svc -n istio-system + NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) + istio-ingress LoadBalancer 10.104.208.165 <pending> 80:32410/TCP,443:31045/TCP + +**Note, the CLUSTER-IP of the service will be unused in this example since load balancing service +types are unsupported in this configuration. It is normal for the EXTERNAL-IP to show status +<pending> indefinitely** + +In this example, traffic arriving on port 32410 will flow to istio-ingress. The +istio-ingress service will route traffic to the proxy-access-control service based on a +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 +==================== + +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 +of the Kubernetes cluster. Modify the port used below (32410) with the port obtained from section +`Determining the ingress IP and port`_. If flannel is being used, requests can use the default +flannel CNI IP address, as shown below: + +.. code-block:: bash + + $ wget http://10.244.0.1:32410/ + $ curl http://10.244.0.1:32410/ + +An HTTP response will be returned as a result of the wget or curl command, if the SDC sample +is operating correctly. However, the visibility into what services were accessed within +the service mesh remains hidden. The next section `Exposing tracing and monitoring`_ shows how +to inspect the internals of the Istio service mesh. + +Exposing tracing and monitoring +------------------------------- + +To gain insight into the service mesh, the Jaeger tracing and Prometheus monitoring tools +can also be deployed. These tools can show how the sample functions in the service mesh. +Using the Clover container, issue the following command to deploy these tools +into your Kubernetes environment: + +.. code-block:: bash + + $ sudo docker run --rm \ + -v ~/.kube/config:/root/.kube/config \ + opnfv/clover \ + /bin/bash -c '/home/opnfv/repos/clover/samples/scenarios/view.sh' + +The Jaeger tracing UI is exposed outside of the Kubernetes cluster via any node IP in the cluster +using the following commands **(above command already executes the two commands below)**: + +.. code-block:: bash + + $ kubectl expose -n istio-system deployment jaeger-deployment --port=16686 --type=NodePort + +Likewise, the Promethues monitoring UI is exposed with the following command: + +.. code-block:: bash + + $ kubectl expose -n istio-system deployment prometheus --port=9090 --type=NodePort + +To find the ports the Jaeger tracing and Prometheus monitoring UIs are exposed on, use the +following command: + +.. code-block:: bash + + $ kubectl get svc --all-namespaces + NAMESPACE NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) + istio-system jaeger-deployment NodePort 10.105.94.85 <none> 16686:32174/TCP + istio-system prometheus NodePort 10.97.74.230 <none> 9090:32708/TCP + +In the example above, the Jaeger tracing web-based UI will be available on port 32171 and +the Prometheus monitoring UI on port 32708. In your browser, navigate to the following +URLs for Jaeger and Prometheus respectively:: + + http://<node IP>:32174 + http://<node IP>:32708 + +Where node IP is an IP from one of the Kubernetes cluster node(s). + +.. image:: imgs/sdc_tracing.png + :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 +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 +handling the request including: + + * istio-ingress + * proxy-access-control + * http-lb + * clover-server1 OR clover-server2 OR clover-server3 + +The individual traces can be clicked on to see the details of the messages between services. + +Modifying the run-time configuration of services +================================================ + +The following control-plane actions can be invoked via GRPC messaging from a controlling agent. +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.** + +Modifying the http-lb server list +---------------------------------- + +By default, both versions of the load balancers send incoming HTTP requests to clover-server1/2/3 +in round-robin fashion. To have the version 2 load balancer (http-lb-v2) send its traffic to +clover-server4/5 instead, issue the following command: + +.. code-block:: bash + + $ sudo docker run --rm \ + -v ~/.kube/config:/root/.kube/config \ + opnfv/clover \ + /bin/bash -c 'python /home/opnfv/repos/clover/samples/services/nginx/docker/grpc/nginx_client.py \ + --service_type=lbv2 --service_name=http-lb-v2' + +Adding rules to snort-ids +-------------------------- + +The snort service installs the readily available community rules. An initial, basic provision to +allow custom rule additions has been implemented within this release. A custom rule will trigger +alerts and can be defined in order to inspect network traffic. This capability, including +rule manipulation, will be further expounded upon in subsequent releases. For the time being, the +following basic rule additions can be performed using a client sample script. + +A snort IDS alert can be triggered by adding the HTTP User-Agent string shown below. The +signature that invokes this alert is part of the community rules that are installed in the +snort service by default. Using the curl or wget commands below, an alert can be observed using +the Jaeger tracing browser UI. It will be displayed as a GRPC message on port 50054 from the +**snort-ids** service to the **proxy-access-control** service. + +.. code-block:: bash + + $ wget -U 'asafaweb.com' http://10.244.0.1:32410/ + +Or alternatively with curl, issue this command to trigger the alert: + +.. code-block:: bash + + $ curl -A 'asafaweb.com' http://10.244.0.1:32410/ + +The community rule can be copied to local rules in order to ensure an alert is generated +each time the HTTP GET request is observed by snort using the following command. + +.. code-block:: bash + + $ sudo docker run --rm \ + -v ~/.kube/config:/root/.kube/config \ + opnfv/clover \ + /bin/bash -c 'python /home/opnfv/repos/clover/samples/services/snort_ids/docker/grpc/snort_client.py \ + --cmd=addscan --service_name=snort-ids' + +To add an ICMP rule to snort service, use the following command: + +.. code-block:: bash + + $ sudo docker run --rm \ + -v ~/.kube/config:/root/.kube/config \ + opnfv/clover \ + /bin/bash -c 'python /home/opnfv/repos/clover/samples/services/snort_ids/docker/grpc/snort_client.py \ + --cmd=addicmp --service_name=snort-ids' + +The above command will trigger alerts whenever ICMP packets are observed by the snort service. +An alert can be generated by pinging the snort service using the flannel IP address assigned to +the **snort-ids** pod. + +Advanced Usage +=============== + +A-B Validation +-------------- + +Please see the configuration guide at :ref:`a_b_config_guide` for details on +validating A-B route rules using the sample in this guide. + +Uninstall from Kubernetes envionment +==================================== + +Delete with Clover container +---------------------------- + +When you're finished working on the SDC sample, you can uninstall it with the +following command: + +.. code-block:: bash + + $ sudo docker run --rm \ + -v ~/.kube/config:/root/.kube/config \ + opnfv/clover \ + /bin/bash -c '/home/opnfv/repos/clover/samples/scenarios/clean.sh' + +The command above will remove the SDC sample services, Istio components and Jaeger/Prometheus +tools from your Kubernetes environment. + +Delete from source +------------------ + +The SDC sample services can be uninstalled from the source code using the commands below: + +.. code-block:: bash + + $ cd clover/samples/scenarios + $ kubectl delete -f service_delivery_controller_opnfv.yaml + + pod "redis" deleted + service "redis" deleted + deployment "clover-server1" deleted + service "clover-server1" deleted + deployment "clover-server2" deleted + service "clover-server2" deleted + deployment "clover-server3" deleted + service "clover-server3" deleted + deployment "clover-server4" deleted + service "clover-server4" deleted + deployment "clover-server5" deleted + service "clover-server5" deleted + deployment "http-lb-v1" deleted + deployment "http-lb-v2" deleted + service "http-lb" deleted + deployment "snort-ids" deleted + service "snort-ids" deleted + deployment "proxy-access-control" deleted + service "proxy-access-control" deleted + ingress "proxy-gateway" deleted + +Istio components will not be uninstalled with the above command, which deletes using the SDC +manifest file. To remove the Istio installation, navigate to the root directory where Istio +was installed from source and use the following command: + +.. code-block:: bash + + $ cd istio-0.6.0 + $ kubectl delete -f install/kubernetes/istio.yaml + + +Uninstall from Docker environment +================================= + +The OPNFV docker images can be removed with the following commands: + +.. code-block:: bash + + $ docker rmi opnfv/clover-ns-nginx-proxy + $ docker rmi opnfv/clover-ns-nginx-lb + $ docker rmi opnfv/clover-ns-nginx-server + $ docker rmi opnfv/clover-ns-snort-ids + $ docker rmi opnfv/clover + +The Redis, Prometheus and Jaeger docker images can be removed with the following commands: + +.. code-block:: bash + + $ docker rmi k8s.gcr.io/redis + $ docker rmi kubernetes/redis + $ docker rmi prom/prometheus + $ docker rmi jaegertracing/all-in-one + +If docker images were built locally, they can be removed with the following commands: + +.. code-block:: bash + + $ docker rmi localhost:5000/clover-ns-nginx-proxy + $ docker rmi clover-ns-nginx-proxy + $ docker rmi localhost:5000/clover-ns-nginx-lb + $ docker rmi clover-ns-nginx-lb + $ docker rmi localhost:5000/clover-ns-nginx-server + $ docker rmi clover-ns-nginx-server + $ docker rmi localhost:5000/clover-ns-snort-ids + $ docker rmi clover-ns-snort-ids diff --git a/docs/release/release-notes/index.rst b/docs/release/release-notes/index.rst index 1c41113..c7f8f6c 100644 --- a/docs/release/release-notes/index.rst +++ b/docs/release/release-notes/index.rst @@ -12,4 +12,4 @@ OPNFV Clover Design Specification .. toctree:: :maxdepth: 1 - Fraser-release-notes + release-notes diff --git a/docs/release/release-notes/Fraser-release-notes.rst b/docs/release/release-notes/release-notes.rst index 3e864fb..f345f61 100644 --- a/docs/release/release-notes/Fraser-release-notes.rst +++ b/docs/release/release-notes/release-notes.rst @@ -1,100 +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
-
-
-This document provides the release notes for Fraser of OPNFV Clover.
-
-.. contents::
- :depth: 3
- :local:
-
-
-Version history
----------------
-
-+--------------------+--------------------+--------------------+--------------------+
-| **Date** | **Ver.** | **Author** | **Comment** |
-| | | | |
-+--------------------+--------------------+--------------------+--------------------+
-| 2018-03-14 | Fraser 1.0 | Stephen Wong | First draft |
-| | | | |
-+--------------------+--------------------+--------------------+--------------------+
-
-Important notes
-===============
-
-The OPNFV Clover project for Fraser can ONLY be run on Kubernetes version 1.9.3 or
-above
-
-Summary
-=======
-
-Clover provides tools to help run cloud native virtual network functions. These
-tools include service-mesh and associated policy-based-routing config (via
-Istio), logging (via fluentd), monitoring (via Prometheus), and tracing (via
-OpenTracing and Jaeger).
-
-Release Data
-============
-
-+--------------------------------------+--------------------------------------+
-| **Project** | Clover |
-| | |
-+--------------------------------------+--------------------------------------+
-| **Repo/commit-ID** | |
-| | |
-+--------------------------------------+--------------------------------------+
-| **Release designation** | Fraser |
-| | |
-+--------------------------------------+--------------------------------------+
-| **Release date** | 2018-04-xx |
-| | |
-+--------------------------------------+--------------------------------------+
-| **Purpose of the delivery** | OPNFV Fraser release |
-| | |
-+--------------------------------------+--------------------------------------+
-
-Version change
-^^^^^^^^^^^^^^^^
-
-Module version changes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Fraser marks the first release of OPNFV Clover
-
-Document version changes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Fraser marks the first release of OPNFV Clover
-
-Reason for version
-^^^^^^^^^^^^^^^^^^^^
-
-Feature additions
-~~~~~~~~~~~~~~~~~~~~~~~
-<None> (no backlog)
-
-Bug corrections
-~~~~~~~~~~~~~~~~~~~~~
-<None>
-
-Known Limitations, Issues and Workarounds
-=========================================
-
-System Limitations
-^^^^^^^^^^^^^^^^^^^^
-TBD
-
-Known issues
-^^^^^^^^^^^^^^^
-TBD
-
-Workarounds
-^^^^^^^^^^^^^^^^^
-
-Test Result
-===========
-
-
-References
-==========
+.. 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 + + +This document provides Clover project's release notes for the OPNFV Fraser release. + +.. contents:: + :depth: 3 + :local: + + +Version history +--------------- + ++--------------------+--------------------+--------------------+--------------------+ +| **Date** | **Ver.** | **Author** | **Comment** | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ +| 2018-03-14 | Fraser 1.0 | Stephen Wong | First draft | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ + +Important notes +=============== + +The Clover project for OPNFV Fraser can ONLY be run on Kubernetes version 1.9 or +later + +Summary +======= + +Clover Fraser release provides tools for installation and validation of various +upstream cloud native projects including Istio, fluentd, Jaegar, and Prometheus. +In addition, the Fraser release also includes a sample VNF, its Kubernetes +manifest, simple tools to validate route rules from Istio, as well as an +example A-B testing framework. + +Release Data +============ + ++--------------------------------------+--------------------------------------+ +| **Project** | Clover | +| | | ++--------------------------------------+--------------------------------------+ +| **Repo/commit-ID** | | +| | | ++--------------------------------------+--------------------------------------+ +| **Release designation** | Fraser | +| | | ++--------------------------------------+--------------------------------------+ +| **Release date** | 2018-04-27 +| | | ++--------------------------------------+--------------------------------------+ +| **Purpose of the delivery** | OPNFV Fraser release | +| | | ++--------------------------------------+--------------------------------------+ + +Version change +^^^^^^^^^^^^^^^^ + +Module version changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +OPNFV Fraser marks the first release for Clover + +Document version changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +OPNFV Fraser marks the first release for Clover + +Reason for version +^^^^^^^^^^^^^^^^^^^^ + +Feature additions +~~~~~~~~~~~~~~~~~~~~~~~ +<None> (no backlog) + +Bug corrections +~~~~~~~~~~~~~~~~~~~~~ +<None> + +Known Limitations, Issues and Workarounds +========================================= + +System Limitations +^^^^^^^^^^^^^^^^^^^^ +TBD + +Known issues +^^^^^^^^^^^^^^^ +TBD + +Workarounds +^^^^^^^^^^^^^^^^^ + +Test Result +=========== + + +References +========== diff --git a/docs/release/userguide/Fraser-userguide.rst b/docs/release/userguide/Fraser-userguide.rst deleted file mode 100644 index 243c4e1..0000000 --- a/docs/release/userguide/Fraser-userguide.rst +++ /dev/null @@ -1,81 +0,0 @@ -.. 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 - - -================================================================ -Clover User Guide (Fraser Release) -================================================================ - -This document provides the user guide for Fraser release of Clover. - -.. contents:: - :depth: 3 - :local: - - -Description -=========== - -Project Clover was established to investigate best practice to implement, -build, deploy, and operate virtual network functions as cloud native -applications. "Cloud native" has a ever evolving and expanding definition, -and in Clover, the focus is effectively running and operating VNFs built -in a micro-service design pattern running on Docker containers and -orchestrated by Kubernetes. - -The strength of cloud native applications is their operablity and -scalability. Essential to achieve these qualities is the use of service -mesh. As such, in Fraser release, Clover's emphasis is on demonstrating -running a sample micro-service composed VNF on Istio, the service mesh -platform of Clover's choice in Fraser, and how to maximize visibility -of this sample running in a service mesh. - -What is in Fraser? -================== - - * a sample micro-service composed VNF - - * logging module: fluentd and elasticsearch Kubernetes manifests, - installation validation, log data correlation in datastore - - * tracing module: jaeger Kubernetes manifest, installation validation, - jaegar tracing query tools, trace data correlation in datastore - - * monitoring module: prometheus Kubernetes manifest, installation - validation, prometheous query tools for Istio related metrics, - metrics correlation in datastore - - * Istio route-rules and circuit breaking sample yaml and validation - tools - - * Test scripts - - * Reference for a demo shown during ONS - -Usage -===== - - * each modules (service mesh, logging, tracing, monitoring) are Python - modules with their own set of library calls / API exposed. The descriptions - of these library calls are under doc/developer (TBD) - - * tools directory contains Python tools for generic use - python clover_validate_route_rules.py -s <service name> -n <number of tests> - [more TBD] - - * an example scenario: - - version 2 (v2) of a micro-service component is deployed - - Istio route rule is applied to send 50% traffic to v2 - - Clover tool validates traffic conformance with route rules - - user specify via yaml the "success" expectation of v2 (latency, - performance, session loss...etc) - - Clover tool validates sessions conformance with user defined expectations - - The "commit" action is invoked to move 100% traffic to v2 - - Clover tool validates traffic conformance with route rules - - A fault is injected for the path to the extra service of v2 which adds - a one second delay onto the path - - The same A-B testing script is invoked, this time, performance - test now fails - - The "rollback" action is invoked to move 100% traffic back to v1 diff --git a/docs/release/userguide/index.rst b/docs/release/userguide/index.rst index 41fcb1f..672c62c 100644 --- a/docs/release/userguide/index.rst +++ b/docs/release/userguide/index.rst @@ -10,4 +10,4 @@ OPNFV Clover Design Specification .. toctree:: :maxdepth: 1 - Fraser-userguide + userguide diff --git a/docs/release/userguide/userguide.rst b/docs/release/userguide/userguide.rst new file mode 100644 index 0000000..c01886e --- /dev/null +++ b/docs/release/userguide/userguide.rst @@ -0,0 +1,64 @@ +.. 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 + + +================================================================ +Clover User Guide (Fraser Release) +================================================================ + +This document provides the Clover user guide for OPNFV Fraser release. + +.. contents:: + :depth: 3 + :local: + + +Description +=========== + +As project Clover's first release, Fraser release includes installation +and simple validation of foundational upstream projects including Istio, +fluentd, Jaeger, and Prometheus. Clover Fraser release also provides a +sample VNF which follows micro-service design pattern, its Kubernetes +manifest, and an automatic scipt to demonstrate a sample A-B testing use +case using the sample VNF running on Istio with trace data exposed to +Jaeger running in istio-system namespace. + +What is in Fraser? +================== + + * a sample micro-service composed VNF + + * logging module: fluentd and elasticsearch Kubernetes manifests, + and fluentd installation validation + + * tracing module: jaeger Kubernetes manifest, installation validation, + jaegar tracing query tools, module for trace data output to datastore + + * monitoring module: prometheus Kubernetes manifest, installation + validation, sample Prometheous query of Istio related metrics + + * Istio route-rules sample yaml and validation tools + + * Test scripts + + * Sample code for an A-B testing demo shown during ONS + +Usage +===== + + * Python modules to validate installation of fluentd, Jaeger, and + Prometheus + + * Installation and deployment of a sample VNF + - VNF designed and implemented with micro-service design pattern + - tested and validated via Istio service mesh tools + + * sample tool to validate Istio route rules: + tools/python clover_validate_route_rules.py -s <service name> -t <test id> + + * an example use case: A-B testing: + test/fraser_a_b_test.py -t yaml/fraser_a_b_test.yaml -p <tracing port num> + *** detail procedure to run sample A-B testing at docs/configguide/... diff --git a/samples/services/snort_ids/docker/grpc/snort_alerts.py b/samples/services/snort_ids/docker/grpc/snort_alerts.py index 4cb87e2..25d1738 100644 --- a/samples/services/snort_ids/docker/grpc/snort_alerts.py +++ b/samples/services/snort_ids/docker/grpc/snort_alerts.py @@ -14,7 +14,7 @@ from idstools import unified2 HOST_IP = 'redis' -PROXY_GRPC = 'proxy-access-control:50054' +# PROXY_GRPC = 'proxy-access-control:50054' logging.basicConfig(filename='alert.log', level=logging.DEBUG) @@ -34,7 +34,7 @@ reader = unified2.SpoolRecordReader("/var/log/snort", def sendGrpcAlert(event_id, redis_key): try: - channel = grpc.insecure_channel(PROXY_GRPC) + channel = grpc.insecure_channel('proxy-access-control:50054') stub = nginx_pb2_grpc.ControllerStub(channel) stub.ProcessAlerts(nginx_pb2.AlertMessage( event_id=event_id, redis_key=redis_key)) @@ -45,13 +45,15 @@ def sendGrpcAlert(event_id, redis_key): for record in reader: try: if isinstance(record, unified2.Event): - snort_event = "snort_event:" + str(record['event-id']) - r.sadd('snort_events', str(record['event-id'])) - r.hmset(snort_event, record) - sendGrpcAlert(str(record['event-id']), 'snort_events') - # elif isinstance(record, unified2.Packet): - # print("Packet:") + event = record + elif isinstance(record, unified2.Packet): + packet = record # elif isinstance(record, unified2.ExtraData): # print("Extra-Data:") + snort_event = "snort_event:" + str(record['event-id']) + r.sadd('snort_events', str(record['event-id'])) + event.update(packet) + r.hmset(snort_event, event) + sendGrpcAlert(str(record['event-id']), 'snort_events') except Exception as e: logging.debug(e) diff --git a/samples/services/snort_ids/docker/grpc/snort_server.py b/samples/services/snort_ids/docker/grpc/snort_server.py index 9ece832..223461a 100644 --- a/samples/services/snort_ids/docker/grpc/snort_server.py +++ b/samples/services/snort_ids/docker/grpc/snort_server.py @@ -33,10 +33,16 @@ class Controller(snort_pb2_grpc.ControllerServicer): # file_local = 'testfile' file_local = '/etc/snort/rules/local.rules' f = open(file_local, 'a') - rule = 'alert {} {} {} -> {} {} '.format( - r.protocol, r.src_ip, r.src_port, r.dest_ip, r.dest_port) \ - + '(msg:"{}"; content:{}; sid:{}; rev:{};)\n'.format( - r.msg, r.content, r.sid, r.rev) + if r.content: + rule = 'alert {} {} {} -> {} {} '.format( + r.protocol, r.src_ip, r.src_port, r.dest_ip, r.dest_port) \ + + '(msg:"{}"; content:{}; sid:{}; rev:{};)\n'.format( + r.msg, r.content, r.sid, r.rev) + else: + rule = 'alert {} {} {} -> {} {} '.format( + r.protocol, r.src_ip, r.src_port, r.dest_ip, r.dest_port) \ + + '(msg:"{}"; sid:{}; rev:{};)\n'.format( + r.msg, r.sid, r.rev) f.write(rule) f.close msg = "Added to local rules" |
