Extended documentation for Euphrates

Inlcuded user guide and configuration guide that can be used to get started immediately with orchestra

Change-Id: Idec9cf8462b0497addc8419fb77744a639fd8718
Signed-off-by: Giuseppe Carella <cargius@gmail.com>
Signed-off-by: Michael Pauls <michael.pauls@fokus.fraunhofer.de>

4 files changed, 320 insertions, 10 deletions

diff --git a/docs/release/userguide/descriptors/nsd.json b/docs/release/userguide/descriptors/nsd.json
new file mode 100644
index 0000000..4b20bcb
--- /dev/null
+++ b/docs/release/userguide/descriptors/nsd.json
@@ -0,0 +1,214 @@
+{
+  "name":"NSD SIPp Floating IPs",
+  "vendor":"FOKUS",
+  "version":"1.0",
+  "vld":[
+    {
+      "name":"private"
+    }
+  ],
+  "vnfd":[
+    {
+      "name":"sipp-client",
+      "vendor":"FOKUS",
+      "version":"1.0",
+      "lifecycle_event":[
+        {
+          "event":"CONFIGURE",
+          "lifecycle_events":[
+            "server_sipp_start.sh"
+          ]
+        },
+        {
+          "event":"INSTANTIATE",
+          "lifecycle_events":[
+            "sipp_install.sh"
+          ]
+        }
+      ],
+      "vdu":[
+        {
+          "vm_image":[
+            "ubuntu-14.04"
+          ],
+          "scale_in_out":5,
+          "vnfc":[
+            {
+              "connection_point":[
+                {
+                  "floatingIp":"random",
+                  "virtual_link_reference":"private",
+                  "interfaceId":0
+                }
+              ]
+            }
+          ],
+          "vimInstanceName":[]
+        }
+      ],
+      "configurations": {
+        "configurationParameters": [
+          {
+            "confKey": "SIPP_LENGTH",
+            "value": "0",
+            "description": "Controls the length (in milliseconds) of calls. More precisely, this controls the duration of 'pause' instructions in the scenario, if they do not have a 'milliseconds' section. Default value is 0."
+          },
+          {
+            "confKey": "SIPP_RATE",
+            "value": "10",
+            "description": "Set the call rate (in calls per seconds). Default is 10. If the -rp option is used, the call rate is calculated with the period in ms given by the user."
+          },
+          {
+            "confKey": "SIPP_RATE_PERIOD",
+            "value": "1000",
+            "description": "Specify the rate period in milliseconds for the call rate.  Default is 1 second.  This allows you to have n calls every m milliseconds (by using -r n -rp m). Example: -r 7 -rp 2000 ==> 7 calls every 2 seconds."
+          },
+          {
+            "confKey": "SIPP_RATE_MAX",
+            "value": "10",
+            "description": "If -rate_increase is set, then quit after the rate reaches this value. Example: -rate_increase 10 -max_rate 100 ==> increase calls by 10 until 100 cps is hit."
+          },
+          {
+            "confKey": "SIPP_RATE_INCREASE",
+            "value": "0",
+            "description": "Specify the rate increase every -fd seconds.  This allows you to increase the load for each independent logging period. Example: -rate_increase 10 -fd 10 ==> increase calls by 10 every 10 seconds."
+          },
+          {
+            "confKey": "SIPP_RTP_ECHO",
+            "value": "10",
+            "description": "Enable RTP echo. RTP/UDP packets received on port defined by -mp are echoed to their sender. RTP/UDP packets coming on this port + 2 are also echoed to their sender (used for sound and video echo)."
+          },
+          {
+            "confKey": "SIPP_TRANSPORT_MODE",
+            "value": "u1",
+            "description": "Set the transport mode: - u1: UDP with one socket (default), - un: UDP with one socket per call, - ui: UDP with one socket per IP address The IP addresses must be defined in the injection file. - t1: TCP with one socket, - tn: TCP with one socket per call, - l1: TLS with one socket, - ln: TLS with one socket per call, - c1: u1 + compression (only if compression plugin loaded), - cn: un + compression (only if compression plugin loaded)."
+          }
+        ],
+        "name": "sipp-configuration"
+      },
+      "virtual_link":[
+        {
+          "name":"private"
+        }
+      ],
+      "deployment_flavour":[
+        {
+          "flavour_key":"m1.small"
+        }
+      ],
+      "auto_scale_policy": [
+        {
+          "name":"scale-out",
+          "threshold":100,
+          "comparisonOperator":">=",
+          "period":30,
+          "cooldown":60,
+          "mode":"REACTIVE",
+          "type":"VOTED",
+          "alarms": [
+            {
+              "metric":"system.cpu.util[,idle]",
+              "statistic":"avg",
+              "comparisonOperator":"<=",
+              "threshold":40,
+              "weight":1
+            }
+          ],
+          "actions": [
+            {
+              "type":"SCALE_OUT",
+              "value":"1"
+            }
+          ]
+        },
+        {
+          "name":"scale-in",
+          "threshold":100,
+          "comparisonOperator":">=",
+          "period":30,
+          "cooldown":60,
+          "mode":"REACTIVE",
+          "type":"VOTED",
+          "alarms": [
+            {
+              "metric":"system.cpu.util[,idle]",
+              "statistic":"avg",
+              "comparisonOperator":">=",
+              "threshold":60,
+              "weight":1
+            }
+          ],
+          "actions": [
+            {
+              "type":"SCALE_IN",
+              "value":"1"
+            }
+          ]
+        }
+      ],
+      "type":"client",
+      "endpoint":"generic",
+      "vnfPackageLocation":"https://github.com/openbaton/vnf-scripts.git"
+    },
+    {
+      "name":"sipp-server",
+      "vendor":"FOKUS",
+      "version":"1.0",
+      "lifecycle_event":[
+        {
+          "event":"INSTANTIATE",
+          "lifecycle_events":[
+            "sipp_install.sh",
+            "sipp_server_start.sh"
+          ]
+        }
+      ],
+      "virtual_link":[
+        {
+          "name":"private"
+        }
+      ],
+      "vdu":[
+        {
+          "vm_image":[
+            "ubuntu-14.04"
+          ],
+          "scale_in_out":1,
+          "vnfc":[
+            {
+              "connection_point":[
+                {
+                  "floatingIp":"random",
+                  "virtual_link_reference":"private",
+                  "interfaceId":0
+                }
+              ]
+            }
+          ],
+          "vimInstanceName":[]
+        }
+      ],
+      "deployment_flavour":[
+        {
+          "flavour_key":"m1.small"
+        }
+      ],
+      "type":"server",
+      "endpoint":"generic",
+      "vnfPackageLocation":"https://github.com/openbaton/vnf-scripts.git"
+    }
+  ],
+  "vnf_dependency":[
+    {
+      "source":{
+        "name":"sipp-server"
+      },
+      "target":{
+        "name":"sipp-client"
+      },
+      "parameters":[
+        "private"
+      ]
+    }
+  ]
+}
\ No newline at end of file
diff --git a/docs/release/userguide/descriptors/pop.json b/docs/release/userguide/descriptors/pop.json
new file mode 100644
index 0000000..325d334
--- /dev/null
+++ b/docs/release/userguide/descriptors/pop.json
@@ -0,0 +1,17 @@
+{
+  "name":"opnfv-pop",
+  "authUrl":"http://192.168.145.50:5000/v3",
+  "tenant":"your-tenant-id",
+  "username":"admin",
+  "password":"password",
+  "keyPair":"your-keypair-name",
+  "securityGroups": [
+    "default"
+  ],
+  "type":"openstack",
+  "location":{
+    "name":"Berlin",
+    "latitude":"52.525876",
+    "longitude":"13.314400"
+  }
+}
\ No newline at end of file
diff --git a/docs/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst
index 28fd9bc..76c7fcd 100644
--- a/docs/release/userguide/feature.userguide.rst
+++ b/docs/release/userguide/feature.userguide.rst
@@ -2,22 +2,101 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. (c) Fraunhofer FOKUS
 
