From 7d6f6962fb9c5ff6d815241d5d15c86c4c6a501b Mon Sep 17 00:00:00 2001 From: "serena.spinoso" Date: Thu, 16 Mar 2017 16:18:24 +0100 Subject: Add verigraph documentation Add user guide and test usage documentation. Add examples of service graphs to use verigraph. Change-Id: I3e454e03fa2de99bad0761e3e4a0eab98f2e0b23 Signed-off-by: serena.spinoso --- docs/release/userguide/feature.userguide.rst | 61 ++++++++++++- docs/testing/testusage.rst | 56 +++++++++++- verigraph/examples/verigraph-req3-fail.json | 115 +++++++++++++++++++++++++ verigraph/examples/verigraph-req3-success.json | 115 +++++++++++++++++++++++++ 4 files changed, 343 insertions(+), 4 deletions(-) create mode 100644 verigraph/examples/verigraph-req3-fail.json create mode 100644 verigraph/examples/verigraph-req3-success.json diff --git a/docs/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst index f1e1362..1113118 100644 --- a/docs/release/userguide/feature.userguide.rst +++ b/docs/release/userguide/feature.userguide.rst @@ -44,7 +44,7 @@ Example: tosca-parser --template-file=vRNC.yaml Parser tosca2heat References -=========================== +============================ Refer two upstream components: https://github.com/openstack/tosca-parser/blob/master/doc/source/usage.rst https://github.com/openstack/heat-translator/blob/master/doc/source/usage.rst @@ -53,7 +53,7 @@ Refer two upstream components: Parser yang2tosca Execution -============================ +=========================== Step 1: Change directory to where the scripts are present. @@ -94,7 +94,7 @@ Example: Parser policy2tosca Execution -============================ +============================= Step 1: To see a list of commands available. @@ -141,3 +141,58 @@ Example: cat example_tosca.yaml + +Parser verigraph Execution +========================== + +VeriGraph is accessible via both a RESTful API and a gRPC interface. + +**REST API** + +Step 1. Change directory to where the service graph examples are present + +.. code-block:: bash + + cd parser/verigraph/examples + +Step 2. Use a REST client (e.g., cURL) to send a POST request (whose body is one of the JSON +file in the directory) + +.. code-block:: bash + + curl -X POST -d @.json http://:/verify/api/graphs + --header "Content-Type:application/json" + +Step 3. Use a REST client to send a GET request to check a reachability-based property between +two nodes of the service graph created in the previous step. + +.. code-block:: bash + + curl -X GET http://:/verify/api/graphs// + policy?source=&destination=&type= + +where: + +- is the identifier of the service graph created at Step 2 +- is the name of the source node +- is the name of the destination node +- can be ``reachability``, ``isolation`` or ``traversal`` + +Step 4. the output is a JSON with the overall result of the verification process and the partial +result for each path that connects the source and destination nodes in the service graph. + +**gRPC API** + +VeriGraph exposes a gRPC interface that is self-descriptive by its Protobuf file +(``parser/verigraph/src/main/proto/verigraph.proto``). In the current release, Verigraph +misses a module that receives service graphs in format of JSON and sends the proper +requests to the gRPC server. A testing client has been provided to have an example of how +to create a service graph using the gRPC interface and to trigger the verification step. + +1. Run the testing client + +.. code-block:: bash + + cd parser/verigraph + #Client souce code in ``parser/verigraph/src/main/it/polito/grpc/Client.java`` + ant -f buildVeriGraph_gRPC.xml run-client diff --git a/docs/testing/testusage.rst b/docs/testing/testusage.rst index 405d6bd..36b9c00 100644 --- a/docs/testing/testusage.rst +++ b/docs/testing/testusage.rst @@ -3,7 +3,7 @@ Parser tosca2heat test usage -=========================== +============================ 1. run tox in tosca-parser sub project .. code-block:: bash @@ -52,3 +52,57 @@ or # run tox tox +Parser VeriGraph test usage +=========================== + +VeriGraph is accessible via both a RESTfull API and a gRPC interface. + +**RESTful API** + +1. Run the Python tester + +.. code-block:: bash + + cd parser/verigraph/tester + python test.py + +**gRPC API** + +1. Compile the code + +.. code-block:: bash + + cd parser/verigraph + ant -f buildVeriGraph_gRPC.xml build + +2. Run both client and server + +.. code-block:: bash + + cd parser/verigraph + ant -f buildVeriGraph_gRPC.xml run + +3. Run only the testing client + +.. code-block:: bash + + cd parser/verigraph + ant -f buildVeriGraph_gRPC.xml run-client + +4. Run only the gRPC server + +.. code-block:: bash + + cd parser/verigraph + ant -f buildVeriGraph_gRPC.xml run-server + +5. Run all tests and print out the partial results and global result + +.. code-block:: bash + + cd parser/verigraph + # This target has the needed dependencies to compile the code + # and run both client and server + ant -f buildVeriGraph_gRPC.xml run-test + +Note that the execution of these tests may take up to 1-2 minutes when successful. diff --git a/verigraph/examples/verigraph-req3-fail.json b/verigraph/examples/verigraph-req3-fail.json new file mode 100644 index 0000000..dc8482f --- /dev/null +++ b/verigraph/examples/verigraph-req3-fail.json @@ -0,0 +1,115 @@ +{ + "nodes":[ + { + "neighbours":[ + { + "name":"webserver1" + }, + { + "name":"nat" + } + ], + "configuration":[ + { + "webserver1":"nat" + } + ], + "name":"fw", + "functional_type":"firewall" + }, + { + "neighbours":[ + { + "name":"host3" + }, + { + "name":"fw" + } + ], + "name":"webserver1", + "functional_type":"webserver" + }, + { + "neighbours":[ + { + "name":"host1" + }, + { + "name":"dpi" + }, + { + "name":"fw" + } + ], + "configuration":[ + "host1", + "host2" + ], + "name":"nat", + "functional_type":"nat" + }, + { + "neighbours":[ + { + "name":"host2" + } + ], + "configuration":[ + "sex" + ], + "name":"dpi", + "functional_type":"dpi" + }, + { + "neighbours":[ + { + "name":"nat" + } + ], + "configuration":[ + { + "url":"www.facebook.com", + "body":"sex", + "destination":"webserver1", + "protocol":"HTTP_REQUEST" + } + ], + "name":"host2", + "functional_type":"endhost" + }, + { + "neighbours":[ + { + "name":"nat" + } + ], + "configuration":[ + { + "url":"www.facebook.com", + "body":"cats", + "destination":"webserver1", + "protocol":"HTTP_REQUEST" + } + ], + "name":"host1", + "functional_type":"endhost" + }, + { + "neighbours":[ + { + "name":"webserver1" + } + ], + "configuration":[ + { + "url":"www.facebook.com", + "body":"cats", + "destination":"webserver1", + "protocol":"HTTP_REQUEST" + } + ], + "name":"host3", + "functional_type":"endhost" + } + ] +} \ No newline at end of file diff --git a/verigraph/examples/verigraph-req3-success.json b/verigraph/examples/verigraph-req3-success.json new file mode 100644 index 0000000..127a677 --- /dev/null +++ b/verigraph/examples/verigraph-req3-success.json @@ -0,0 +1,115 @@ +{ + "nodes":[ + { + "neighbours":[ + { + "name":"webserver1" + }, + { + "name":"nat" + } + ], + "configuration":[ + { + "ip_host1":"webserver1" + } + ], + "name":"fw", + "functional_type":"firewall" + }, + { + "neighbours":[ + { + "name":"host3" + }, + { + "name":"fw" + } + ], + "name":"webserver1", + "functional_type":"webserver" + }, + { + "neighbours":[ + { + "name":"host1" + }, + { + "name":"dpi" + }, + { + "name":"fw" + } + ], + "configuration":[ + "host1", + "host2" + ], + "name":"nat", + "functional_type":"nat" + }, + { + "neighbours":[ + { + "name":"host2" + } + ], + "configuration":[ + "sex" + ], + "name":"dpi", + "functional_type":"dpi" + }, + { + "neighbours":[ + { + "name":"nat" + } + ], + "configuration":[ + { + "url":"www.facebook.com", + "body":"candy", + "destination":"webserver1", + "protocol":"HTTP_REQUEST" + } + ], + "name":"host2", + "functional_type":"endhost" + }, + { + "neighbours":[ + { + "name":"nat" + } + ], + "configuration":[ + { + "url":"www.facebook.com", + "body":"cats", + "destination":"webserver1", + "protocol":"HTTP_REQUEST" + } + ], + "name":"host1", + "functional_type":"endhost" + }, + { + "neighbours":[ + { + "name":"webserver1" + } + ], + "configuration":[ + { + "url":"www.facebook.com", + "body":"cats", + "destination":"webserver1", + "protocol":"HTTP_REQUEST" + } + ], + "name":"host3", + "functional_type":"endhost" + } + ] +} \ No newline at end of file -- cgit 1.2.3-korg