diff options
| -rw-r--r-- | docs/platform/administration.rst | 30 | ||||
| -rw-r--r-- | docs/platform/consumedapis.rst | 54 | ||||
| -rw-r--r-- | docs/platform/delivery.rst | 9 | ||||
| -rw-r--r-- | docs/platform/human-interfaces.rst | 13 | ||||
| -rw-r--r-- | docs/platform/images/holmes-delivery.png | bin | 0 -> 37534 bytes | |||
| -rw-r--r-- | docs/platform/images/swagger-gui-for-holmes.png | bin | 0 -> 27875 bytes | |||
| -rw-r--r-- | docs/platform/index.rst | 7 | ||||
| -rw-r--r-- | docs/platform/installation.rst | 37 | ||||
| -rw-r--r-- | docs/platform/log-and-diagnostic-info.rst | 19 | ||||
| -rw-r--r-- | docs/platform/offeredapis.rst | 7 | ||||
| -rw-r--r-- | docs/release-notes/index.rst | 15 |
11 files changed, 172 insertions, 19 deletions
diff --git a/docs/platform/administration.rst b/docs/platform/administration.rst index a32790f..977e024 100644 --- a/docs/platform/administration.rst +++ b/docs/platform/administration.rst @@ -4,12 +4,30 @@ Administration -------------- -Processes -^^^^^^^^^ -* Process 1 -* Process 2 +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 ^^^^^^^ -* Action X -* Action Y
\ No newline at end of file + +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/consumedapis.rst b/docs/platform/consumedapis.rst index f6eebb0..6d803d1 100644 --- a/docs/platform/consumedapis.rst +++ b/docs/platform/consumedapis.rst @@ -4,4 +4,56 @@ Consumed APIs ------------- -References to APIs offered by other components
\ No newline at end of file +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 index 27b3770..5b2a0b1 100644 --- a/docs/platform/delivery.rst +++ b/docs/platform/delivery.rst @@ -5,5 +5,12 @@ 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. -**TO BE DONE**
\ No newline at end of file +* 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 index e8501d0..d73c6cc 100644 --- a/docs/platform/human-interfaces.rst +++ b/docs/platform/human-interfaces.rst @@ -3,13 +3,22 @@ Human Interfaces ---------------- -Provide info on the targeted user, interface types, ports/protocols to access, etc. 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 -^^^^^^
\ No newline at end of file +^^^^^^ + +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-delivery.png b/docs/platform/images/holmes-delivery.png Binary files differnew file mode 100644 index 0000000..a62d82d --- /dev/null +++ b/docs/platform/images/holmes-delivery.png diff --git a/docs/platform/images/swagger-gui-for-holmes.png b/docs/platform/images/swagger-gui-for-holmes.png Binary files differnew file mode 100644 index 0000000..c2ed5d7 --- /dev/null +++ b/docs/platform/images/swagger-gui-for-holmes.png diff --git a/docs/platform/index.rst b/docs/platform/index.rst index 19742bb..441d0a9 100644 --- a/docs/platform/index.rst +++ b/docs/platform/index.rst @@ -1,7 +1,7 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. -Holmes ------------------------------------------------- +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. @@ -10,9 +10,10 @@ Holmes provides alarm correlation and analysis for Telecom cloud infrastructure architecture.rst offeredapis.rst + consumedapis.rst delivery.rst log-and-diagnostic-info.rst installation.rst configuration.rst administration.rst - human-interfaces.rst
\ No newline at end of file + human-interfaces.rst diff --git a/docs/platform/installation.rst b/docs/platform/installation.rst index 7926680..f380835 100644 --- a/docs/platform/installation.rst +++ b/docs/platform/installation.rst @@ -3,3 +3,40 @@ 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 index 4561eab..53527f5 100644 --- a/docs/platform/log-and-diagnostic-info.rst +++ b/docs/platform/log-and-diagnostic-info.rst @@ -2,13 +2,26 @@ .. http://creativecommons.org/licenses/by/4.0 Logging & Diagnostic Information +--------------------------------- - -Description of how to interact with and diagnose problems with the components as delivered. +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 -^^^^^^^^^^^^^^^^^^^^^^^^
\ No newline at end of file +^^^^^^^^^^^^^^^^^^^^^^^^ + +* 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 index 41142ed..1d38145 100644 --- a/docs/platform/offeredapis.rst +++ b/docs/platform/offeredapis.rst @@ -1,5 +1,6 @@ -Holmes Rule Management Component Offered APIs -================================== +Offered APIs +------------ + The rule management module provides the following APIs. * Rule Creation @@ -7,4 +8,4 @@ The rule management module provides the following APIs. * Rule Query * Rule Deletion -.. swaggerv2doc:: ../rulemgt/src/main/resources/swagger.json +.. swaggerv2doc:: ../../rulemgt/src/main/resources/swagger.json diff --git a/docs/release-notes/index.rst b/docs/release-notes/index.rst new file mode 100644 index 0000000..57f654f --- /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 +------------- + +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 + + new-features.rst + bug-fixes.rst + upgrade-notes.rst + security-issues.rst + known-issues.rst |
