Kevin L, Guides for Brahmaputra.

Change-Id: I97cf9e3cf38d59ccb40e0e25bed9a7f8caf9346c

3 files changed, 352 insertions, 28 deletions

diff --git a/docs/LSOAPI_Configuration_Guide.rst b/docs/LSOAPI_Configuration_Guide.rst
new file mode 100755
index 0000000..bff5f20
--- /dev/null
+++ b/docs/LSOAPI_Configuration_Guide.rst
@@ -0,0 +1,159 @@
+======================================================

+Connectivity Services LSO (LSOAPI) Configuration Guide

+======================================================

+

+..toctree::

+	:caption: Table of Contents

+	:numbered:

+	:maxdepth:  3

+

+Configuration Guide

+-----------------------------

+Installation and configuration information for Connectivity Services LSO APIs 

+and their implementations for Brahmaputra is provided in this file, which is 

+the LSOAPI_Configuration_Guide.rst file in the docs folder in the LSOAPI project 

+branch of the Brahmaputra Git repository. The LSOAPI project configuration guide

+is a reproduction of the README.MD file in the root lsoapi folder.

+

+

+Virtualized Business CPE Services Demo

+--------------------------------------

+The Connectivity Services LSO APIs and their implementations are part of a 

+proof-of-concept demonstration for the provisioning of Ethernet Private Line

+(EPL) service using OpenDaylight as the SDN controller. The PoC demo, referred 

+to as the Virtualized Business CPE (VCPE) demo, is installed and configured as

+described below.

+

+* There are 3 service layers in the VCPE demo, each runs independently

+    - Ethernet Services Manager API (svcmgr)

+    - Ethernet Virtual Connection Manager API (evcmgr)

+    - Class of Service Manager API (cosmgr)

+* The build creates war files for each that are deployable on tomcat

+* The code is housed in the LSOAPI project gerrit repository: 

+    https://gerrit.opnfv.org/gerrit/lsoapi 

+* All development and testing to date have been on OSX

+

+Environment Requirements:

+^^^^^^^^^^^^^^^^^^^^^^^^^^

+* JDK for Java 7

+* Tomcat 8

+* Maven 3.3

+

+If you need help with environement set-up instructions, see "Environment Set Up"

+notes at the bottom of this document

+

+Building and Deploying Connectivity Services LSO API Implementations

+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

+Assumptions

+*  You have an account on the LSOAPI gerrit server

+*  Your environment has been completely set up as described at the bottom of 

+   this document

+

+    $ git clone ssh://<your opnfv id>@gerrit.opnfv.org:29418/lsoapi 

+    $ cd lsoapi

+    $ chmod +x ./deploy.sh

+    $ ./deploy.sh

+

+* This will build cosmgr.war, evcmgr.war, and svcmgr.war, copy them to your 

+  tomcat webapps directory, and start tomcat

+* If you prefer to set up manually you can follow the following steps

+    $ cd lsoapi

+    $ mvn clean install

+    $ cp ./cos/cosmgr/target/cosmgr.war /Library/Tomcat/webapps/.

+    $ cp ./evc/evcmgr/target/evcmgr.war /Library/Tomcat/webapps/.

+    $ cp ./svc/svcmgr/target/svcmgr.war /Library/Tomcat/webapps/.

+    $ /Library/Tomcat/bin/startup.sh

+

+* The 3 service managers are now running, and will expect/send REST calls 

+  on port 9090

+

+Running the OpenDaylight UNI Manager Emulator

+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

+* The Connectivity Services LSO APIs implementations are designed to call

+  the OpenDaylight UNI Manager plug-in.

+* If you would like to validate the LSOAPI implementation without running the 

+  ODL UNI Manager plug-in, you can do so by running the ODL UNIMgr emulator.

+    - This is a nodejs app that is listening for ODL specific REST calls, and 

+      when recieved, it prints the deatils of the call to the console

+* In order to run the unimgr emulator, you will need to install nodejs and npm.  

+  See "Install node/npm" in the "Environment Set Up" section at the bottom of 

+  this document for more details.

+* Before running the emulator, make sure that the ODL plugin is not running (or

+  you will likely get a port conflict on 8181)

+* Build the runtime environement, and Start the emulator as follows:

+

+    $ cd lsoapi/uni/unimgr

+    $ npm install (if node_modules does not exist)

