Populate documentation for MSB

Issue-Id: MSB-80, MSB-81, MSB-82
Change-Id: I97e1eed801c44b3c6906745f4e49c2579b549ace
Signed-off-by: HuabingZhao <zhao.huabing@zte.com.cn>

18 files changed, 209 insertions, 10 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 8219c32..453e146 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -5,17 +5,12 @@ MSB(Microservices Bus)
 
 Microservices Bus provide key infrastructure functionalities to support ONAP microservice architecture including service registration/discovery, service gateway, service load balancer and service governance. It's a pluggable architecture so it can be extended with plugins to provide value added services such as centralized authentication for APIs. Microservices Platform also provides a GUI portal for service management.
 
-MSB comprises these modules: 
+This document is aimed to give the users some brief introductions on MSB from different aspects. The users could find useful information, e.g. the architecuture, the APIs and the installation steps, etc. as well as the release notes of MSB in this document.
 
-- MSB
-    - Discovery
-    - API Gateway
-    - MSB SDK
-    - Swagger SDK
 
 .. toctree::
    :maxdepth: 1
    
-   offeredapis.rst
-
+   platform/index.rst
+   release-notes/index.rst
 
diff --git a/docs/platform/administration.rst b/docs/platform/administration.rst
new file mode 100644
index 0000000..5213df7
--- /dev/null
+++ b/docs/platform/administration.rst
@@ -0,0 +1,15 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+
+Administration
+--------------
+
+Processes
+^^^^^^^^^
+* Process 1
+* Process 2
+
+Actions
+^^^^^^^
+* Action X
+* Action Y
diff --git a/docs/platform/architecture.rst b/docs/platform/architecture.rst
new file mode 100644
index 0000000..2fca78b
--- /dev/null
+++ b/docs/platform/architecture.rst
@@ -0,0 +1,32 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+
+Architecture
+------------
+
+Holmes comprises three modules: the rule management module, the engine management module and the data source adapter.
+
+- Holmes
+    - Rule Management Module
+    - Engine Management Module
+    - Data Source Adapter
+	
+ONAP-level Architecture
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Basically, Holmes itself is an independent component in ONAP, which means it could be deployed as an ONAP-level component. In the Amsterdam release, Holmes is more generally a DCAE analytic application. It is deployed by DCAE and run as an analytic application on top of it. Also, it could be considered as a filter of the Policy component because it reduces the number of the input messages of Policy.
+
+.. image:: images/overall-architecture-in-onap.png
+
+Holmes Architecture
+^^^^^^^^^^^^^^^^^^^
+
+Take a deep dive into Holmes, we could see it mainly consists of three modules, which are the rule management module, the engine management module and the data source adapter module respectively. 
+
+The rule management module provides interfaces for the operations (e.g. creating, updating and deleting) on the rules.
+
+The data source adapter consists of subscribers and publishers, which are used to convert the data format into the one that could be digested by Holmes and vice versa. 
+
+The engine management module is the core of Holmes. All the rules are deployed here. When alarms gets into Holmes, they will be pushed into the Drools engine and analyzed by the enabled rules one after another. When processing the alarms, a couple of attributes, such as the alarm name, the occurrence time of the alarm and so on, are utilized. Also, the topological information from A&AI is used in combination of the alarm attributes. After the root cause is identified, it will be converted into a control loop event and published to a specific DMaaP topic which is subscribed to by the Policy component.
+
+.. image:: images/holmes-architecture.png
diff --git a/docs/platform/configuration.rst b/docs/platform/configuration.rst
new file mode 100644
index 0000000..cedb443
--- /dev/null
+++ b/docs/platform/configuration.rst
@@ -0,0 +1,8 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+
+Configuration
+-------------
+
+No machanism for customized configurtions is provided in the Amsterdam release. Such functionalities will be provided in the future if necessary.
+
diff --git a/docs/platform/consumedapis.rst b/docs/platform/consumedapis.rst
new file mode 100644
index 0000000..a5700b2
--- /dev/null
+++ b/docs/platform/consumedapis.rst
@@ -0,0 +1,7 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Consumed APIs
+-------------
+
+In the Amsterdam release, MSB does not consume any APIs provided by other ONAP components.
diff --git a/docs/platform/delivery.rst b/docs/platform/delivery.rst
new file mode 100644
index 0000000..27b3770
--- /dev/null
+++ b/docs/platform/delivery.rst
@@ -0,0 +1,9 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+
+Delivery
+--------
+
+Describe how functions are packaged into run-time components. For some components a block diagram may be useful.
+
+**TO BE DONE**
\ No newline at end of file
diff --git a/docs/platform/human-interfaces.rst b/docs/platform/human-interfaces.rst
new file mode 100644
index 0000000..e8501d0
--- /dev/null
+++ b/docs/platform/human-interfaces.rst
@@ -0,0 +1,15 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Human Interfaces
+----------------
+Provide info on the targeted user, interface types, ports/protocols to access, etc.
+
+Target Users
+^^^^^^^^^^^^
+
+Interface Type
+^^^^^^^^^^^^^^
+
+Access
+^^^^^^
\ No newline at end of file
diff --git a/docs/platform/images/msb-architecture.PNG b/docs/platform/images/msb-architecture.PNG
new file mode 100644
index 0000000..8485372
--- /dev/null
+++ b/docs/platform/images/msb-architecture.PNG
diff --git a/docs/platform/index.rst b/docs/platform/index.rst
new file mode 100644
index 0000000..82f10d7
--- /dev/null
+++ b/docs/platform/index.rst
@@ -0,0 +1,19 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Platform
+--------
+
+Microservices Bus provide key infrastructure functionalities to support ONAP microservice architecture including service registration/discovery, service gateway, service load balancer and service governance. It's a pluggable architecture so it can be extended with plugins to provide value added services such as centralized authentication for APIs. Microservices Platform also provides a GUI portal for service management.
+
+.. toctree::
+   :maxdepth: 1
+   
+   architecture.rst
+   offeredapis.rst
+   consumedapis.rst
+   delivery.rst
+   log-and-diagnostic-info.rst
+   installation.rst
+   configuration.rst
+   administration.rst
+   human-interfaces.rst
diff --git a/docs/platform/installation.rst b/docs/platform/installation.rst
new file mode 100644
index 0000000..5181980
--- /dev/null
+++ b/docs/platform/installation.rst
@@ -0,0 +1,49 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Installation
+------------
+MSB can run as docker, it's very handy to try it at your laptop. For production, MSB supports to be deployed as a cluster to provide a scalable microservice communication infrastructure with kubernetes.
+ 
+Run MSB on the a single host using host network
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This deployment approach is only for testing. MSB is consist of multiple microservices, for testing, the easiest way is to run them in the same host by using host network.  
+1. Run the Consul dockers.
+sudo docker run -d --net=host --name msb_consul consul 
+
+2. Run the MSB dockers.
+Login the ONAP docker registry first: docker login -u docker -p docker nexus3.onap.org:10001
+
+sudo docker run -d --net=host --name msb_discovery nexus3.onap.org:10001/onap/msb/msb_discovery
+sudo docker run -d --net=host -e "ROUTE_LABELS=visualRange:1" --name msb_internal_apigateway nexus3.onap.org:10001/onap/msb/msb_apigateway
+3. Explore the MSB portal.
+http://127.0.0.1/msb
+
+4. Register your REST service to MSB via curl
+For testing, we can register the services via curl. MSB is working with OOM team to register the services automatically when deploying the ONAP components.
+curl -X POST \
+-H "Content-Type: application/json" \
+-d '{"serviceName": "aai", "version": "v8", "url": "/aai/v8","protocol": "REST", "path": "/aai/v8", "nodes": [ {"ip": "10.74.215.65","port": "8443"}]}' \
+"http://127.0.0.1:10081/api/microservices/v1/services”
+
+5.Access the rest service via api gateway
+curl http://127.0.0.1/api/aai/v8/cloud-infrastructure/cloud-regions
+
+Run MSB using default docker network
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In case that you don't want to use host network to set up the MSB dockers, you need to export the port and specify the environment variables to let msb components know each other.
+1. Run the Consul dockers.
+sudo docker run -d -p 8500:8500  --name msb_consul consul 
+CONSUL_IP=`sudo docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' msb_consul`
+
+2. Run the MSB dockers.
+Login the ONAP docker registry first: docker login -u docker -p docker nexus3.onap.org:10001
+
+sudo docker run -d  -p 10081:10081  -e CONSUL_IP=$CONSUL_IP --name msb_discovery nexus3.onap.org:10001/onap/msb/msb_discovery
+DISCOVERY_IP=`sudo docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' msb_discovery`
+sudo docker run -d -p 80:80 -e CONSUL_IP=$CONSUL_IP -e SDCLIENT_IP=$DISCOVERY_IP -e "ROUTE_LABELS=visualRange:1" --name msb_internal_apigateway nexus3.onap.org:10001/onap/msb/msb_apigateway
+
+Deploy MSB with kubernetes
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+The chart for MSB running in kubernetes cluster is available here: 
+https://gerrit.onap.org/r/gitweb?p=oom.git;a=tree;f=kubernetes/msb;h=17f8fd89791b81f1e981716dcffdb3e2e90299ae;hb=refs/heads/master
diff --git a/docs/platform/log-and-diagnostic-info.rst b/docs/platform/log-and-diagnostic-info.rst
new file mode 100644
index 0000000..4bda4ba
--- /dev/null
+++ b/docs/platform/log-and-diagnostic-info.rst
@@ -0,0 +1,14 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Logging & Diagnostic Information
+---------------------------------
+
+Description of how to interact with and diagnose problems with the components as delivered.
+
+Where to Access Information
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+Error / Warning Messages
+^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/docs/offeredapis.rst b/docs/platform/offeredapis.rst
index 3ceed0c..3d77d92 100644
--- a/docs/offeredapis.rst
+++ b/docs/platform/offeredapis.rst
@@ -1,5 +1,6 @@
-MSB APIs
-==================================
+Offered APIs
+------------
+
 The MSB provides the following APIs.
 
 * Service Registration/Unregistration
