diff options
| -rwxr-xr-x | docs/LSOAPI_Configuration_Guide.rst | 159 | ||||
| -rwxr-xr-x | docs/LSOAPI_User_Guide.rst | 162 | ||||
| -rw-r--r-- | docs/index.rst | 59 |
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|
|