+    $ node uniMgrEmu.js

+

+* Any REST calls targted to ODL will now be responded to by the ODL emulator,  

+  and logged to the console in which the emulator was started

+

+Environment Set Up

+------------------------

+

+Install JDK

+^^^^^^^^^^^^^^

+**OSX:**

+* Because OpenDaylight requires Java 7, all md-proto development has been 

+  against Java 7, so that all components (ODL based, and non ODL based) will be 

+  able to run on the same machine if needed

+* The md-proto development has been against JDK version 79

+    - Download installation package from here:

+        http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html

+* Tomcat (and other applications) will require a JAVA_HOME environment variable.  

+  A convenient way to make sure that it is created correctly is to add the 

+  following to your .bashrc

+    - export JAVA_HOME=$(/usr/libexec/java_home)

+

+Install Tomcat

+^^^^^^^^^^^^^^^^^^

+**OSX:**

+* We are using Tomcat 8, which is the latest version that support Java7

+* Download tar.gz installation package from here

+    - https://tomcat.apache.org/download-80.cgi

+    - note: md-proto dev was against v 8.022

+

+* Assuming the tar.gz file is in your ~/Downloads folder:

+

+    $ sudo mkdir -p /usr/local (if /usr/local does not already)

+    $ cd /usr/local

+    $ sudo tar -xvf ~/Downloads/apache-tomcat-8.0.22.tar.gz (or other version)

+

+* For convenience, and to make it simpler to replace this with newer versions 

+ you can create a link /Library/Tomcat and point to the version specific tomcat 

+ directory (the instructions below assume, and the deployment script assume 

+ you have done so)

+

+    $ sudo rm -f /Library/Tomcat (if the link already exists)

+    $ sudo ln -s /usr/local/apache-tomcat-8.0.22 /Library/Tomcat

+    $ sudo chown -R -H <your_username> /Library/Tomcat