diff --git a/docs/release-notes/bug-fixes.rst b/docs/release-notes/bug-fixes.rst
new file mode 100644
index 0000000..4dc09fc
--- /dev/null
+++ b/docs/release-notes/bug-fixes.rst
@@ -0,0 +1,4 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Bug Fixes
+---------
diff --git a/docs/release-notes/index.rst b/docs/release-notes/index.rst
new file mode 100644
index 0000000..19f0bff
--- /dev/null
+++ b/docs/release-notes/index.rst
@@ -0,0 +1,15 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Release-notes
+-------------
+
+Microservices Bus provide key infrastructure functionalities to support ONAP microservice architecture including service registration/discovery, service gateway, service load balancer and service governance. It's a pluggable architecture so it can be extended with plugins to provide value added services such as centralized authentication for APIs. Microservices Platform also provides a GUI portal for service management.
+
+.. toctree::
+   :maxdepth: 1
+   
+   new-features.rst
+   bug-fixes.rst
+   upgrade-notes.rst
+   security-issues.rst
+   known-issues.rst
diff --git a/docs/release-notes/known-issues.rst b/docs/release-notes/known-issues.rst
new file mode 100644
index 0000000..f4341d7
--- /dev/null
+++ b/docs/release-notes/known-issues.rst
@@ -0,0 +1,4 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Known Issues
+------------
diff --git a/docs/release-notes/new-features.rst b/docs/release-notes/new-features.rst
new file mode 100644
index 0000000..f548910
--- /dev/null
+++ b/docs/release-notes/new-features.rst
@@ -0,0 +1,4 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+New Features
+------------
diff --git a/docs/release-notes/security-issues.rst b/docs/release-notes/security-issues.rst
new file mode 100644
index 0000000..3a6cd9e
--- /dev/null
+++ b/docs/release-notes/security-issues.rst
@@ -0,0 +1,4 @@
+.. 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
new file mode 100644
index 0000000..29e67e5
--- /dev/null
+++ b/docs/release-notes/upgrade-notes.rst
@@ -0,0 +1,4 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Upgrade Notes
+-------------