Add Dynamic VNFFG usage guide

This patch also reorders the user guide index page.
And fix a docs test with tox.

Change-Id: I0522f6aa40d47f40178820a99a2723ba2af9cf72
Closes-Bug: #1774356

doc/source/contributor/index.rst

@@ -36,6 +36,10 @@ Code Documentation
 
 :ref:`modindex`
 
+.. toctree::
+   :maxdepth: 1
+
+   api/modules.rst
 
 API Documentation
 -----------------

doc/source/install/openstack_vim_installation.rst

@@ -29,7 +29,7 @@ and be used to run kolla-ansible tool.
 
 The basic information and the topology of these nodes is like this:
 
-.. image:: openstack_nodes.png
+.. image:: ../_images/openstack_nodes.png
    :scale: 50 %
 
 
@@ -238,7 +238,7 @@ This is a simple task for any OpenStack administrator, but one thing to pay
 attention to is that the user must have 'admin' and 'heat_stack_owner'
 roles on the user's project.
 
-.. image:: openstack_role.png
+.. image:: ../_images/openstack_role.png
    :scale: 50 %
 
 

doc/source/user/dynamic_vnffg_usage_guide.rst

@@ -0,0 +1,294 @@
+..
+  Licensed under the Apache License, Version 2.0 (the "License"); you may
+  not use this file except in compliance with the License. You may obtain
+  a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+  License for the specific language governing permissions and limitations
+  under the License.
+
+
+==========================
+A Use Case of VNFFG Update
+==========================
+
+This guide walks you through a specific usecase in which you can leverage
+the Zabbix monitoring software to create a dynamic VNF Forwarding Graph
+(VNFFG) or Service Function Chaining (SFC). You can check out the video
+presentation here [#f1]_ and slides here [#f2]_ to see how to do it in action.
+
+
+Prerequisites
+=============
+
+**1. Two libvirt VMs** to install devstack and Zabbix server.
+
+**2. Two libvirt networks** which can reach the internet (one management,
+one devstack external)
+
+
+Topology
+========
+
+**1. Chain:** IDS (Suricata), Openwrt (VNFs)
+
+**2. Target to protect:** Server nova instance.
+
++ SFC with no classifier (HTTP works, ICMP works)
+
+.. figure:: ../_images/sfc1.png
+   :alt: SFC with no classifier
+
++ SFC with ICMP classifier (HTTP works, ICMP dropped)
+
+.. figure:: ../_images/sfc2.png
+   :alt: SFC with ICMP classifier
+
+Setting up and produce the scenario
+===================================
+
+**1.** Install **devstack** in a VM as it is described here [#f3]_ using the
+configuration sample here [#f4]_ (Please add here the right configuration for
+the management and external networks). Two network interfaces, one for the
+management and one for the external network.
+
+**2.** Create a second VM where you will install the **Zabbix server**
+according to these instructions [#f5]_. Please be sure that the Zabbix server
+has an interface on the same network as the external network of devstack to be
+able to monitor the server nova instance through the floating IP.
+
+Config the Zabbix server as below:
+
++ Register the devstack machine (the host that we want to monitor and it
+  should have installed the Zabbix agent, see step 3)
+
+.. figure:: ../_images/zabbix1.JPG
+   :alt: Zabbix server config 1
+
++ Create a trigger with a name which contains the keyword BpS (e.g. BpS in the
+  eth0 is too high) and add to that trigger an expression-condition which will
+  generate an event if the traffic will set this expression-condition to True.
+  The expression-condition is:
+
+.. code-block:: console
+
+  {host-10-10-1-12:net.if.in[eth0].avg(2)}>2000
+
+..
+
+.. figure:: ../_images/zabbix2.JPG
+   :alt: Zabbix server config 2
+
++ Create an action which will update the classifier if a trigger with the BpS
+  name will generated by the Zabbix server. To do this you need to create an
+  action , set the keyword of the Trigger which will make this action to
+  actually come to play and also you need to create an operation inside that
+  action where you will write the update-vnffg command which you will execute
+  to update the current classifier.
+
+.. figure:: ../_images/zabbix3.JPG
+   :alt: Zabbix server config 3
+
+.. figure:: ../_images/zabbix4.JPG
+   :alt: Zabbix server config 4
+
+The action command is as follows:
+
+.. code-block:: console
+
+  /usr/local/bin/openstack --os-username admin \
+                           --os-password devstack \
+                           --os-project-name admin \
+                           --os-user-domain-name default \
+                           --os-project-domain-name default \
+                           --os-project-domain-id default \
+                           --os-auth-url http://<devstack ip address>/identity/v3 \
+                           --os-region-name RegionOne \
+                           vnf graph set \
+                           --vnffgd-template vnffg_block_icmp.yaml block_icmp
+
+..
+
+**3.** Install in the **server nova instance** and in the devstack VM
+natively the **Zabbix agent**. The Zabbix agent in the server nova instance is
+used to send data back to the Zabbix server. The Zabbix agent in the devstack
+VM is essential because we execute from the Zabbix server the vnffg-update
+command so we can update the classifier of the chain. And for this we need the
+Zabbix agent to the devstack VM.
+
+**4.** Deploy two Service Functions (SFs) via two VNFs:
+
+-  The first one is Suricata (IDS) which will be deployed using this VNFD
+   template
+
+.. code-block:: yaml
+
+  tosca_definitions_version: tosca_simple_profile_for_nfv_1_0_0
+  description: suricata
+  metadata:
+    template_name: suricata
+
+  topology_template:
+    node_templates:
+      VDU1:
+        type: tosca.nodes.nfv.VDU.Tacker
+        capabilities:
+          nfv_compute:
+            properties:
+              num_cpus: 1
+              mem_size: 4096 MB
+              disk_size: 15 GB
+        properties:
+          image: danube
+          availability_zone: nova
+          mgmt_driver: noop
+          config: |
+            param0: key1
+            param1: key2
+          service_type: firewall
+          monitoring_policy:
+            name: ping
+            parameters:
+              monitoring_delay: 10
+              count: 3
+              interval: 2
+              timeout: 2
+              action:
+                failure: respawn
+              retry: 5
+              port: 22
+
+      CP2:
+        type: tosca.nodes.nfv.CP.Tacker
+        properties:
+          management: true
+          order: 0
+          anti_spoofing_protection: false
+        requirements:
+          - virtualLink:
+              node: VL1
+          - virtualBinding:
+              node: VDU1
+
+      VL1:
+        type: tosca.nodes.nfv.VL
+        properties:
+          network_name: net1
+          vendor: Tacker
+..
+
+   After the VNF instance has been deployed successfully, SSH to it and
+   configure as in [#f6]_.
+
+-  The second one is OpenWrt with the configuration is the same as it is
+   described in the Tacker docs [#f7]_, use the VNFD template here [#f8]_
+   and param file here [#f9]_.
+
+**5.** Create a VNFFG with a chain (IDS, Openwrt) and no classifier
+
+**vnffg_no_classifier.yaml**
+
+.. code-block:: yaml
+
+  tosca_definitions_version: tosca_simple_profile_for_nfv_1_0_0
+
+  description: Sample VNFFG template
+
+  topology_template:
+    node_templates:
+
+      Forwarding_path1:
+        type: tosca.nodes.nfv.FP.TackerV2
+        description: demo chain
+        properties:
+          id: 51
+          path:
+            - forwarder: IDS
+              capability: CP2
+            - forwarder: openwrt
+              capability: CP4
+
+    groups:
+      VNFFG1:
+        type: tosca.groups.nfv.VNFFG
+        description: Traffic to server
+        properties:
+          vendor: tacker
+          version: 1.0
+          number_of_endpoints: 2
+          dependent_virtual_link: [VL1,VL2]
+          connection_point: [CP2,CP4]
+          constituent_vnfs: [IDS,openwrt]
+        members: [Forwarding_path1]
+
+..
+
+**6.** Generate ICMP traffic using PING towards the floating IP of the server
+nova instance and when that traffic reaches a threshold a specific event is
+published to the Zabbix server and Zabbix server executes the vvnffg-update
+action which update the already created VNFFG with a classifier which
+classifies the ICMP traffic
+
+**vnffg_block_icmp.yaml**
+
+.. code-block:: yaml
+
+  tosca_definitions_version: tosca_simple_profile_for_nfv_1_0_0
+
+  description: Sample VNFFG template
+
+  topology_template:
+    node_templates:
+
+      Forwarding_path1:
+        type: tosca.nodes.nfv.FP.TackerV2
+        description: demo chain
+        properties:
+          id: 51
+          policy:
+            type: ACL
+            criteria:
+              - name: block_icmp
+                classifier:
+                  network_src_port_id: 654eaf96-3737-4b72-9dd7-445a26dfc2ee
+                  ip_proto: 1
+          path:
+            - forwarder: IDS
+              capability: CP2
+            - forwarder: openwrt
+              capability: CP4
+
+    groups:
+      VNFFG1:
+        type: tosca.groups.nfv.VNFFG
+        description: Traffic to server
+        properties:
+          vendor: tacker
+          version: 1.0
+          number_of_endpoints: 2
+          dependent_virtual_link: [VL1,VL2]
+          connection_point: [CP2,CP4]
+          constituent_vnfs: [IDS,openwrt]
+        members: [Forwarding_path1]
+
+..
+
+That means that the traffic will be steered to the SFs and it will be
+mitigated.
+
+
+.. rubric:: Footnotes
+
+.. [#f1] https://www.openstack.org/videos/vancouver-2018/dynamic-sfc-from-tacker-to-incept-specific-traffic-of-vm-1
+.. [#f2] https://github.com/dangtrinhnt/DynamicSFCDemo/blob/master/DynamicSFC_OpenStackSummit2018Vancouver.pdf
+.. [#f3] https://docs.openstack.org/devstack/latest/
+.. [#f4] https://github.com/openstack/tacker/blob/master/devstack/local.conf.example
+.. [#f5] https://www.digitalocean.com/community/tutorials/how-to-install-and-configure-zabbix-to-securely-monitor-remote-servers-on-ubuntu-16-04
+.. [#f6] https://blog.rapid7.com/2017/02/14/how-to-install-suricata-nids-on-ubuntu-linux/
+.. [#f7] https://docs.openstack.org/tacker/latest/install/deploy_openwrt.html
+.. [#f8] https://github.com/openstack/tacker/blob/master/samples/tosca-templates/vnfd/tosca-vnfd-openwrt.yaml
+.. [#f9] https://github.com/openstack/tacker/blob/master/samples/tosca-templates/vnfd/tosca-config-openwrt-firewall.yaml

doc/source/user/index.rst

@@ -34,17 +34,18 @@ User Guide
    :maxdepth: 1
 
    alarm_monitoring_usage_guide.rst
-   containerized_vnf_usage_guide.rst
+   dynamic_vnffg_usage_guide.rst
    enhanced_placement_awareness_usage_guide.rst
+   containerized_vnf_usage_guide.rst
+   ../reference/mistral_workflows_usage_guide.rst
    multisite_vim_usage_guide.rst
    nsd_usage_guide.rst
+   ../reference/block_storage_usage_guide.rst
    scale_usage_guide.rst
    vnf_component_usage_guide.rst
    vnffg_usage_guide.rst
    vnffg_usage_guide_advanced.rst
    vnfm_usage_guide.rst
-   ../reference/mistral_workflows_usage_guide.rst
-   ../reference/block_storage_usage_guide.rst
 
 Feature Documentation
 ---------------------
@@ -52,13 +53,13 @@ Feature Documentation
 .. toctree::
    :maxdepth: 1
 
+   ../contributor/zabbix-plugin.rst
+   ../contributor/tacker_vim_monitoring.rst
    ../contributor/encrypt_vim_auth_with_barbican.rst
    ../contributor/event_logging.rst
    ../contributor/monitor-api.rst
    ../contributor/policy_actions_framework.rst
    ../contributor/tacker_conductor.rst
-   ../contributor/tacker_vim_monitoring.rst
    ../contributor/vnfd_template_description.rst
    ../contributor/vnfd_template_parameterization.rst
    ../contributor/vnffgd_template_description.rst
-   ../contributor/zabbix-plugin.rst