+    $ sudo chmod +x /Library/Tomcat/bin/*.sh

+

+* All of the vcpe services sent to  9090, so make sure that your 

+  /Library/Tomcat/conf/server.xml file is configured to have tomcat listen 

+  on 9090.

+

+    <Connector port="9090" protocol="HTTP/1.1"

+               connectionTimeout="20000"

+               redirectPort="8443" />

+

+Install Maven

+^^^^^^^^^^^^^^^^^^

+**OSX:**

+* Maven can be installed on OSX using brew

+    - brew is a package manager for OSX

+    - if you don't have brew installed, do so as described here

+  http://coolestguidesontheplanet.com/installing-homebrew-os-x-yosemite-10-10-package-manager-unix-apps/

+

+* Now, install maven:

+

+    $ brew install maven

+

+

+Install node/npm

+^^^^^^^^^^^^^^^^^^^^^

+**OSX:**

+* If you plan on running the UNI ODL emluator you will need to install node/npm

+* Download and execute the Nodejs Mac OS X Installer (.pkg) from

+    https://nodejs.org/download/

diff --git a/docs/LSOAPI_User_Guide.rst b/docs/LSOAPI_User_Guide.rst
new file mode 100755
index 0000000..50f2dc5
--- /dev/null
+++ b/docs/LSOAPI_User_Guide.rst
@@ -0,0 +1,162 @@
+

+=============================================

+Connectivity Services LSO (LSOAPI) User Guide

+=============================================

+..toctree::

+	:caption: Table of Contents

+	:numbered:

+	:maxdepth:  3

+

+API Configuration Information

+-----------------------------

+Installation and configuration information for Connectivity Services LSO APIs 

+and their implementations for Brahmaputra is provided in the 

+LSOAPI_Configuration_Guide.rst file in the docs folder in the LSOAPI 

+project branch of the Brahmaputra Git repository.

+

+API Capabilities and Uses

+-------------------------

+Connectivity Services LSO APIs (short name LSOAPI) provide REST services for 

+development of northbound  Business Services applications. The APIs provide a 

+payload of attributes defined in Metro Ethernet Forum (MEF) Carrier Ethernet 

+services applications and expose capabilities of software defined networking 

+(SDN) controller functions allowing applications to configure and activate 

+network elements to provide Carrier Ethernet services. LSOAPI uses JSON data 

+interchange format to exchange the attributes. Carrier Ethernet services 

+defined by MEF include ELine point-to-point service, E-Tree point-to-multipoint 

+service and E-LAN multipoint-to-multipoint service.

+

+The APIs receive from a northbound application a request for service, 

+identification information for service endpoints and service attributes.  

+API implementations can then use the information to make subsequent calls to 

+lower layers and take other action including storing the attributes.

+

+For the initial phase of the LSOAPI project included in the OPNFV Brahmaputra 

+release, implementations of the APIs were developed to validate the APIs and 

+to demonstrate ‘proof-of-concept’ functionality. The implementations, driven by 

+a simple Web UI developed for the purpose, use the REST interface of an SDN 

+controller to initiate the creation of a GRE tunnel between the endpoints, 

+emulating a simple ELine service. API implementation and Web UI code is 

+provided in the LSOAPI project branch of the Brahmaputra Git repository.

+

+The initial version of LSOAPI included in OPNFV Brahmaputra release is limited 

+in scope in several ways in order to enable a relatively quick proof-of-concept:

+

+- Only Ethernet Private Line (EPL) sub-type of ELine point-to-point service is 

+  implemented

+- The API implementation actually uses only a subset of the full set of EPL 

+  parameters

+- Implementation of EPL service consists of creation of a GRE tunnel between 

+  two instances of Open vSwitch without class-of-service or bandwidth profile 

+  features. 

+- The implementation acts on two endpoints only. It does not configure network 

+  elements between the endpoints.

+- The APIs use REST services provided by an OpenDaylight plug-in only. The 

+  implementation does not use services of any other SDN controller.

+  

+ The initial phase of the LSOAPI project developed three APIs: Ethernet Services

+ Manager (ESM), Ethernet Virtual Connection (EVC) Manager, and Class of Service 

+ (CoS) Manager.  Description of each API follows. The APIs are also documented 

+ in RESTful API Modeling Language (RAML). The file, lsoapi-rest.raml, is 

+ provided in the api folder in the LSOAPI project branch of the Brahmaputra Git 

+ repository. HTML representation of the APIs as described in the RAML file is 

+ linked from the `LSOAPI project documentation page 

+ <https://wiki.opnfv.org/lsoapi/documents/>`_. Attributes passed for each 

+ operation are listed in the RAML documentation.

+ 

+ The Connectivity Services LSO project intends to evolve and expand the APIs to 

+ complete the objective of aligning the APIs with MEF specifications. The 

+ project will not necessarily further develop implementations for each of the 

+ APIs as they evolve.

+ 

+ Ethernet Services Manager (ESM) API

+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

+ The ESM API enables Create, Read, Update and Delete (CRUD) lifecycle management

+ for Carrier Ethernet services as defined by Metro Ethernet Forum (MEF). The 

+ initial use case implemented for Brahmaputra release is Ethernet Private Line 

+(EPL) service.

+

+The ESM API Create operation (POST) takes input from its northbound interface 

+for a set of attributes and returns an HTTP Status Code. The current ESM API 

+implementation obtains Class of Service ID from the Class of Service Manager API

+implementation and uses the services of the Ethernet Virtual Connection (EVC) 

+Manager API. The ESM API implementation stores attributes it receives and passes 

+some of them to the EVC Manager API.

+

+The ESM Read operation (GET) takes input from its northbound interface for a 

+single EPL ID or a list of EPL IDs and returns a set of attributes for each EPL 

+ID provided.

+

+The ESM API Update operation (PUT) takes input from its northbound interface for

+each of a set of attributes and obtains Class of Service ID from the Class of 

+Service Manager API implementation. The current ESM API Update implementation 

+stores each attribute and passes each one to the EVC Manager API.

+

+The ESM API Delete operation (DELETE) takes input from its northbound interface 

+for the EPL ID and returns an HTTP status code. The current ESM API 

+implementation initiates deletion of an EPL by calling the EVC API using the 

+DELETE operation.

+Default values for Ethernet Services Manager attributes are defined in the 

+config.json file. Config.json is available in the demo-ui/app folder in the 

+LSOAPI project branch of the Git repository.

+

+Ethernet Virtual Connection (EVC) Manager API

+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

+The EVC Manager API enables Create, Read, Update and Delete (CRUD) lifecycle 

+management for the Ethernet Virtual Connection associated with the EPL service 

+as defined by Metro Ethernet Forum (MEF) specifications.

+

+The EVC Manager API Create (POST) operation takes input from its northbound 

+interface for a set of attributes and returns an HTTP status code. The current 

+EVC Manager API implementation obtains Class of Service ID from the Class of 

+Service Manager API implementation and uses services of the UNI Manager plug in 

+of OpenDaylight SDN Controller to configure two instances of Open vSwitch and 

+create a GRE tunnel between them. The current EVC Manager API implementation 

+stores all attributes and passes some to the UNI Manager northbound REST 

+interface.

+

+The EVC Manager API Read (GET) operation takes input from its northbound 

+interface for a single EVC ID or list of EVC IDs and returns an HTTP status code 

+and a list of attributes each EVC ID provided.

+

+The EVC Manager Update (PUT) operation takes input from its northbound interface 

+for a set of attributes and returns an HTTP status code. The current EVC Manager 

+API implementation obtains Class of Service ID from the Class of Service Manager 

+API implementation. The EVC Manager implementation passes all parameters to the 

+UNI Manager REST interface for the Update operation.

+

+The EVC Manager Delete (DELETE) operation takes input from its northbound 

+interface for an EVC ID and returns an HTTP status code. The current EVC Manager

+API implementation initiates deletion of the GRE tunnel emulating the EPL by 

+calling the UNI Manager northbound REST interface using the DELETE operation.

+

+Class of Service (CoS) Manager API

+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

+The CoS Manager API enables Create, Read, Update and Delete (CRUD) lifecycle 

+management for Class of Service associated with the EPL service as defined by 

+Metro Ethernet Forum (MEF) specifications. The CoS parameters define how network 

+elements are to handle traffic passed between them including transmission rate,

+availability, frame delay, frame loss and jitter. The current LSOAPI CoS 

+implementation allows the user to define values for the set of attributes and 

+assign a name (identifier) to each unique set of values, stores the CoS sets, 

+and passes the CoS name to the ESM API implementation and EVC Manager API 

+implementation as requested.

+

+The CoS Manager API Create (POST) operation takes input from its northbound 

+interface for a set of attributes and returns an HTTP status code. 

+

+The CoS Manager API Read (GET) operation takes input from its northbound 

+interface for a specific CoS ID or a list of CoS IDs and returns HTTP status 

+code and attribute values associated with each provided CoS ID.

+

+The CoS Manager API Update (PUT) operation takes input from its northbound 

+interface for a specific CoS ID and attributes associated with that ID. The CoS 

+API implementation can update its data store and other API implementations with 

+changes made to the attributes. The CoS Manager API PUT operation returns an 

+HTTP status code.

+

+The CoS Manager API Delete (DELETE) operation takes input from its northbound 

+interface for a specific CoS ID and returns an HTTP status code. The current CoS

+Manager API implementation deletes all attributes and the CoS ID when it 

+receives a request with the Delete operation.

+

diff --git a/docs/index.rst b/docs/index.rst
index 1b84735..720d986 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,28 +1,31 @@
-.. OPNFV Release Engineering documentation, created by
-   sphinx-quickstart on Tue Jun  9 19:12:31 2015.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-.. image:: opnfv-logo.png
-  :height: 40
-  :width: 200
-  :alt: OPNFV
-  :align: left
-
-Connectivity Services LSO
-=========================
-
-Contents:
-
-.. toctree::
-   :maxdepth: 4
-   :titlesonly:
-
-   dev-notes.rst
-   state-of-code.rst
-
-* :ref:`search`
-
-Revision: _sha1_
-
-Build date: |today|
+.. OPNFV Release Engineering documentation, created by

+   sphinx-quickstart on Tue Jun  9 19:12:31 2015.

+   You can adapt this file completely to your liking, but it should at least

+   contain the root `toctree` directive.

+

+.. image:: ../etc/opnfv-logo.png

+  :height: 40

+  :width: 200

+  :alt: OPNFV

+  :align: left

+

+Connectivity Services LSO

+===========================

+

+Contents:

+

+.. toctree::

+   :maxdepth: 4

+   :titlesonly:

+

+   LSOAPI_User_Guide.rst

+   LSOAPI_Configuration_Guide.rst

+

+Indices and tables

+==================

+

+* :ref:`search`

+

+Revision: _sha1_

+

+Build date: |today|