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>

7 files changed, 398 insertions, 38 deletions

diff --git a/docs/release/configguide/feature.configuration.rst b/docs/release/configguide/feature.configuration.rst
index 32e20f9..99535f9 100644
--- a/docs/release/configguide/feature.configuration.rst
+++ b/docs/release/configguide/feature.configuration.rst
@@ -1,34 +1,61 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 
-========
-Abstract
-========
-Add a brief introduction to configure OPNFV with this specific feature including
-dependancies on platform components, this description should be at a level that
-will apply to any installer providing the pre-requisite components.
+
+Orchestra Installation
+======================
+Orchestra is the OPNFV name given to the Open Baton integration project. This documentation explains how to install it.
+Please notice that the JOID installer already integrates Orchestra as a scenario. Please refer to the JOID installer in case
+you want to install Orchestra using it.
 
 .. contents::
    :depth: 3
    :local:
 
-Pre-configuration activities
-============================
-Describe specific pre-configuration activities. This should include ensuring the
-right components are installed by the installation tools as required for your
-feature to function.  Refer to the previous installer configuration chapters,
-installations guide and release notes
 
 
 Hardware configuration
-======================
-Describe the hardware configuration needed for this specific feature
+----------------------
+
+No special hardware is needed in order to execute Orchestra. We assume that you are performing
+the installation on top of a clean installation either of Ubuntu 14.04, Ubuntu 16.04 or Debian Jessy.
+In other cases we suggest to install the components one by one.
+You can checkout the bootstrap repository and see the installation procedures which are executed by the bootstrap script.
+
+Orchestra can be installed on any kind of environment (physical hosts, virtual machines, containers, etc.).
+So, you can decide either to install it on top of virtual machine running on the jump host or somewhere else.
+Suggested requirements in terms of CPUs, Memory, and disk space are:
+
+* minimal: > 2GB of RAM, and > 2CPUs, 10GB of disk space
+* suggested: > 8GB of RAM, and > 8CPUs, 10GB of disk space
+
+In general, you may be able to get a working environment also with less perfomant hardware, especially tuning the JVM startup options (i.e -Xms and -Xmx).
+
+Orchestra Bootstrap
+-------------------
+To facilitate the installation procedures we provide a bootstrap script which
+will install the desired components and configure them for running a hello world VNF out of the box.
+To execute the bootstrap procedure you need to have curl installed (see http://curl.haxx.se/).
+This command should work on any Ubuntu system:
+
+.. code-block:: bash
+
+    apt-get install curl
+
+We provide a non-interactive installation using a configuration file.
+Specifically, you need to have the configuration file locally available and to pass it
+to the bootstrap command as a parameter. You can download this example of configuration file,
+modify it accordingly and execute the bootstrap typing the following command:
+
+.. code-block:: bash
+
+    wget http://get.openbaton.org/bootstraps/orchestra/euphrates/bootstrap-config-file # modify any parameters you want
+    sh <(curl -s http://get.openbaton.org/bootstraps/orchestra/euphrates/bootstrap) release --config-file=/home/ubuntu/bootstrap-config-file
+
 
+VERY IMPORTANT NOTE - By default RabbitMQ is installed on the host of the NFVO.
+Be aware of the fact that during the installation you will be prompted for entering the RabbitMQ IP and Port.
+Please make sure that this IP can be reached by external components (VMs, or host where will run other VNFMs) otherwise you will have runtime issues.
+If you are installing Open Baton on a VM running in OpenStack, the best is that you put here the floating IP.
 
-Orchestra configuration
-=====================
-Describe the procedures to configure your feature on the platform in order
-that it is ready to use according to the feature instructions in the platform
-user guide.  Where applicable you should add content in the postinstall.rst
-to validate the feature is configured for use.
-(checking components are installed correctly etc...)
+At this point the NFVO dashboard should be reachable via the following URL http://your-ip-here:8080
diff --git a/docs/release/configguide/index.rst b/docs/release/configguide/index.rst
index 4039341..6b19c9c 100644
--- a/docs/release/configguide/index.rst
+++ b/docs/release/configguide/index.rst
@@ -6,6 +6,6 @@ Orchestra Configuration Guide
 **********************************
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 4
 
    feature.configuration
diff --git a/docs/release/release-notes/orchestra-release.rst b/docs/release/release-notes/orchestra-release.rst
index 7e514d1..1419ff4 100644
--- a/docs/release/release-notes/orchestra-release.rst
+++ b/docs/release/release-notes/orchestra-release.rst
@@ -20,18 +20,41 @@ Version history
 | **Date**   | **Ver.** | **Author**         | **Comment**            |
 |            |          |                    |                        |
 +------------+----------+--------------------+------------------------+
-| 2017-08-25 | 1.0.0    | Giuseppe Carella   | Functest for           |
-|            |          | (Fraunhofer FOKUS) | Euphrates.1.0 release   |
+| 2017-08-25 | 1.0.0    | Giuseppe Carella   | Euphrates.1.0 release  |
+|            |          | (Fraunhofer FOKUS) |                        |
 +------------+----------+--------------------+------------------------+
 
+Important notes
+===============
+
+The OPNFV Orchestra project started with the main objective of integrating
+the Open Baton open source framework with OPNFV. The initial main objective was
+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
+Open Baton project and the OPNFV platform.
+
+
 OPNFV Orchestra Euphrates Release
 =================================
 
-Orchestra enables the integration of the open source Open Baton platform,
-an ETSI NFV MANO reference implementation, with the OPNFV platforms allowing
-specific scenarios and use cases.
+During the Euphrates release, the Orchestra team focused mainly in integrating
+Orchestra with the JOID installer, and in extending the testing scenarios
+developed in the context of the Functest project.
+
+With the JOID installer users can easily get a ready-to-go Open Baton environment
+selecting the 'os-nosdn-openbaton-ha' scenario. After the installation,
+Open Baton release 4 will be available as part of the OPNFV environment. Users can
+refer to the Open Baton documentation in order to get started immediately
+on boarding their VNFs and network services.
+
+Using Functest users can test the integration of the orchestra project with the OPNFV
+platform. In particular, there are two use cases implementing the automated on boarding and
+deployment of a classical IMS network service on top of the OPNFV platform:
 
-Currently Orchestra has been integrated with an installer project (JOID) and a testing framework (Functest).
+* `OpenIMSCore <http://openimscore.org/>`
+* `Clearwater IMS <http://www.projectclearwater.org/>`
 
 
 
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