Beijing RC2 documentation

Change-Id: Ic8b75e4cb33d6c4562cef2f2b9342974bfae03a3
Signed-off-by: fsandoval <frank.sandoval@oamtechnologies.com>
Issue-ID: OPTFRA-41

22 files changed, 242 insertions, 52 deletions

diff --git a/docs/index.rst b/docs/index.rst
index c80d7ad..5431d85 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -2,10 +2,37 @@
 
 Optimization Framework: Homing and Allocation
 =============================================
+Shankaranarayanan Puzhavakath Narayanan
+Apr 30 10:52 PM
+OOF-HAS is an policy-driven placement optimizing service (or homing service) that allows ONAP to 
+deploy services automatically across multiple sites and multiple clouds. 
+It enables placement based on a wide variety of policy constraints including capacity, 
+location, platform capabilities, and other service specific constraints. 
+HAS is a distributed resource broker that enables automated policy-driven optimized placement of 
+services on a global heterogeneous platform using ONAP. Given a set of service components 
+(based on SO decomposition flows) and requirements for placing these components 
+(driven by policies), HAS finds optimal resources (cloud regions or existing service instances) 
+to home these service components such that it meets all the service requirements. 
+HAS is architected as an extensible homing service that can accommodate a growing set of 
+homing objectives, policy constraints, data sources and placement algorithms. It is also 
+service-agnostic by design and can easily onboard new services with minimal effort. 
+Therefore, HAS naturally extends to a general policy-driven optimizing placement platform 
+for wider range of services, e.g., DCAE micro-services, ECOMP control loops, server capacity, etc. 
+Finally, HAS provides an traceable mechanism for what-if analysis which is critical for ease of 
+understanding a homing recommendation and resolving infeasibility scenarios.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+
+   ./sections/architecture.rst
+   ./sections/homingspecification.rst
+   ./sections/offeredapis.rst
+   ./sections/consumedapis.rst
+   ./sections/delivery.rst
+   ./sections/logging.rst
+   ./sections/installation.rst
+   ./sections/configuration.rst
+   ./sections/administration.rst
+   ./sections/humaninterfaces.rst
+   ./sections/release-notes.rst
 
-   api
-   homingspecification
-   release-notes/index
diff --git a/docs/release-notes/deprecation-notes.rst b/docs/release-notes/deprecation-notes.rst
deleted file mode 100644
index e954e87..0000000
--- a/docs/release-notes/deprecation-notes.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-
-Deprecation Notes
------------------
-
diff --git a/docs/release-notes/index.rst b/docs/release-notes/index.rst
deleted file mode 100644
index 2d4b19d..0000000
--- a/docs/release-notes/index.rst
+++ /dev/null
@@ -1,15 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-
-Release notes
--------------
-
-.. toctree::
-    :maxdepth: 2
-
-    new-features.rst
-    bug-fixes.rst
-    known-issues.rst
-    security-issues.rst
-    upgrade-notes.rst
-    deprecation-notes.rst
-    other.rst
diff --git a/docs/release-notes/new-features.rst b/docs/release-notes/new-features.rst
deleted file mode 100644
index ab86bb9..0000000
--- a/docs/release-notes/new-features.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-
-New Features
-------------
-
diff --git a/docs/release-notes/other.rst b/docs/release-notes/other.rst
deleted file mode 100644
index 2ce683b..0000000
--- a/docs/release-notes/other.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-
-Other
------
-
diff --git a/docs/release-notes/security-issues.rst b/docs/release-notes/security-issues.rst
deleted file mode 100644
index 96e1fe9..0000000
--- a/docs/release-notes/security-issues.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-
-Security Issues
----------------
-
diff --git a/docs/release-notes/upgrade-notes.rst b/docs/release-notes/upgrade-notes.rst
deleted file mode 100644
index f31c74a..0000000
--- a/docs/release-notes/upgrade-notes.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-
-Upgrade Notes
--------------
-
diff --git a/docs/release-notes/bug-fixes.rst b/docs/sections/administration.rst
index ee4ff9f..0650561 100644
--- a/docs/release-notes/bug-fixes.rst
+++ b/docs/sections/administration.rst
@@ -1,5 +1,6 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 
-Bug Fixes
----------
+Administration
+=============================================
 
