14 files changed, 271 insertions, 0 deletions
diff --git a/docs/platform/administration.rst b/docs/platform/administration.rst
new file mode 100644
index 00000000..977e024e
--- /dev/null
+++ b/docs/platform/administration.rst
@@ -0,0 +1,33 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+
+Administration
+--------------
+
+It is not hard to manage Holmes becasue it's been dockerized and split into two dockers. One is for rule management and the other for engine management.
+
+Processes / Dockers
+^^^^^^^^^^^^^^^^^^^
+
+For both of the dockers of Holmes, there's only one process running during the run time. But the rule management docker sort of relies on the enginemanagement docker. Once the engine management module is stopped, the whole Holmes will malfunction because the Drools engine which is managed by the engine management module is the core component of Holmes.
+
+Holmes mainly consists of two dockers:
+
+* Rule Management Docker
+
+* Engine Management Docker
+
+Actions
+^^^^^^^
+
+All actions performed on the Holmes modules are docker-based.
+
+* Create a Container: ``sudo docker run [OPTIONS] IMAGE [COMMAND] [ARG...]``
+
+* Kill a Container: ``sudo docker kill [OPTIONS] CONTAINER [CONTAINER...]``
+
+* Stop a Container: ``sudo docker stop [OPTIONS] CONTAINER [CONTAINER...]``
+
+* Start a Container: ``sudo docker start [OPTIONS] CONTAINER [CONTAINER...]``
+
+* Restart a Container: ``sudo docker restart [OPTIONS] CONTAINER [CONTAINER...]``
diff --git a/docs/platform/architecture.rst b/docs/platform/architecture.rst
new file mode 100644
index 00000000..2fca78bd
--- /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 00000000..cedb4435
--- /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 00000000..6d803d19
--- /dev/null
+++ b/docs/platform/consumedapis.rst
@@ -0,0 +1,59 @@
+.. 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, Holmes mainly depends on the APIs provided by DCAE, A&AI, DMaaP and MSB.
+
+DCAE
+^^^^
+
+Holmes uses DCAE APIs to fetch the information of the microservices that are registered to the DCAE Consul via the Config Binding Service provided by DCAE. The definition of the APIs could be found at `Config Binding Service APIs <https://wiki.onap.org/download/attachments/13599708/cb.html?version=1&modificationDate=1503378245000&api=v2>`_.
+
+A&AI
+^^^^
+
+In order to get the correlation between different alarms with the help of the topological information provided by A&AI. Holmes needs to call the A&AI APIs. Generally, we have to query the information of VNFs, VMs and the corresponding relation between resources from different layers. The following APIs are invoked by Holmes.
+
+#. Query a VNF by name:
+
+   ``/aai/v11/network/generic-vnfs/generic-vnf?vnf-name={vnf-name}``
+
+#. Query a VNF by ID:
+
+   ``/aai/v11/network/generic-vnfs/generic-vnf?vnf-id={vnf-id}``
+
+#. Query a VM by name:
+
+   ``/aai/v11/search/nodes-query?search-node-type=vserver&filter=vserver-name:EQUALS:{vserver-name}``
+
+#. Query a VM by ID:
+
+   ``/aai/v11/search/nodes-query?search-node-type=vserver&filter=vserver-id:EQUALS:{vserver-id}`` 
+
+More details could be found at `A&AI APIs <https://wiki.onap.org/pages/viewpage.action?pageId=13598793>`_.
+ 
+DMaaP
+^^^^^
+
+Holmes fetches VES data from DMaaP and publishes the control loop event back to DMaaP. The related APIs are:
+
+#. Subscribing:
+
+   ``/events/{topic}/{consumergroup}/{consumerid}``
+
+#. Publishing:
+
+   ``/events/{topic}``
+
+More details could be found at `DMaaP APIs <https://wiki.onap.org/display/DW/DMaaP+API>`_.
+
+MSB
+^^^
+
+MSB is a key component that Holmes depends on. Almost all communications between Holmes and other components are performed using MSB as a proxy. In order to utilize the service registration and discovery functions provided by MSB, Holmes has to register itself to MSB in advance.
+
+Service Registration: ``/api/microservices/v1/services``
+
+More details could be found at `MSB APIs <https://wiki.onap.org/display/DW/Microservice+Bus+API+Documentation>`_.
diff --git a/docs/platform/delivery.rst b/docs/platform/delivery.rst
new file mode 100644
index 00000000..5b2a0b16
--- /dev/null
+++ b/docs/platform/delivery.rst
@@ -0,0 +1,16 @@
+.. 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.
+As mentioned in the architecture chapter, Holmes mainly comprises three modules: the rule management module, the engine management module and the data source adapter. But due to the imperfect implemetation of the DCAE platform, the engine management module and the data source adapter are hosted in a single docker. From this point of view, Holmes in the Amsterdam release actually consists of two main modules.
+
+* Rule Management Docker: The main operations on the rules are performed in this module. The module provides CRUD operation interfaces and is reponsible of the persistence of the rules as well.
+
+* Engine Management Docker: The Drools rules are actually deployed into the Drools engine which is embedded within the engine management module. The analysis tasks are excuted in this module as well. Ideally, the data source adapter is supposed to be running as a standalone docker and communicate with the engine management module via MQ (or any other message bus). But in the Amsterdam release, due to the limitation of the DCAE platform. These two modules are merged into one and interact with each other directy in the manner of Java API calls.
+
+* Common Library: The library hosts some supportive tools for both the rule management module and the engine management module. It is not run separately. Instead, it is introduced into the main modules of Holmes during the compile and package phase.
+
+.. image:: images/holmes-delivery.png
diff --git a/docs/platform/human-interfaces.rst b/docs/platform/human-interfaces.rst
new file mode 100644
index 00000000..d73c6cc8
--- /dev/null
+++ b/docs/platform/human-interfaces.rst
@@ -0,0 +1,24 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Human Interfaces
+----------------
+
+Target Users
+^^^^^^^^^^^^
+
+The human interfaces provided in the Amsterdam release by Holmes is intended for the developers rather than the end users.
+
+Interface Type
+^^^^^^^^^^^^^^
+
+The interfaces of Holmes is more like a Swagger GUI, which is supported by MSB and used by the developers or system engineers for debugging or testing. They could use the GUI instead of the ``curl`` command or Postman to call the RESTful APIs of Holmes.
+
+Access
+^^^^^^
+
+Go to the MSB interface with a browser, using the address ``http://${msb-ip}:${msb-port}/iui/microservices/default.html``. Select the "API Service" tab (which is opened by default), then you can see all the registered microservices. Click on the microservice block of which the name is *holmes-rule-mgmt* and the APIs will be displayed in the browser. Select the corresponding interface and details will be expanded. Users could use the interface to send http request to the Holmes server to perform health check or other operations on the rules.
+
+.. image:: images/swagger-gui-for-holmes.png
+
+**Direct calling of the APIs in the engine management module of Holmes is not recommended becasue it would cause data inconsistency between the rule managment module and the engine management module. All rules related operations should be only conducted on the rule management module.**
diff --git a/docs/platform/images/holmes-architecture.png b/docs/platform/images/holmes-architecture.png
new file mode 100644
index 00000000..b2bd2a97
--- /dev/null
+++ b/docs/platform/images/holmes-architecture.png
diff --git a/docs/platform/images/holmes-delivery.png b/docs/platform/images/holmes-delivery.png
new file mode 100644
index 00000000..a62d82d6
--- /dev/null
+++ b/docs/platform/images/holmes-delivery.png
diff --git a/docs/platform/images/overall-architecture-in-onap.png b/docs/platform/images/overall-architecture-in-onap.png
new file mode 100644
index 00000000..22c82277
--- /dev/null
+++ b/docs/platform/images/overall-architecture-in-onap.png
diff --git a/docs/platform/images/swagger-gui-for-holmes.png b/docs/platform/images/swagger-gui-for-holmes.png
new file mode 100644
index 00000000..c2ed5d71
--- /dev/null
+++ b/docs/platform/images/swagger-gui-for-holmes.png
diff --git a/docs/platform/index.rst b/docs/platform/index.rst
new file mode 100644
index 00000000..441d0a92
--- /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
+--------
+
+Holmes provides alarm correlation and analysis for Telecom cloud infrastructure and services, including hosts, vims, VNFs and NSs. Holmes aims to find the root reason which causes the failure or degradation of services by digging into the ocean of events collected from different levels of the Telecom cloud.
+
+.. 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 00000000..f380835f
--- /dev/null
+++ b/docs/platform/installation.rst
@@ -0,0 +1,42 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+
+Installation
+------------
+
+In the Amsterdam release, Holmes is deployed as an analytic application by the DCAE controller. So the users do not have to install it on their own.
+
+In case the users want to deploy Holmes independently, the steps for the installation is as follows.
+
+Prerequisites
+^^^^^^^^^^^^^
+
+#. MSB must be installed and started. The user knows the IP address of the MSB API gateway service.
+#. PostgreSQL must be installed and started. For the guidance on how to run a PostgreSQL, please refer to `Offical Repository of PostgreSQL <https://hub.docker.com/_/postgres/>`_.
+   
+   **While setting up PostgreSQL, a database and a user named 'holmes' must be created. The corresponding password shuold be set to 'holmespwd'. Otherwise, Holmes could not be started up successfully.**
+
+Steps
+^^^^^
+
+#. Start the rule management module of Holmes using the command below:
+
+   ``sudo docker run --name holmes-rule-management -p 9101:9101 -d -e URL_JDBC=$DB_IP -e MSB_ADDR=$MSB_IP -e TESTING=1 nexus3.onap.org:10001/onap/holmes/rule-management`` 
+
+#. Start the engine manamgement module of Holmes using the command below:
+
+   ``sudo docker run --name holmes-engine-management -p 9102:9102 -d -e URL_JDBC=$DB_IP -e MSB_ADDR=$MSB_IP -e TESTING=1 nexus3.onap.org:10001/onap/holmes/engine-management``
+
+When the environment variable ``TESTING`` is set to ``1``, it means Holmes is running in the standalone mode. All the interactions between Holmes and other ONAP components are routed by MSB.
+
+Check the Status of Holmes
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After the installation, you have to check whether Holmes is alive or not using the health-check API.
+
+#. Use ``curl http://${msb-ip}:${msb-port}/api/holmes-rule-mgmt/v1/healthcheck`` or any other tools (e.g. Postman) to check whether the rule management module of Holmes has been spun up and registered to MSB successfully. 
+
+#. Use ``curl http://${msb-ip}:${msb-port}/api/holmes-engine-mgmt/v1/healthcheck`` or any other tools (e.g. Postman) to check whether the engine management module of Holmes has been spun up and registered to MSB successfully.
+
+If the response code is ``200`` and the response body is ``true``, it's telling the user that everything is fine. Otherwise, you have to take a look at the logs to check whether there are any errors and contact the Holmes team for help.
+
diff --git a/docs/platform/log-and-diagnostic-info.rst b/docs/platform/log-and-diagnostic-info.rst
new file mode 100644
index 00000000..53527f56
--- /dev/null
+++ b/docs/platform/log-and-diagnostic-info.rst
@@ -0,0 +1,27 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Logging & Diagnostic Information
+---------------------------------
+
+In the Amsterdam release, the logs are kept inside the docekr containers, which means that you can get the log information only when the docker is still running. 
+
+Where to Access Information
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Assume that the name of a running docker is *holmes-rule-mgmt*, the way to get the log is to run the command ``docker logs ${docker-name}`` in the command window:
+
+``sudo docker logs holmes-rule-mgmt``
+
+Then the logs will be displayed in the command window.
+
+Error / Warning Messages
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Failed to initialize the SSL builder.: Could not create the SSL information for HTTPS calls.
+* Failed to fetch the DCAE configurations.: Could not get the configurations coded in the component specification files.
+* Failed to add rules.: Failed to deploy the rules distributed by CLAMP into Holmes.
+* Failed to publish the control loop message to DMaaP.: Errors occur while publishing messages to DMaaP.
+* Failed to read the API description file.: Could not find the swagger.json file.
+* An error occurrred while reading swagger.json.: An I/O Exception occurs while reading the swagger.json file.
+
+
diff --git a/docs/platform/offeredapis.rst b/docs/platform/offeredapis.rst
new file mode 100644
index 00000000..1d381457
--- /dev/null
+++ b/docs/platform/offeredapis.rst
@@ -0,0 +1,11 @@
+Offered APIs
+------------
+
+The rule management module provides the following APIs.
+
+* Rule Creation
+* Rule Update
+* Rule Query
+* Rule Deletion
+
+.. swaggerv2doc:: ../../rulemgt/src/main/resources/swagger.json