+Orchestra User Guide
+====================
+
 .. contents::
    :depth: 3
    :local:
 
 Orchestra description
-=====================
-.. Describe the specific features and how it is realised in the scenario in a brief manner
-.. to ensure the user understand the context for the user guide instructions to follow.
+---------------------
+
+The OPNFV Orchestra project integrates the upstream open source Open Baton project within OPNFV.
+Open Baton is the result of an agile design process having as major objective the development
+of an extensible and customizable framework capable of orchestrating network services across heterogeneous NFV Infrastructures.
+
+The main objective is to allow OPNFV users to get an Open Baton environment up and running using OPNFV installers.
+Furthermore, the Orchestra team collaborates with testing projects in order
+to include some scenarios for validating the actual integration between the
+MANO stack provided by Open Baton and the OPNFV platform.
+
 
 Orchestra capabilities and usage
-================================
-.. Describe the specific capabilities and usage for <XYZ> feature.
-.. Provide enough information that a user will be able to operate the feature on a deployed scenario.
+--------------------------------
+
+:numref:`opnfv-orchestra` below shows the Open Baton architecture integrating with the OPNFV platform.
+
+.. figure:: images/opnfv-orchestra.png
+   :name: opnfv-orchestra
+   :width: 100%
+
+
+Basically Open Baton manages a multi-site NFVI supporting heterogeneous virtualization and cloud technologies.
+   Although OpenStack is the major supported VIM, it provides a driver mechanism for supporting additional VIM types.
+
+
+Orchestra usage guidelines and example
+--------------------------------------
+Considering that there are no major differences between the Open Baton installed within
+OPNFV platform and the upstream one, feel free to follow the upstram documentation provided
+by the Open Baton project to learn more advanced use cases: http://openbaton.github.io/documentation/
+
+Here, it is provided a small example to get started immediately. Depending on whether you have installed Orchestra yourself,
+or using the JOID installer, you should retrieve the IP assigned to the Orchestra (host) where Open Baton has been installed.
+
+The Open Baton dashboard is available on port 8080 (typically SSL is disabled within OPNFV installations): http://your-ip-here:8080
+
+When accessing the dashboard, you will be prompted for a username and password.
+The first access can only be done with the super user ("admin") created during the installation process (by default the password is "openbaton").
+Please refer to the following documentation for learning how to use the Open Baton dashboard.
+In addition, there is also a python CLI available which provides the same functions as the dashboard.
+For simplicity, in this guide it is covered the usage of the dashboard only.
+
+In order to use Open Baton for launching your own Network Service, assuming that
+you have all the different components up and running, you will need to follow these steps:
+
+* Register OPNFV as the Point of Presence (PoP)
+* On board the SIPP client/server Network Service Descriptor (NSD)
+* Launch the Network Service Record using the NSD created in the previous step
+
+Register OPNFV as the Point of Presence
++++++++++++++++++++++++++++++++++++++++
+
+In order to make use of your PoP you need to create a JSON file (see :download:`this example <descriptors/pop.json>`), and
+you need to upload the JSON file to the NFVO. Please make sure you modify information about networks, images, and flavours inside
+the NSD in order to get it working on your local setup.
+
+You can use the dashboard available at http://your-ip-here:8080 for this purpose.
+Under the menu Manage PoPs you can see the PoP instances.
+Click on the Register VIM button and upload your JSON file (from the File input section).
+
+Once the VIM instance is registered, it will appear on the list of available PoPs,
+filled with the information regarding the available images, networks and flavors.
+At this point, you are ready to use the OPNFV PoP in any NSDs and VNFDs.
+
+On board the SIPP client/server Network Service Descriptor (NSD)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Download the SIPp NSD using floating IPs (see :download:`this example <descriptors/nsd.json>`),
+and upload it in the catalogue using the dashboard.
+
+For uploading the NSD using the Dashboard go to Catalogue -> NS Descriptors and
+choose the NSD of your choice by clicking on Upload NSD and selecting the Descriptor's json file.
+
+
+Launch the Network Service Record using the NSD created in the previous step
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+As soon as you onboarded the NSD in the NFVO you can deploy this NSD by using the dashboard.
+You need to go to the GUI again and navigate to Catalogue -> NS Descriptors.
+Open the drop down menu by clicking on Action. Afterwards you need to press the Launch button and a
+window with launching options will appear. Just click on Launch again in order to start the deployment of this NSD.
+
+This will create a Network Service Record (NSR) and actually launch the Virtual Machines on OpenStack.
 
-Feature and API usage guidelines and example
-============================================
-.. Describe with examples how to use specific features, provide API examples and details required to
-.. operate the feature on the platform.
+Check the status of your Network Service Record
++++++++++++++++++++++++++++++++++++++++++++++++
 
+If you go to Orchestrate NS -> NS Records in the menu on the left side,
+you can follow the deployment process and check the current status of the created NSR.
diff --git a/docs/release/userguide/images/opnfv-orchestra.png b/docs/release/userguide/images/opnfv-orchestra.png
new file mode 100644
index 0000000..1a01d62
--- /dev/null
+++ b/docs/release/userguide/images/opnfv-orchestra.png