+    Administration - TBD
\ No newline at end of file
diff --git a/docs/sections/architecture.rst b/docs/sections/architecture.rst
new file mode 100644
index 0000000..f8ecbcf
--- /dev/null
+++ b/docs/sections/architecture.rst
@@ -0,0 +1,55 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Architecture
+=============================================
+
+Introduction
+------------------
+OOF-HAS is an policy-driven placement optimizing service (or homing service) that allows ONAP to deploy services 
+automatically across multiple sites and multiple clouds. It enables placement based on a wide variety of policy 
+constraints including capacity, location, platform capabilities, and other service specific constraints. 
+
+HAS is a distributed resource broker that enables automated policy-driven optimized placement of services on a 
+global heterogeneous platform using ONAP. Given a set of service components (based on SO decomposition flows) 
+and requirements for placing these components (driven by policies), HAS finds optimal resources (cloud regions 
+or existing service instances) to home these service components such that it meets all the service requirements. 
+HAS is architected as an extensible homing service that can accommodate a growing set of homing objectives, policy 
+constraints, data sources and placement algorithms. It is also service-agnostic by design and can easily onboard 
+new services with minimal effort. Therefore, HAS naturally extends to a general policy-driven optimizing placement 
+platform for wider range of services, e.g., DCAE micro-services, ECOMP control loops, server capacity, etc. 
+Finally, HAS provides an traceable mechanism for what-if analysis which is critical for ease of understanding a 
+homing recommendation and resolving infeasibility scenarios.
+
+HAS in Service Instantiation workflows
+--------------------------------------------
+Below is an illustration of HAS interactions with other ONAP components to enable Policy driven homing. The homing 
+policy constraints have been expanded (and categorized) to highlight the range of constraints that could be provided
+to HAS for determining the homing solution. The figure also shows how HAS uses a plugin-based approach to allow an 
+extensible set of constraints and data models. 
+
+.. image:: ./diagrams/HAS_PolicyDrivenHoming.png
+
+More information on how homing constraints are specified can be found at OOF-HAS Homing Specification Guide, and a 
+sample homing template has been drawn up for residential vCPE Homing Use Case.  
+
+HAS Architecture (R2)
+----------------------
+
+.. image:: ./diagrams/HAS_SeedCode_Architecture_R2.jpg
+
+Lifecycle of a Homing request in HAS
+--------------------------------------------
+
+.. image:: ./diagrams/PlanLifecycle.jpg
+
+Use cases
+----------------------
+Residential vCPE: https://wiki.onap.org/display/DW/vCPE+Homing+Use+Case
+
+5G RAN: https://wiki.onap.org/display/DW/5G+RAN+use+case
+
+
+A sample heuristic greedy algorithm of HAS (using a vCPE as example)
+------------------------------------------------------------------------
+
+.. image:: ./diagrams/HASHeuristicGreedyAlgorithm.jpg
diff --git a/docs/sections/configuration.rst b/docs/sections/configuration.rst
new file mode 100644
index 0000000..5e55a89
--- /dev/null
+++ b/docs/sections/configuration.rst
@@ -0,0 +1,36 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Configuration
+=============================================
+
+For the configuration inside the config-file, please refer to the README inside Gerrit  
+
+It is worth noting that A&AI and MUSIC may be needed to run HAS project. Please refer to their setup page for installation.
+
+For MUSIC version 2.4.x and newer refer Setup for Developing MUSIC
+
+Running the example
+-----------------------
+To start the process, execute the following commands:
+    
+    $ conductor-api --port=8091 -- --config-file={conductor_conf_file_location} 
+    
+    $ conductor-controller --config-file={conductor_conf_file_location}
+    
+    $ conductor-solver --config-file={conductor_conf_file_location}
+    
+    $ conductor-reservation --config-file={conductor_conf_file_location}
+    
+    $ conductor-data --config-file={conductor_conf_file_location}
+
+Committing the Code
+-----------------------    
+    $ git commit -am "Initial proj struct"
+    
+    $ git review -s
+    
+    $ git commit -as --amend
+
+# scroll down 2 lines (above your Change-ID) insert "Issue-ID: {issue_id}"
+    
+    $ git review
diff --git a/docs/sections/consumedapis.rst b/docs/sections/consumedapis.rst
new file mode 100644
index 0000000..954a138
--- /dev/null
+++ b/docs/sections/consumedapis.rst
@@ -0,0 +1,18 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Consumed APIs
+=============================================
+The following are the dependencies for the project based on the scope for the Beijing Release. 
+The required dependencies have been identified based on the current homing requirements for the vCPE use case, 
+and the potential dependencies are tentative dependencies that may exist based on how the information required 
+for homing (e.g., Hardware Platform Enablement, VIM attributes) is available. 
+
+
+AAI
+--------------------------------------------
+See documentation for Active and Available Inventory component
+
+
+Multi-Cloud
+--------------------------------------------
+See documentation for Multi-Cloud component
\ No newline at end of file
diff --git a/docs/release-notes/known-issues.rst b/docs/sections/delivery.rst
index 01c93d1..bfe8480 100644
--- a/docs/release-notes/known-issues.rst
+++ b/docs/sections/delivery.rst
@@ -1,5 +1,6 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 
-Known Issues
-------------
+Delivery
+=============================================
 
