From b123b74d81d20efbb594db5eb1fb17ed79953c58 Mon Sep 17 00:00:00 2001 From: botte Date: Mon, 30 Nov 2015 14:25:59 -0700 Subject: Kevin L, Guides for Brahmaputra. Change-Id: I97cf9e3cf38d59ccb40e0e25bed9a7f8caf9346c --- docs/LSOAPI_Configuration_Guide.rst | 159 +++++++++++++++++++++++++++++++++++ docs/LSOAPI_User_Guide.rst | 162 ++++++++++++++++++++++++++++++++++++ docs/index.rst | 59 ++++++------- 3 files changed, 352 insertions(+), 28 deletions(-) create mode 100755 docs/LSOAPI_Configuration_Guide.rst create mode 100755 docs/LSOAPI_User_Guide.rst 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://@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 /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. + + + +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 + `_. 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| -- cgit 1.2.3-korg