+    Delivery description TBD
\ No newline at end of file
diff --git a/docs/sections/diagrams/HASHeuristicGreedyAlgorithm.jpg b/docs/sections/diagrams/HASHeuristicGreedyAlgorithm.jpg
new file mode 100644
index 0000000..c412ad6
--- /dev/null
+++ b/docs/sections/diagrams/HASHeuristicGreedyAlgorithm.jpg
diff --git a/docs/sections/diagrams/HAS_PolicyDrivenHoming.png b/docs/sections/diagrams/HAS_PolicyDrivenHoming.png
new file mode 100644
index 0000000..19b2d5c
--- /dev/null
+++ b/docs/sections/diagrams/HAS_PolicyDrivenHoming.png
diff --git a/docs/sections/diagrams/HAS_SeedCode_Architecture_R2.jpg b/docs/sections/diagrams/HAS_SeedCode_Architecture_R2.jpg
new file mode 100644
index 0000000..1d247ca
--- /dev/null
+++ b/docs/sections/diagrams/HAS_SeedCode_Architecture_R2.jpg
diff --git a/docs/sections/diagrams/PlanLifecycle.jpg b/docs/sections/diagrams/PlanLifecycle.jpg
new file mode 100644
index 0000000..8d5cf2f
--- /dev/null
+++ b/docs/sections/diagrams/PlanLifecycle.jpg
diff --git a/docs/homingspecification.rst b/docs/sections/homingspecification.rst
index 9e10730..9e10730 100644
--- a/docs/homingspecification.rst
+++ b/docs/sections/homingspecification.rst
diff --git a/docs/sections/humaninterfaces.rst b/docs/sections/humaninterfaces.rst
new file mode 100644
index 0000000..5b8c3e7
--- /dev/null
+++ b/docs/sections/humaninterfaces.rst
@@ -0,0 +1,6 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Human Interfaces
+=============================================
+
+    OOF HAS does not expose a human interface
\ No newline at end of file
diff --git a/docs/sections/installation.rst b/docs/sections/installation.rst
new file mode 100644
index 0000000..65029c6
--- /dev/null
+++ b/docs/sections/installation.rst
@@ -0,0 +1,22 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Installation
+=============================================
+
+Installing from the Source Code
+------------------------------------
+Get HAS seed code from the Linux Foundation Projects page
+    $ git clone https://gerrit.onap.org/r/optf/has
+
+Use python virtual environment (https://virtualenv.pypa.io/en/stable/) to create and manage libraries and dependencies for HAS project.
+    $ virtualenv {virtual_environment_location}
+    
+    $ source {virtual_environemtn_location}/bin/activate
+
+Inside of /has/conductor folder, run the following commands:
+    $ python setup.py install
+    
+    $ pip install -e .
+
+In {virtual_environment_location}/bin folder, you should see the five components of HAS/Conductor project
+conductor-api,conductor-controller, conductor-solver, conductor-reservation, conductor-data
diff --git a/docs/sections/logging.rst b/docs/sections/logging.rst
new file mode 100644
index 0000000..86b63f9
--- /dev/null
+++ b/docs/sections/logging.rst
@@ -0,0 +1,16 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Logging
+=============================================
+
+HAS uses a single logger, oslo, across all the components. The logging format is compliant with the EELF recommendations, 
+including having the following logs:
+error, audit, metric, application.
+
+The log statements follow the following format (values default to preset values when missing):
+
+Timestamp|RequestId|ServiceInstanceId|ThreadId|Virtual Server Name|ServiceName|InstanceUUID|Log Level|Alarm Severity Level|Server IP Address|HOST NAME|Remote IP Address|Class name|Timer|Detailed Message
+
+The logger util module can be found at: 
+
+<>/has/conductor/conductor/common/utils/conductor_logging_util.py
\ No newline at end of file
diff --git a/docs/api.rst b/docs/sections/offeredapis.rst
index 33e0a68..ed215d3 100644
--- a/docs/api.rst
+++ b/docs/sections/offeredapis.rst
@@ -1,8 +1,13 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Offered APIs
+=============================================
+
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. Copyright (C) 2017-2018 AT&T Intellectual Property. All rights reserved.
 
 Homing API v1
-=============
+------------------
 
 *Updated: 28 Feb 2018*
 
@@ -10,7 +15,7 @@ This document describes the Homing API, provided by the Homing and Allocation se
 It is a work in progress and subject to frequent revision.
 
 General API Information
-=======================
+------------------
 
 Authenticated calls that target a known URI but that use an HTTP method
 the implementation does not support return a 405 Method Not Allowed
@@ -20,7 +25,7 @@ HTTP methods. See the API Errors section for more information about the
 error response structure.
 
 API versions
-============
+------------------
 
 List all Homing API versions
 ----------------------------
@@ -61,7 +66,7 @@ List all Homing API versions
 This operation does not accept a request body.
 
 Plans
-=====
+------------------
 
 Create a plan
 -------------
diff --git a/docs/sections/release-notes.rst b/docs/sections/release-notes.rst
new file mode 100644
index 0000000..32ea3a0
--- /dev/null
+++ b/docs/sections/release-notes.rst
@@ -0,0 +1,43 @@
+..
+ This work is licensed under a Creative Commons Attribution 4.0
+ International License.
+
+=============
+Release Notes
+=============
+
+Release Date
+------------
+2018-05-24
+
+
+New Features
+------------
+* Baseline HAS functionality
+* Integration with OOF OSDF, AAI, and Multi-Cloud
+* Platform Maturity Level 1
+* ~50%+ unit test coverage
+
+Bug Fixes
+---------
+None  
+
+Known Issues
+------------
+None
+
+Security Issues
+---------------
+None
+
+Upgrade Notes
+-------------
+None
+
+Deprecation Notes
+-----------------
+None
+
+Other
+-----
+None
\ No newline at end of file