From 6a35d99de3143d80f1fec13e310bb6fc156fe8cc Mon Sep 17 00:00:00 2001 From: Guangrong Fu Date: Thu, 14 Oct 2021 09:14:31 +0800 Subject: Updated docs Issue-ID: HOLMES-480 Signed-off-by: Guangrong Fu Change-Id: I6893e4cd12dfd70e1c32079912cdfefad32b7da7 --- docs/_static/css/ribbon.css | 63 --- docs/_static/favicon.ico | Bin 2102 -> 0 bytes docs/_static/logo_onap_2017.png | Bin 12278 -> 0 bytes docs/conf.py | 15 - docs/conf.yaml | 7 - docs/docs/_static/css/ribbon.css | 63 +++ docs/docs/_static/favicon.ico | Bin 0 -> 2102 bytes docs/docs/_static/logo_onap_2017.png | Bin 0 -> 12278 bytes docs/docs/conf.py | 15 + docs/docs/conf.yaml | 7 + docs/docs/index.rst | 15 + docs/docs/platform/administration.rst | 33 ++ docs/docs/platform/architecture.rst | 21 + docs/docs/platform/configuration.rst | 8 + docs/docs/platform/consumedapis.rst | 59 +++ docs/docs/platform/delivery.rst | 16 + docs/docs/platform/human-interfaces.rst | 24 + docs/docs/platform/images/holmes-architecture.png | Bin 0 -> 20256 bytes docs/docs/platform/images/holmes-delivery.png | Bin 0 -> 37534 bytes .../images/overall-architecture-in-onap.png | Bin 0 -> 43459 bytes .../platform/images/swagger-gui-for-holmes.png | Bin 0 -> 27875 bytes docs/docs/platform/index.rst | 19 + docs/docs/platform/installation.rst | 43 ++ docs/docs/platform/log-and-diagnostic-info.rst | 33 ++ docs/docs/platform/offeredapis.rst | 13 + docs/docs/release-notes.rst | 385 ++++++++++++++ docs/docs/requirements-docs.txt | 15 + docs/etc/requirements.txt | 4 + docs/etc/upper-constraints.onap.txt | 7 + docs/etc/upper-constraints.os.txt | 585 +++++++++++++++++++++ docs/index.rst | 15 - docs/platform/administration.rst | 33 -- docs/platform/architecture.rst | 21 - docs/platform/configuration.rst | 8 - docs/platform/consumedapis.rst | 59 --- docs/platform/delivery.rst | 16 - docs/platform/human-interfaces.rst | 24 - docs/platform/images/holmes-architecture.png | Bin 20256 -> 0 bytes docs/platform/images/holmes-delivery.png | Bin 37534 -> 0 bytes .../images/overall-architecture-in-onap.png | Bin 43459 -> 0 bytes docs/platform/images/swagger-gui-for-holmes.png | Bin 27875 -> 0 bytes docs/platform/index.rst | 19 - docs/platform/installation.rst | 43 -- docs/platform/log-and-diagnostic-info.rst | 33 -- docs/platform/offeredapis.rst | 13 - docs/release-notes.rst | 381 -------------- docs/requirements-docs.txt | 15 - docs/tox.ini | 71 ++- 48 files changed, 1428 insertions(+), 773 deletions(-) delete mode 100644 docs/_static/css/ribbon.css delete mode 100755 docs/_static/favicon.ico delete mode 100644 docs/_static/logo_onap_2017.png delete mode 100644 docs/conf.py delete mode 100644 docs/conf.yaml create mode 100644 docs/docs/_static/css/ribbon.css create mode 100755 docs/docs/_static/favicon.ico create mode 100644 docs/docs/_static/logo_onap_2017.png create mode 100644 docs/docs/conf.py create mode 100644 docs/docs/conf.yaml create mode 100644 docs/docs/index.rst create mode 100644 docs/docs/platform/administration.rst create mode 100644 docs/docs/platform/architecture.rst create mode 100644 docs/docs/platform/configuration.rst create mode 100644 docs/docs/platform/consumedapis.rst create mode 100644 docs/docs/platform/delivery.rst create mode 100644 docs/docs/platform/human-interfaces.rst create mode 100644 docs/docs/platform/images/holmes-architecture.png create mode 100644 docs/docs/platform/images/holmes-delivery.png create mode 100644 docs/docs/platform/images/overall-architecture-in-onap.png create mode 100644 docs/docs/platform/images/swagger-gui-for-holmes.png create mode 100644 docs/docs/platform/index.rst create mode 100644 docs/docs/platform/installation.rst create mode 100644 docs/docs/platform/log-and-diagnostic-info.rst create mode 100644 docs/docs/platform/offeredapis.rst create mode 100644 docs/docs/release-notes.rst create mode 100644 docs/docs/requirements-docs.txt create mode 100644 docs/etc/requirements.txt create mode 100644 docs/etc/upper-constraints.onap.txt create mode 100644 docs/etc/upper-constraints.os.txt delete mode 100644 docs/index.rst delete mode 100644 docs/platform/administration.rst delete mode 100644 docs/platform/architecture.rst delete mode 100644 docs/platform/configuration.rst delete mode 100644 docs/platform/consumedapis.rst delete mode 100644 docs/platform/delivery.rst delete mode 100644 docs/platform/human-interfaces.rst delete mode 100644 docs/platform/images/holmes-architecture.png delete mode 100644 docs/platform/images/holmes-delivery.png delete mode 100644 docs/platform/images/overall-architecture-in-onap.png delete mode 100644 docs/platform/images/swagger-gui-for-holmes.png delete mode 100644 docs/platform/index.rst delete mode 100644 docs/platform/installation.rst delete mode 100644 docs/platform/log-and-diagnostic-info.rst delete mode 100644 docs/platform/offeredapis.rst delete mode 100644 docs/release-notes.rst delete mode 100644 docs/requirements-docs.txt diff --git a/docs/_static/css/ribbon.css b/docs/_static/css/ribbon.css deleted file mode 100644 index 6008cb1..0000000 --- a/docs/_static/css/ribbon.css +++ /dev/null @@ -1,63 +0,0 @@ -.ribbon { - z-index: 1000; - background-color: #a00; - overflow: hidden; - white-space: nowrap; - position: fixed; - top: 25px; - right: -50px; - -webkit-transform: rotate(45deg); - -moz-transform: rotate(45deg); - -ms-transform: rotate(45deg); - -o-transform: rotate(45deg); - transform: rotate(45deg); - -webkit-box-shadow: 0 0 10px #888; - -moz-box-shadow: 0 0 10px #888; - box-shadow: 0 0 10px #888; - -} - -.ribbon a { - border: 1px solid #faa; - color: #fff; - display: block; - font: bold 81.25% 'Helvetica Neue', Helvetica, Arial, sans-serif; - margin: 1px 0; - padding: 10px 50px; - text-align: center; - text-decoration: none; - text-shadow: 0 0 5px #444; - transition: 0.5s; -} - -.ribbon a:hover { - background: #c11; - color: #fff; -} - - -/* override table width restrictions */ -@media screen and (min-width: 767px) { - - .wy-table-responsive table td, .wy-table-responsive table th { - /* !important prevents the common CSS stylesheets from overriding - this as on RTD they are loaded after this stylesheet */ - white-space: normal !important; - } - - .wy-table-responsive { - overflow: visible !important; - } -} - -@media screen and (max-width: 767px) { - .wy-table-responsive table td { - white-space: nowrap; - } -} - -/* fix width of the screen */ - -.wy-nav-content { - max-width: none; -} diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico deleted file mode 100755 index cb712eb..0000000 Binary files a/docs/_static/favicon.ico and /dev/null differ diff --git a/docs/_static/logo_onap_2017.png b/docs/_static/logo_onap_2017.png deleted file mode 100644 index 5d064f4..0000000 Binary files a/docs/_static/logo_onap_2017.png and /dev/null differ diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 5371015..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,15 +0,0 @@ -from docs_conf.conf import * - -branch = 'latest' -master_doc = 'index' - -linkcheck_ignore = [ - 'http://localhost', -] - -intersphinx_mapping = {} - -html_last_updated_fmt = '%d-%b-%y %H:%M' - -def setup(app): - app.add_stylesheet("css/ribbon.css") diff --git a/docs/conf.yaml b/docs/conf.yaml deleted file mode 100644 index ab59281..0000000 --- a/docs/conf.yaml +++ /dev/null @@ -1,7 +0,0 @@ ---- -project_cfg: onap -project: onap - -# Change this to ReleaseBranchName to modify the header -default-version: latest -# diff --git a/docs/docs/_static/css/ribbon.css b/docs/docs/_static/css/ribbon.css new file mode 100644 index 0000000..6008cb1 --- /dev/null +++ b/docs/docs/_static/css/ribbon.css @@ -0,0 +1,63 @@ +.ribbon { + z-index: 1000; + background-color: #a00; + overflow: hidden; + white-space: nowrap; + position: fixed; + top: 25px; + right: -50px; + -webkit-transform: rotate(45deg); + -moz-transform: rotate(45deg); + -ms-transform: rotate(45deg); + -o-transform: rotate(45deg); + transform: rotate(45deg); + -webkit-box-shadow: 0 0 10px #888; + -moz-box-shadow: 0 0 10px #888; + box-shadow: 0 0 10px #888; + +} + +.ribbon a { + border: 1px solid #faa; + color: #fff; + display: block; + font: bold 81.25% 'Helvetica Neue', Helvetica, Arial, sans-serif; + margin: 1px 0; + padding: 10px 50px; + text-align: center; + text-decoration: none; + text-shadow: 0 0 5px #444; + transition: 0.5s; +} + +.ribbon a:hover { + background: #c11; + color: #fff; +} + + +/* override table width restrictions */ +@media screen and (min-width: 767px) { + + .wy-table-responsive table td, .wy-table-responsive table th { + /* !important prevents the common CSS stylesheets from overriding + this as on RTD they are loaded after this stylesheet */ + white-space: normal !important; + } + + .wy-table-responsive { + overflow: visible !important; + } +} + +@media screen and (max-width: 767px) { + .wy-table-responsive table td { + white-space: nowrap; + } +} + +/* fix width of the screen */ + +.wy-nav-content { + max-width: none; +} diff --git a/docs/docs/_static/favicon.ico b/docs/docs/_static/favicon.ico new file mode 100755 index 0000000..cb712eb Binary files /dev/null and b/docs/docs/_static/favicon.ico differ diff --git a/docs/docs/_static/logo_onap_2017.png b/docs/docs/_static/logo_onap_2017.png new file mode 100644 index 0000000..5d064f4 Binary files /dev/null and b/docs/docs/_static/logo_onap_2017.png differ diff --git a/docs/docs/conf.py b/docs/docs/conf.py new file mode 100644 index 0000000..5371015 --- /dev/null +++ b/docs/docs/conf.py @@ -0,0 +1,15 @@ +from docs_conf.conf import * + +branch = 'latest' +master_doc = 'index' + +linkcheck_ignore = [ + 'http://localhost', +] + +intersphinx_mapping = {} + +html_last_updated_fmt = '%d-%b-%y %H:%M' + +def setup(app): + app.add_stylesheet("css/ribbon.css") diff --git a/docs/docs/conf.yaml b/docs/docs/conf.yaml new file mode 100644 index 0000000..ab59281 --- /dev/null +++ b/docs/docs/conf.yaml @@ -0,0 +1,7 @@ +--- +project_cfg: onap +project: onap + +# Change this to ReleaseBranchName to modify the header +default-version: latest +# diff --git a/docs/docs/index.rst b/docs/docs/index.rst new file mode 100644 index 0000000..0a16914 --- /dev/null +++ b/docs/docs/index.rst @@ -0,0 +1,15 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. _master_index: + +Holmes +------ + +This document is aimed to give the users some brief introductions on Holmes 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 Holmes in this document. + +.. toctree:: + :maxdepth: 1 + + platform/index.rst + release-notes.rst diff --git a/docs/docs/platform/administration.rst b/docs/docs/platform/administration.rst new file mode 100644 index 0000000..977e024 --- /dev/null +++ b/docs/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/docs/platform/architecture.rst b/docs/docs/platform/architecture.rst new file mode 100644 index 0000000..0a5ed6c --- /dev/null +++ b/docs/docs/platform/architecture.rst @@ -0,0 +1,21 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. _architecture: + + +Holmes Architecture +------------------- + +Basically, Holmes itself is an independent component in ONAP, which means it could be deployed as an ONAP-level component. In the Istanbul 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 + + +Taking a deep dive into Holmes, could observe that 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/docs/platform/configuration.rst b/docs/docs/platform/configuration.rst new file mode 100644 index 0000000..fd01c02 --- /dev/null +++ b/docs/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 Istanbul release. Such functionalities will be provided in the future if necessary. + diff --git a/docs/docs/platform/consumedapis.rst b/docs/docs/platform/consumedapis.rst new file mode 100644 index 0000000..640deef --- /dev/null +++ b/docs/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 Istanbul 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 `_. + +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 `_. + +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 `_. + +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 `_. diff --git a/docs/docs/platform/delivery.rst b/docs/docs/platform/delivery.rst new file mode 100644 index 0000000..40186b6 --- /dev/null +++ b/docs/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 two modules: a rule management module and an engine management module. + +* 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. Alarm messages are converted to Holmes-compatible format and put into the Drools engine for analysis. + +* 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/docs/platform/human-interfaces.rst b/docs/docs/platform/human-interfaces.rst new file mode 100644 index 0000000..8e74506 --- /dev/null +++ b/docs/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 Istanbul 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/docs/platform/images/holmes-architecture.png b/docs/docs/platform/images/holmes-architecture.png new file mode 100644 index 0000000..e471ff6 Binary files /dev/null and b/docs/docs/platform/images/holmes-architecture.png differ diff --git a/docs/docs/platform/images/holmes-delivery.png b/docs/docs/platform/images/holmes-delivery.png new file mode 100644 index 0000000..a62d82d Binary files /dev/null and b/docs/docs/platform/images/holmes-delivery.png differ diff --git a/docs/docs/platform/images/overall-architecture-in-onap.png b/docs/docs/platform/images/overall-architecture-in-onap.png new file mode 100644 index 0000000..22c8227 Binary files /dev/null and b/docs/docs/platform/images/overall-architecture-in-onap.png differ diff --git a/docs/docs/platform/images/swagger-gui-for-holmes.png b/docs/docs/platform/images/swagger-gui-for-holmes.png new file mode 100644 index 0000000..c2ed5d7 Binary files /dev/null and b/docs/docs/platform/images/swagger-gui-for-holmes.png differ diff --git a/docs/docs/platform/index.rst b/docs/docs/platform/index.rst new file mode 100644 index 0000000..f279434 --- /dev/null +++ b/docs/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/docs/platform/installation.rst b/docs/docs/platform/installation.rst new file mode 100644 index 0000000..c6550f9 --- /dev/null +++ b/docs/docs/platform/installation.rst @@ -0,0 +1,43 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + + +Installation +------------ + +In the Istanbul 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 `_. + + **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 -p 9104:9104 -p 9201:9201 -d -e URL_JDBC=$DB_IP -e MSB_IAG_SERVICE_HOST=$MSB_IAG_IP -e MSB_IAG_SERVICE_PORT=$MSB_IAG_PORT -e TESTING=1 -e HOST_IP=$HOST_IP -e ENABLE_ENCRYPT=false nexus3.onap.org:10001/onap/holmes/rule-management:9.0.0`` + +#. 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_IAG_SERVICE_HOST=$MSB_IAG_IP -e MSB_IAG_SERVICE_PORT=MSB_IAG_PORT -e TESTING=1 -e HOST_IP=$HOST_IP -e ENABLE_ENCRYPT=false nexus3.onap.org:10001/onap/holmes/engine-management:9.0.0`` + +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. In order to register Holmes itself to MSB, the users have to specify the IP address of the host using the ``HOST_IP`` variable. Please note that the ``HOST_IP`` should be the IP address of the host, rather than the IP address of the containers (of which the IP address is allocated by the docker daemon). +``ENABLE_ENCRYPT`` specifies whether HTTPS is enabled. When it is set to "false", only the HTTP schema is allowed. Otherwise, only HTTPS is allowed. + +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/docs/platform/log-and-diagnostic-info.rst b/docs/docs/platform/log-and-diagnostic-info.rst new file mode 100644 index 0000000..607ecbc --- /dev/null +++ b/docs/docs/platform/log-and-diagnostic-info.rst @@ -0,0 +1,33 @@ +.. 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 Istanbul release, the logs are kept inside the docker containers, which means that you can get the log information only when the docker is still running. + +Where to Access Information +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +There are two ways for a user to get the logs. + + +* 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. + +* Get into the docker containers by running ``sudo docker exec -it ${docker-name} sh``. Go to the path ``/var/log/ONAP/holmes/`` and find the logs there. + +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/docs/platform/offeredapis.rst b/docs/docs/platform/offeredapis.rst new file mode 100644 index 0000000..26e9c75 --- /dev/null +++ b/docs/docs/platform/offeredapis.rst @@ -0,0 +1,13 @@ +Offered APIs +------------ +.. _offeredapis: + +The rule management module provides the following APIs. + +* Rule Creation +* Rule Update +* Rule Query +* Rule Deletion +* Health Check + +.. swaggerv2doc:: ../../rulemgt/src/main/resources/swagger.json diff --git a/docs/docs/release-notes.rst b/docs/docs/release-notes.rst new file mode 100644 index 0000000..65f010d --- /dev/null +++ b/docs/docs/release-notes.rst @@ -0,0 +1,385 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. _release_notes: + + +Holmes Rule Management 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. + +Version: 9.0.1 +-------------- + +:Release Date: 2021-10-28 + + +**New Features** + +N/A + +**Bug Fixes** + +- `Fixed Vulnerability issues by removing httpclient. `_ +- `Failed to update rules if the package name does not end with a semicolon. `_ +- `Database instantiation failed due to holmesdb password with single quote. `_ +- `Existing rules are not able to sync when engine get restarted/redeployed. `_ +- `RESTful APIs of the Engine Management Module are not Accessible. `_ + +**Known Issues** + +- If the database is not stable, there may be data/status inconsistency between the rule management module and the engine management module. +- The current horizontal scaling mechanism can not efficiently balance the load. Optimization is needed in the future. + +**Security Issues** + +HOLMES code has been formally scanned during build time using NexusCloud and all critical vulnerabilities have been addressed. + +Quick Links: + - `HOLMES project page `_ + + - `Passing Badge information for HOLMES `_ + + +**Upgrade Notes** + +N/A + + +**Deprecation Notes** + +N/A + + +**Other** + +N/A + +Version: 8.0.1 +-------------- + +:Release Date: 2021-04-22 + + +**New Features** + +- `HOLMES-380 `_ Migrate Holmes deployment to Helm + +**Bug Fixes** + +N/A + +**Known Issues** + +- If the database is not stable, there may be data/status inconsistency between the rule management module and the engine management module. +- The current horizontal scaling mechanism can not efficiently balance the load. Optimization is needed in the future. + +**Security Issues** + +HOLMES code has been formally scanned during build time using NexusCloud and all critical vulnerabilities have been addressed. + +Quick Links: + - `HOLMES project page `_ + + - `Passing Badge information for HOLMES `_ + + +**Upgrade Notes** + +N/A + + +**Deprecation Notes** + +N/A + + +**Other** + +N/A + + +Version: 7.0.1 +-------------- + +:Release Date: 2020-11-19 + + +**New Features** + +- `HOLMES-312 `_ Alarm Correlation Support in MDONS Close Loop + +**Bug Fixes** + +- `HOLMES-357 `_ Some holmes pods have no limit +- `HOLMES-367 `_ Holmes certificates are expired + +**Known Issues** + +- If the database is not stable, there may be data/status inconsistency between the rule management module and the engine management module. +- The current horizontal scaling mechanism can not efficiently balance the load. Optimization is needed in the future. + +**Security Issues** + +HOLMES code has been formally scanned during build time using NexusCloud and all critical vulnerabilities have been addressed. + +Quick Links: + - `HOLMES project page `_ + + - `Passing Badge information for HOLMES `_ + + +**Upgrade Notes** + +- Upgraded the Java environment from Java 8 to Java 11. +- Changed the base images to onap/integration-java11:7.0.0. + + +**Deprecation Notes** + +N/A + + +**Other** + +N/A + + +Version: 5.0.1 +-------------- + +:Release Date: 2019-10-17 + + +**New Features** +N/A + +**Bug Fixes** +N/A + +**Known Issues** + +- If the database is not stable, there may be data/status inconsistency between the rule management module and the engine management module. +- The current horizontal scaling mechanism can not efficiently balance the load. Optimization is needed in the future. + +**Security Issues** + +HOLMES code has been formally scanned during build time using NexusIQ and all Critical vulnerabilities have been addressed, some of the items that remain open have been assessed for risk and determined to be false positive and the rest are planned to be resolved in the next release. + +Quick Links: + - `HOLMES project page `_ + + - `Passing Badge information for HOLMES `_ + + +**Upgrade Notes** + +N/A + + +**Deprecation Notes** + +N/A + + +**Other** + +N/A + +Version: 1.2.6 +-------------- + +:Release Date: 2019-06-13 + + +**New Features** +Added some tools to support the extended CCVPN use case: + +- `Rules for CCVEN Extension `_ This feature provides some rules for the extended CCVPN usecase. Users could use the rules as templates to develop their own rules. +- `Updated AAI Assistant Tools for CCVPN Extension `_ Some tools related to the CCVPN usecase have been enhanced in order to support the extended CCVPN usecase. + +**Bug Fixes** + +- `HOLMES-204 `_ Alarms can not be deleted from the DB when they get cleared. +- `HOLMES-223 `_ The "ABATED" messages can not be generated in the control loop. + +**Known Issues** + +- If the database is not stable, there may be data/status inconsistency between the rule management module and the engine management module. +- The current horizontal scaling mechanism can not efficiently balance the load. Optimization is needed in the future. + +**Security Issues** + +HOLMES code has been formally scanned during build time using NexusIQ and all Critical vulnerabilities have been addressed, some of the items that remain open have been assessed for risk and determined to be false positive and the rest are planned to be resolved in the next release. + +Quick Links: + - `HOLMES project page `_ + + - `Passing Badge information for HOLMES `_ + + +**Upgrade Notes** + +N/A + + +**Deprecation Notes** + +N/A + + +**Other** + +N/A + +=========== + +Version: 1.2.0 +-------------- + +:Release Date: 2018-11-30 + + +**New Features** +In the Casablanca release, Holmes provides its own GUI for rule management tasks: + +- `UI Deployment `_ This feature provides a graphic user interface for the sake of easiness of rule management. It mainly provides a rule list view and a rule editing page. Users could get an overview of all rules that have been added to Holmes and create/modify them easily by using the GUI provided by this feature. + +Besides, Holmes has been enhanced to be CCVPN use case supportive. CCVPN related assistant tools are added to the common library of Holmes. + +**Bug Fixes** + +- `HOLMES-156 `_ Rules can not be deployed after they've been added/removed from the engine. +- `HOLMES-133 `_ Don't rely on key word 'import' when extracting package name from rule. +- `HOLMES-130 `_ Holmes can not be successfully registered to MSB when trying to register itself with a health check parameter. + +**Known Issues** + +- If the database is not stable, there may be data/status inconsistency between the rule management module and the engine management module. +- The current horizontal scaling mechanism can not efficiently balance the load. Optimization is needed in the future. + +**Security Issues** + +HOLMES code has been formally scanned during build time using NexusIQ and all Critical vulnerabilities have been addressed, items that remain open have been assessed for risk and determined to be false positive. The HOLMES open Critical security vulnerabilities and their risk assessment have been documented as part of the `project `_. + +Quick Links: + - `HOLMES project page `_ + + - `Passing Badge information for HOLMES `_ + + - `Project Vulnerability Review Table for HOLMES `_ + + +**Upgrade Notes** + +N/A + + +**Deprecation Notes** + +N/A + + +**Other** + +N/A + +=========== + + +Version: 1.1.0 +-------------- + +:Release Date: 2018-06-07 + + +**New Features** +In the Beijing release, Holmes provides no more functionalites than the Amsterdam release. Its main features remains like follows: + +- `Rule Management `_ The feature provides interfaces for the users to create, query, update and delete rules. In this release, they are used along with the DCAE interfaces to accomplish the deployment (creation/update) of the control loop related rules. + +- `Engine Management `_ The feature is not exposed to the end user directly. It's mainly used internally by Holmes as a container for the execution of rules. It provides interface for rule verification and deployment/un-deployment. + +Besides, Holmes has been enhanced to meet the platform maturity requirements. The enhancement mainly covers: + +- Scaling: Holmes supports horizontal scale-in/scale-out operations in case it is overloaded by too large amounts of data. + +- Security: Holmes has updated all its APIs to support the HTTPS protocol. + +**Bug Fixes** + +N/A + +**Known Issues** + +- If the database is not stable, there may be data/status inconsistency between the rule management module and the engine management module. +- The current horizontal scaling mechanism can not efficiently balance the load. Optimization is needed in the future. + +**Security Issues** + +HOLMES code has been formally scanned during build time using NexusIQ and all Critical vulnerabilities have been addressed, items that remain open have been assessed for risk and determined to be false positive. The HOLMES open Critical security vulnerabilities and their risk assessment have been documented as part of the `project `_. + +Quick Links: + - `HOLMES project page `_ + + - `Passing Badge information for HOLMES `_ + + - `Project Vulnerability Review Table for HOLMES `_ + + +**Upgrade Notes** + +- `HOLMES-99 `_ Updated the Drools engine to Version 6.5.0. +- `HOLMES-104 `_ Update all interfaces to enforce the HTTPS protocal. +- `HOLMES-112 `_ Following the guideline of the Logging Enhancements Project to implement log collection. +- `HOLMES-106 `_ Implemented horizontal scaling. +- `HOLMES-123 `_ Fixed some vulnerability issues identified by Nexus IQ. + + +**Deprecation Notes** + +None of the HTTP APIs provided in the Amsterdam release are available in Beijing anymore. + + +**Other** + +N/A + +=========== + +Version: 1.0.0 +-------------- + +:Release Date: 2017-11-16 + + +**New Features** +In the Amsterdam release, Holmes is mainly intended to support the alarm +correlation analysis for the VoLTE scenario. To get us there, Holmes provides +the following features: + +- `Rule Management `_ The feature provides interfaces for the users to create, query, update and delete rules. In this release, they are used along with the DCAE interfaces to accomplish the deployment (creation/update) of the control loop related rules. + +- `Engine Management `_ The feature is not exposed to the end user directly. It's mainly used internally by Holmes as a container for the execution of rules. It provides interface for rule verification and deployment/un-deployment. + +**Bug Fixes** + +This is the initial release. + +**Known Issues** + +If the database is not stable, there may be data/status inconsistency between the rule management module and the engine management module. + +**Security Issues** + +N/A + +**Upgrade Notes** + +N/A + + +End of Release Notes diff --git a/docs/docs/requirements-docs.txt b/docs/docs/requirements-docs.txt new file mode 100644 index 0000000..b3188dd --- /dev/null +++ b/docs/docs/requirements-docs.txt @@ -0,0 +1,15 @@ +tox +Sphinx +doc8 +docutils +setuptools +six +sphinx_rtd_theme>=0.4.3 +sphinxcontrib-blockdiag +sphinxcontrib-needs>=0.2.3 +sphinxcontrib-nwdiag +sphinxcontrib-seqdiag +sphinxcontrib-swaggerdoc +sphinxcontrib-plantuml +sphinx_bootstrap_theme +lfdocs-conf diff --git a/docs/etc/requirements.txt b/docs/etc/requirements.txt new file mode 100644 index 0000000..b6654e5 --- /dev/null +++ b/docs/etc/requirements.txt @@ -0,0 +1,4 @@ +lfdocs-conf +autopep8 +sphinxcontrib-spelling +pylint diff --git a/docs/etc/upper-constraints.onap.txt b/docs/etc/upper-constraints.onap.txt new file mode 100644 index 0000000..88e019f --- /dev/null +++ b/docs/etc/upper-constraints.onap.txt @@ -0,0 +1,7 @@ +lfdocs-conf===0.7.7 +sphinxcontrib.blockdiag===2.0.0 +sphinxcontrib-needs===0.5.6 +sphinxcontrib.plantuml===0.21 +sphinxcontrib.nwdiag===2.0.0 +sphinxcontrib-swaggerdoc===0.1.7 +sphinx-rtd-theme===1.0.0 diff --git a/docs/etc/upper-constraints.os.txt b/docs/etc/upper-constraints.os.txt new file mode 100644 index 0000000..5f27d22 --- /dev/null +++ b/docs/etc/upper-constraints.os.txt @@ -0,0 +1,585 @@ +ntlm-auth===1.5.0 +voluptuous===0.12.1 +chardet===4.0.0 +enum-compat===0.0.3 +rsa===4.7.2 +restructuredtext-lint===1.3.2 +netmiko===3.3.3 +sshtunnel===0.4.0 +PasteDeploy===2.1.1 +typing===3.7.4.3 +python-saharaclient===3.3.0 +Routes===2.5.1 +rtslib-fb===2.1.74 +oslo.limit===1.3.0 +smmap===3.0.5 +confget===2.3.4 +XStatic-Angular-Bootstrap===2.5.0.0 +WebOb===1.8.7 +sphinxcontrib-actdiag===2.0.0 +pecan===1.3.3 +ryu===4.34 +os-api-ref===2.1.0 +python-ldap===3.3.1 +oslo.concurrency===4.4.0 +websocket-client===0.58.0 +osprofiler===3.4.0 +os-resource-classes===1.0.0 +tabulate===0.8.9 +python-ironic-inspector-client===4.5.0 +lxml===4.6.2 +vintage===0.4.1 +ntc-templates===1.7.0 +rst2txt===1.1.0 +setproctitle===1.2.2 +pytest===6.2.2 +python-slugify===4.0.1 +cursive===0.2.2 +oslo.service===2.5.0 +django-appconf===1.0.4 +pykerberos===1.2.1 +certifi===2020.12.5 +sphinxcontrib-nwdiag===2.0.0 +rbd-iscsi-client===0.1.8 +requests-aws===0.1.8 +alabaster===0.7.12 +pbr===5.5.1 +munch===2.5.0 +waiting===1.4.1 +attrs===20.3.0 +microversion-parse===1.0.1 +Pint===0.16.1 +oslo.i18n===5.0.1 +jsonpath-rw-ext===1.2.2 +python-mistralclient===4.2.0 +oslo.context===3.2.0 +python-senlinclient===2.2.1 +rcssmin===1.0.6 +pycadf===3.1.1 +grpcio===1.36.1 +pysendfile===2.0.1 +sniffio===1.2.0 +fixtures===3.0.0 +neutron===18.1.1 +neutron-lib===2.10.1 +XStatic-FileSaver===1.3.2.0 +oslo.metrics===0.2.1 +storage-interfaces===1.0.4 +persist-queue===0.5.1 +pystache===0.5.4 +XStatic-Font-Awesome===4.7.0.0 +nose===1.3.7 +nosehtmloutput===0.0.7 +waitress===2.0.0 +os-refresh-config===13.0.0 +pysnmp===4.4.12 +Mako===1.1.4 +pyScss===1.3.7 +# differs from https://github.com/openstack/requirements/blob/stable/wallaby/upper-constraints.txt +sphinxcontrib-htmlhelp===2.0.0 +XStatic-jQuery===1.12.4.1 +ddt===1.4.1 +XStatic-Graphlib===2.1.7.0 +pyserial===3.5 +moto===2.0.1 +infi.dtypes.wwn===0.1.1 +python-freezerclient===4.2.0 +os-xenapi===0.3.4 +python-vitrageclient===4.3.0 +nosexcover===1.0.11 +krest===1.3.2 +psycopg2===2.8.6 +networkx===2.5 +bashate===2.0.0 +XStatic-Angular===1.5.8.0 +pyngus===2.3.1 +Pillow===8.1.2 +zuul-sphinx===0.5.0 +python-mimeparse===1.6.0 +tripleo-common===15.3.0 +Tempita===0.5.2 +ply===3.11 +google-api-core===1.26.1 +requests-toolbelt===0.9.1 +simplejson===3.17.2 +suds-jurko===0.6 +immutables===0.15;python_version=='3.6' +python-swiftclient===3.11.1 +pyOpenSSL===20.0.1 +monasca-common===3.3.0 +zeroconf===0.28.8 +scipy===1.5.4;python_version=='3.6' +scipy===1.6.1;python_version=='3.8' +mypy-extensions===0.4.3 +rsd-lib===1.2.0 +XStatic-Jasmine===2.4.1.2 +googleapis-common-protos===1.53.0 +python-glanceclient===3.3.0 +pyinotify===0.9.6 +debtcollector===2.2.0 +requests-unixsocket===0.2.0 +responses===0.12.1 +croniter===1.0.8 +horizon===19.2.0 +octavia-lib===2.3.1 +python-watcherclient===3.2.0 +MarkupSafe===1.1.1 +pypowervm===1.1.24 +doc8===0.8.1 +pymongo===3.11.3 +python-cloudkittyclient===4.2.0 +soupsieve===2.2 +sqlparse===0.4.1 +oslotest===4.4.1 +jsonpointer===2.0 +defusedxml===0.7.1 +netaddr===0.8.0 +pyghmi===1.5.23 +sphinxcontrib-blockdiag===2.0.0 +thrift===0.13.0 +gnocchiclient===7.0.6 +wcwidth===0.2.5 +sphinxcontrib.datatemplates===0.7.2 +jsonpath-rw===1.4.0 +prettytable===0.7.2 +vine===5.0.0 +taskflow===4.6.0 +traceback2===1.4.0 +arrow===1.0.3 +semantic-version===2.8.5 +virtualbmc===2.2.0 +deprecation===2.1.0 +SQLAlchemy===1.3.23 +pyroute2===0.5.14 +google-auth===1.27.1 +kazoo===2.8.0 +XStatic-roboto-fontface===0.5.0.0 +pyudev===0.22.0 +eventlet===0.30.2 +openstack-doc-tools===3.3.0 +oslo.messaging===12.7.1 +jira===2.0.0 +extras===1.0.0 +PyJWT===2.0.1 +XStatic-lodash===4.16.4.2 +zVMCloudConnector===1.4.1 +paramiko===2.7.2 +ifaddr===0.1.7 +reno===3.3.0 +imagesize===1.2.0 +pydot===1.4.2 +urllib3===1.26.3 +graphviz===0.16 +PyKMIP===0.10.0 +whereto===0.4.0 +pywbem===1.1.3 +python-subunit===1.4.0 +tornado===6.1 +pycparser===2.20 +mock===4.0.3 +PyYAML===5.4.1 +beautifulsoup4===4.9.3 +os-net-config===14.2.0 +ovs===2.13.0 +cryptography===3.4.6 +httpcore===0.12.3 +URLObject===2.4.3 +nocasedict===1.0.2 +psycopg2-binary===2.8.6 +openstack-release-test===3.3.1 +validations-libs===1.2.0 +pylxd===2.3.0 +pycryptodomex===3.10.1 +anyjson===0.3.3 +requests-mock===1.8.0 +os-apply-config===13.0.0 +prometheus-client===0.9.0 +oslosphinx===4.18.0 +gunicorn===20.0.4 +storpool===5.5.0 +textfsm===1.1.0 +python-3parclient===4.2.11 +unittest2===1.1.0 +django-compressor===2.4 +libvirt-python===7.1.0 +python-zunclient===4.2.0 +tzlocal===2.1 +sphinxcontrib-jsmath===1.0.1 +python-novaclient===17.4.0 +pact===1.12.0 +bcrypt===3.2.0 +os-client-config===2.1.0 +XStatic-Angular-Gettext===2.4.1.0 +h11===0.12.0 +Pygments===2.8.1 +XStatic-Hogan===2.0.0.3 +XStatic-objectpath===1.2.1.0 +python-manilaclient===2.6.0 +# differs from https://github.com/openstack/requirements/blob/stable/wallaby/upper-constraints.txt +sphinxcontrib-serializinghtml===1.1.5 +requests===2.25.1 +snowballstemmer===2.1.0 +Jinja2===2.11.3 +XStatic-Bootstrap-SCSS===3.4.1.0 +pyzabbix===0.8.2 +ptyprocess===0.7.0 +threadloop===1.0.2 +amqp===5.0.5 +websockify===0.9.0 +XStatic-JQuery.quicksearch===2.0.3.2 +mpmath===1.2.1 +python-binary-memcached===0.30.1 +django-debreach===2.0.1 +sphinx-feature-classification===1.1.0 +django-pymemcache===1.0.0 +XStatic-JQuery-Migrate===1.2.1.2 +pytest-html===3.1.1 +appdirs===1.4.4 +tinyrpc===1.0.4 +google-auth-httplib2===0.1.0 +daiquiri===3.0.0 +influxdb===5.3.1 +# differs from https://github.com/openstack/requirements/blob/stable/wallaby/upper-constraints.txt +funcparserlib===1.0.0a0 +passlib===1.7.4 +dib-utils===0.0.11 +cliff===3.7.0 +os-brick===4.3.2 +ansible-runner===1.4.7 +scp===0.13.3 +python-zaqarclient===2.1.0 +lockfile===0.12.2 +ldappool===3.0.0 +termcolor===1.1.0 +joblib===1.0.1 +google-api-python-client===2.0.2 +castellan===3.7.2 +oslo.versionedobjects===2.4.0 +enmerkar===0.7.1 +webcolors===1.11.1 +aodhclient===2.2.0 +autobahn===21.2.1;python_version=='3.6' +autobahn===21.3.1;python_version=='3.8' +SQLAlchemy-Utils===0.36.8 +retryz===0.1.9 +pluggy===0.13.1 +coverage===5.5 +freezegun===1.1.0 +toml===0.10.0 +pyperclip===1.8.2 +cassandra-driver===3.24.0 +XStatic-Angular-Schema-Form===0.8.13.0 +gabbi===2.2.0 +nwdiag===2.0.0 +XStatic-bootswatch===3.3.7.0 +pytest-xdist===2.2.1 +XStatic-JS-Yaml===3.8.1.0 +XStatic-term.js===0.0.7.0 +oslo.log===4.4.0 +nodeenv===1.5.0 +gossip===2.4.0 +importlib-metadata===3.7.2 +oslo.middleware===4.2.0 +apipkg===1.5 +XStatic-mdi===1.6.50.2 +django-pyscss===2.0.2 +uritemplate===3.0.1 +docutils===0.16 +threadpoolctl===2.1.0 +os-ken===1.4.0 +ujson===4.0.2 +selenium===3.141.0 +python-glareclient===0.5.3 +mypy===0.812 +mistral-lib===2.4.0 +dogtag-pki===10.7.4.1 +XStatic-Angular-UUID===0.0.4.0 +purestorage===1.19.0 +sphinxcontrib-seqdiag===2.0.0 +os-win===5.4.0 +capacity===1.3.14 +retrying===1.3.3 +XStatic-Dagre===0.6.4.1 +pydotplus===2.0.2 +boto3===1.17.26 +jeepney===0.6.0 +stestr===3.1.0 +oslo.serialization===4.1.0 +warlock===1.3.3 +exabgp===4.2.11 +sphinxcontrib-httpdomain===1.7.0 +metalsmith===1.4.2 +s3transfer===0.3.4 +text-unidecode===1.3 +sphinxcontrib-svg2pdfconverter===1.1.1 +murano-pkg-check===0.3.0 +oslo.vmware===3.8.0 +XStatic-moment===2.8.4.3 +sqlalchemy-migrate===0.13.0 +gitdb===4.0.5 +python-monascaclient===2.3.0 +ldap3===2.9 +natsort===7.1.1 +requests-ntlm===1.1.0 +automaton===2.3.0 +os-service-types===1.7.0 +keyring===23.0.0 +elementpath===2.2.0 +testscenarios===0.5.0 +sphinxcontrib-pecanwsme===0.10.0 +sadisplay===0.4.9 +infinisdk===161.1.3 +packaging===20.9 +XStatic-Dagre-D3===0.4.17.0 +nose-exclude===0.5.0 +psutil===5.8.0 +py===1.10.0 +txaio===21.2.1 +elasticsearch===2.4.1 +django-nose===1.4.7 +XStatic-JQuery.TableSorter===2.14.5.2 +pifpaf===3.1.5 +pysmi===0.3.4 +blockdiag===2.0.1 +testtools===2.4.0 +infi.dtypes.iqn===0.4.0 +XStatic-tv4===1.2.7.0 +XStatic-JSEncrypt===2.3.1.1 +python-cinderclient===7.4.1 +keystonemiddleware===9.2.0 +django-formtools===2.2 +python-ceilometerclient===2.9.0 +XStatic-Spin===1.2.5.3 +tap-as-a-service===7.0.0 +os-traits===2.5.0 +SecretStorage===3.3.1 +opentracing===2.4.0 +XStatic-Rickshaw===1.5.1.0 +iso8601===0.1.14 +tooz===2.8.1 +linecache2===1.0.0 +oauth2client===4.1.3 +idna===2.10 +yamlloader===1.0.0 +protobuf===3.15.6 +sushy===3.7.3 +python-neutronclient===7.3.0 +pika===1.2.0 +oslo.cache===2.7.0 +WebTest===2.0.35 +openstack.nose-plugin===0.11 +os-collect-config===13.0.1 +edgegrid-python===1.1.1 +python-qpid-proton===0.33.0 +python-octaviaclient===2.3.1 +pysaml2===6.5.1 +requests-oauthlib===1.3.0 +oslo.reports===2.2.0 +bitmath===1.3.3.1 +ceilometermiddleware===2.2.0 +python-nss===1.0.1 +testrepository===0.0.20 +sympy===1.7.1 +Logbook===1.5.3 +PyNaCl===1.4.0 +osc-lib===2.3.1 +python-consul===1.1.0 +more-itertools===8.7.0 +seqdiag===2.0.0 +numpy===1.19.5;python_version=='3.6' +numpy===1.20.1;python_version=='3.8' +msgpack===1.0.2 +# differs from https://github.com/openstack/requirements/blob/stable/wallaby/upper-constraints.txt +Sphinx===4.2.0 +oslo.config===8.5.1 +tempest===27.0.0 +openstackdocstheme===2.2.7 +osc-placement===2.2.0 +zake===0.2.2 +python-rsdclient===1.0.2 +flux===1.3.5 +python-solumclient===3.3.0 +PyMySQL===1.0.2 +uhashring===2.0 +kubernetes===12.0.1 +httplib2===0.19.0 +betamax===0.8.1 +construct===2.10.61 +pytest-metadata===1.11.0 +pyparsing===2.4.7 +geomet===0.2.1.post1 +distlib===0.3.1 +XStatic-Moment-Timezone===0.5.22.0 +dogpile.cache===1.1.2 +python-barbicanclient===5.1.0 +salt===3002.5 +api-object-schema===2.0.0 +WSME===0.10.1 +proboscis===1.2.6.0 +oslo.upgradecheck===1.3.0 +stevedore===3.3.0 +pywinrm===0.4.1 +botocore===1.20.26 +xmltodict===0.12.0 +pyasn1===0.4.8 +oslo.rootwrap===6.2.0 +Django===2.2.19 +pexpect===4.8.0 +contextvars===2.4;python_version=='3.6' +cmd2===1.5.0 +python-json-logger===2.0.1 +redis===3.5.3 +jmespath===0.10.0 +click===7.1.2 +XStatic-smart-table===1.4.13.2 +kuryr-lib===2.3.0 +scrypt===0.8.17 +jsonpatch===1.31 +python-daemon===2.3.0 +typed-ast===1.4.2 +os-testr===2.0.0 +cotyledon===1.7.3 +xattr===0.9.7 +systemd-python===234 +python-memcached===1.59 +openstacksdk===0.55.0 +six===1.15.0 +dulwich===0.20.20 +dfs-sdk===1.2.27 +sentinels===1.0.0 +kombu===5.0.2 +distro===1.5.0 +zstd===1.4.8.1 +yaql===1.1.3 +requestsexceptions===1.4.0 +testresources===2.0.1 +falcon===2.0.0 +etcd3gw===0.2.5 +Flask-RESTful===0.3.8 +GitPython===3.1.14 +python-ironicclient===4.6.2 +XStatic===1.0.2 +XStatic-Angular-FileUpload===12.0.4.0 +python-openstackclient===5.5.1 +pyzmq===22.0.3 +nocaselist===1.0.4 +oslo.db===8.5.1 +simplegeneric===0.8.1 +python-pcre===0.7 +yappi===1.3.2 +dataclasses===0.8;python_version=='3.6' +abclient===0.2.3 +pymemcache===3.4.1 +wrapt===1.12.1 +oslo.privsep===2.5.0 +sphinxcontrib-apidoc===0.3.0 +oslo.policy===3.7.0 +python-muranoclient===2.2.0 +hvac===0.10.8 +pyeclib===1.6.0 +wsgi-intercept===1.9.2 +ndg-httpsclient===0.5.1 +pyrsistent===0.17.3 +repoze.lru===0.7 +rfc3986===1.4.0 +tenacity===6.3.1 +python-designateclient===4.2.0 +future===0.18.2 +Paste===3.5.0 +pytest-django===4.1.0 +jaeger-client===4.4.0 +XStatic-Json2yaml===0.1.1.0 +boto===2.49.0 +os-vif===2.4.0 +hyperlink===21.0.0 +mitba===1.1.1 +python-masakariclient===7.0.0 +Werkzeug===1.0.1 +pyasn1-modules===0.2.8 +APScheduler===3.7.0 +monotonic===1.5 +xmlschema===1.5.2 +python-troveclient===7.0.0 +etcd3===0.12.0 +cachez===0.1.2 +XStatic-Bootstrap-Datepicker===1.4.0.0 +CouchDB===1.2 +netifaces===0.10.9 +cachetools===4.2.1 +ws4py===0.5.1 +sphinxcontrib-qthelp===1.0.3 +keystoneauth1===4.3.1 +statsd===3.3.0 +XenAPI===2.14 +importlib-resources===5.1.2 +python-keystoneclient===4.2.0 +ceilometer===16.0.0 +diskimage-builder===3.7.0 +heat-translator===2.3.0 +python-magnumclient===3.4.1 +docker===4.4.4 +storops===1.2.8 +XStatic-Angular-lrdragndrop===1.0.2.4 +ovsdbapp===1.9.0 +aniso8601===9.0.1 +rjsmin===1.1.0 +icalendar===4.0.7 +decorator===4.4.2 +cffi===1.14.5 +python-cyborgclient===1.3.0 +futurist===2.3.0 +jsonschema===3.2.0 +sphinxcontrib-devhelp===1.0.2 +python-blazarclient===3.2.0 +alembic===1.5.7 +execnet===1.8.0 +glance-store===2.5.0 +sphinxcontrib-programoutput===0.16 +storpool.spopenstack===3.0.0 +sphinx-testing===1.0.1 +dnspython===1.16.0 +oauthlib===3.1.0 +Babel===2.9.0 +logutils===0.3.5 +zipp===3.4.1 +greenlet===1.0.0 +XStatic-Angular-Vis===4.16.0.0 +iniconfig===1.1.1 +confluent-kafka===1.6.0 +xvfbwrapper===0.2.9 +tosca-parser===2.3.0 +Flask===1.1.2 +httpx===0.17.0 +sqlalchemy-filters===0.12.0 +marathon===0.13.0 +sphinxcontrib-runcmd===0.2.0 +confspirator===0.2.2 +fasteners===0.14.1 +sortedcontainers===2.3.0 +filelock===3.0.12 +python-tackerclient===1.6.0 +python-heatclient===2.3.0 +kafka-python===2.0.2 +oslo.utils===4.8.0 +python-editor===1.0.4 +gitdb2===4.0.2 +requests-kerberos===0.12.0 +itsdangerous===1.1.0 +XStatic-jquery-ui===1.12.1.1 +monasca-statsd===2.2.0 +python-dateutil===2.8.1 +typing-extensions===3.7.4.3 +virtualenv===20.4.2 +colorama===0.4.4 +confetti===2.5.3 +ironic-lib===4.6.2 +pytz===2021.1 +pytest-forked===1.3.0 +XStatic-D3===3.5.17.0 +actdiag===2.0.0 +sysv-ipc===1.1.0 +sphinxcontrib-applehelp===1.0.2 +scikit-learn===0.24.1 +# differs from https://github.com/openstack/requirements/blob/stable/wallaby/upper-constraints.txt +setuptools===58.1.0 +ruamel.yaml===0.17.7 diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 0a16914..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. _master_index: - -Holmes ------- - -This document is aimed to give the users some brief introductions on Holmes 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 Holmes in this document. - -.. toctree:: - :maxdepth: 1 - - platform/index.rst - release-notes.rst diff --git a/docs/platform/administration.rst b/docs/platform/administration.rst deleted file mode 100644 index 977e024..0000000 --- a/docs/platform/administration.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. 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 deleted file mode 100644 index 80a3496..0000000 --- a/docs/platform/architecture.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. _architecture: - - -Holmes Architecture -------------------- - -Basically, Holmes itself is an independent component in ONAP, which means it could be deployed as an ONAP-level component. In the Honolulu 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 - - -Taking a deep dive into Holmes, could observe that 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 deleted file mode 100644 index 01893a4..0000000 --- a/docs/platform/configuration.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - - -Configuration -------------- - -No machanism for customized configurtions is provided in the Honolulu release. Such functionalities will be provided in the future if necessary. - diff --git a/docs/platform/consumedapis.rst b/docs/platform/consumedapis.rst deleted file mode 100644 index 9c0a0ff..0000000 --- a/docs/platform/consumedapis.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -Consumed APIs -------------- - -In the Honolulu 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 `_. - -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 `_. - -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 `_. - -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 `_. diff --git a/docs/platform/delivery.rst b/docs/platform/delivery.rst deleted file mode 100644 index 40186b6..0000000 --- a/docs/platform/delivery.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. 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 two modules: a rule management module and an engine management module. - -* 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. Alarm messages are converted to Holmes-compatible format and put into the Drools engine for analysis. - -* 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 deleted file mode 100644 index 24142a2..0000000 --- a/docs/platform/human-interfaces.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. 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 Honolulu 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 deleted file mode 100644 index e471ff6..0000000 Binary files a/docs/platform/images/holmes-architecture.png and /dev/null differ diff --git a/docs/platform/images/holmes-delivery.png b/docs/platform/images/holmes-delivery.png deleted file mode 100644 index a62d82d..0000000 Binary files a/docs/platform/images/holmes-delivery.png and /dev/null differ diff --git a/docs/platform/images/overall-architecture-in-onap.png b/docs/platform/images/overall-architecture-in-onap.png deleted file mode 100644 index 22c8227..0000000 Binary files a/docs/platform/images/overall-architecture-in-onap.png and /dev/null differ diff --git a/docs/platform/images/swagger-gui-for-holmes.png b/docs/platform/images/swagger-gui-for-holmes.png deleted file mode 100644 index c2ed5d7..0000000 Binary files a/docs/platform/images/swagger-gui-for-holmes.png and /dev/null differ diff --git a/docs/platform/index.rst b/docs/platform/index.rst deleted file mode 100644 index f279434..0000000 --- a/docs/platform/index.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. 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 deleted file mode 100644 index ee3f2e5..0000000 --- a/docs/platform/installation.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - - -Installation ------------- - -In the Honolulu 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 `_. - - **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 -p 9201:9201 -p 9104:9104 -p 9105:9105 -d -e URL_JDBC=$DB_IP -e MSB_ADDR=$MSB_IP -e TESTING=1 -e HOST_IP=$HOST_IP -e ENABLE_ENCRYPT=false 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 -e HOST_IP=$HOST_IP -e ENABLE_ENCRYPT=false 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. In order to register Holmes itself to MSB, the users have to specify the IP address of the host using the ``HOST_IP`` variable. Please note that the ``HOST_IP`` should be the IP address of the host, rather than the IP address of the containers (of which the IP address is allocated by the docker daemon). -``ENABLE_ENCRYPT`` specifies whether HTTPS is enabled. When it is set to "false", only the HTTP schema is allowed. Otherwise, only HTTPS is allowed. - -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 deleted file mode 100644 index 68cd46e..0000000 --- a/docs/platform/log-and-diagnostic-info.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. 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 Honolulu release, the logs are kept inside the docker containers, which means that you can get the log information only when the docker is still running. - -Where to Access Information -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -There are two ways for a user to get the logs. - - -* 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. - -* Get into the docker containers by running ``sudo docker exec -it ${docker-name} sh``. Go to the path ``/var/log/ONAP/holmes/`` and find the logs there. - -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 deleted file mode 100644 index 26e9c75..0000000 --- a/docs/platform/offeredapis.rst +++ /dev/null @@ -1,13 +0,0 @@ -Offered APIs ------------- -.. _offeredapis: - -The rule management module provides the following APIs. - -* Rule Creation -* Rule Update -* Rule Query -* Rule Deletion -* Health Check - -.. swaggerv2doc:: ../../rulemgt/src/main/resources/swagger.json diff --git a/docs/release-notes.rst b/docs/release-notes.rst deleted file mode 100644 index ee323f9..0000000 --- a/docs/release-notes.rst +++ /dev/null @@ -1,381 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. _release_notes: - - -Holmes Rule Management 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. - -Version: 9.0.1 --------------- - -:Release Date: 2021-10-28 - - -**New Features** - -N/A - -**Bug Fixes** - -- `Fixed Vulnerability issues by removing httpclient. `_ - -**Known Issues** - -- If the database is not stable, there may be data/status inconsistency between the rule management module and the engine management module. -- The current horizontal scaling mechanism can not efficiently balance the load. Optimization is needed in the future. - -**Security Issues** - -HOLMES code has been formally scanned during build time using NexusCloud and all critical vulnerabilities have been addressed. - -Quick Links: - - `HOLMES project page `_ - - - `Passing Badge information for HOLMES `_ - - -**Upgrade Notes** - -N/A - - -**Deprecation Notes** - -N/A - - -**Other** - -N/A - -Version: 8.0.1 --------------- - -:Release Date: 2021-04-22 - - -**New Features** - -- `HOLMES-380 `_ Migrate Holmes deployment to Helm - -**Bug Fixes** - -N/A - -**Known Issues** - -- If the database is not stable, there may be data/status inconsistency between the rule management module and the engine management module. -- The current horizontal scaling mechanism can not efficiently balance the load. Optimization is needed in the future. - -**Security Issues** - -HOLMES code has been formally scanned during build time using NexusCloud and all critical vulnerabilities have been addressed. - -Quick Links: - - `HOLMES project page `_ - - - `Passing Badge information for HOLMES `_ - - -**Upgrade Notes** - -N/A - - -**Deprecation Notes** - -N/A - - -**Other** - -N/A - - -Version: 7.0.1 --------------- - -:Release Date: 2020-11-19 - - -**New Features** - -- `HOLMES-312 `_ Alarm Correlation Support in MDONS Close Loop - -**Bug Fixes** - -- `HOLMES-357 `_ Some holmes pods have no limit -- `HOLMES-367 `_ Holmes certificates are expired - -**Known Issues** - -- If the database is not stable, there may be data/status inconsistency between the rule management module and the engine management module. -- The current horizontal scaling mechanism can not efficiently balance the load. Optimization is needed in the future. - -**Security Issues** - -HOLMES code has been formally scanned during build time using NexusCloud and all critical vulnerabilities have been addressed. - -Quick Links: - - `HOLMES project page `_ - - - `Passing Badge information for HOLMES `_ - - -**Upgrade Notes** - -- Upgraded the Java environment from Java 8 to Java 11. -- Changed the base images to onap/integration-java11:7.0.0. - - -**Deprecation Notes** - -N/A - - -**Other** - -N/A - - -Version: 5.0.1 --------------- - -:Release Date: 2019-10-17 - - -**New Features** -N/A - -**Bug Fixes** -N/A - -**Known Issues** - -- If the database is not stable, there may be data/status inconsistency between the rule management module and the engine management module. -- The current horizontal scaling mechanism can not efficiently balance the load. Optimization is needed in the future. - -**Security Issues** - -HOLMES code has been formally scanned during build time using NexusIQ and all Critical vulnerabilities have been addressed, some of the items that remain open have been assessed for risk and determined to be false positive and the rest are planned to be resolved in the next release. - -Quick Links: - - `HOLMES project page `_ - - - `Passing Badge information for HOLMES `_ - - -**Upgrade Notes** - -N/A - - -**Deprecation Notes** - -N/A - - -**Other** - -N/A - -Version: 1.2.6 --------------- - -:Release Date: 2019-06-13 - - -**New Features** -Added some tools to support the extended CCVPN use case: - -- `Rules for CCVEN Extension `_ This feature provides some rules for the extended CCVPN usecase. Users could use the rules as templates to develop their own rules. -- `Updated AAI Assistant Tools for CCVPN Extension `_ Some tools related to the CCVPN usecase have been enhanced in order to support the extended CCVPN usecase. - -**Bug Fixes** - -- `HOLMES-204 `_ Alarms can not be deleted from the DB when they get cleared. -- `HOLMES-223 `_ The "ABATED" messages can not be generated in the control loop. - -**Known Issues** - -- If the database is not stable, there may be data/status inconsistency between the rule management module and the engine management module. -- The current horizontal scaling mechanism can not efficiently balance the load. Optimization is needed in the future. - -**Security Issues** - -HOLMES code has been formally scanned during build time using NexusIQ and all Critical vulnerabilities have been addressed, some of the items that remain open have been assessed for risk and determined to be false positive and the rest are planned to be resolved in the next release. - -Quick Links: - - `HOLMES project page `_ - - - `Passing Badge information for HOLMES `_ - - -**Upgrade Notes** - -N/A - - -**Deprecation Notes** - -N/A - - -**Other** - -N/A - -=========== - -Version: 1.2.0 --------------- - -:Release Date: 2018-11-30 - - -**New Features** -In the Casablanca release, Holmes provides its own GUI for rule management tasks: - -- `UI Deployment `_ This feature provides a graphic user interface for the sake of easiness of rule management. It mainly provides a rule list view and a rule editing page. Users could get an overview of all rules that have been added to Holmes and create/modify them easily by using the GUI provided by this feature. - -Besides, Holmes has been enhanced to be CCVPN use case supportive. CCVPN related assistant tools are added to the common library of Holmes. - -**Bug Fixes** - -- `HOLMES-156 `_ Rules can not be deployed after they've been added/removed from the engine. -- `HOLMES-133 `_ Don't rely on key word 'import' when extracting package name from rule. -- `HOLMES-130 `_ Holmes can not be successfully registered to MSB when trying to register itself with a health check parameter. - -**Known Issues** - -- If the database is not stable, there may be data/status inconsistency between the rule management module and the engine management module. -- The current horizontal scaling mechanism can not efficiently balance the load. Optimization is needed in the future. - -**Security Issues** - -HOLMES code has been formally scanned during build time using NexusIQ and all Critical vulnerabilities have been addressed, items that remain open have been assessed for risk and determined to be false positive. The HOLMES open Critical security vulnerabilities and their risk assessment have been documented as part of the `project `_. - -Quick Links: - - `HOLMES project page `_ - - - `Passing Badge information for HOLMES `_ - - - `Project Vulnerability Review Table for HOLMES `_ - - -**Upgrade Notes** - -N/A - - -**Deprecation Notes** - -N/A - - -**Other** - -N/A - -=========== - - -Version: 1.1.0 --------------- - -:Release Date: 2018-06-07 - - -**New Features** -In the Beijing release, Holmes provides no more functionalites than the Amsterdam release. Its main features remains like follows: - -- `Rule Management `_ The feature provides interfaces for the users to create, query, update and delete rules. In this release, they are used along with the DCAE interfaces to accomplish the deployment (creation/update) of the control loop related rules. - -- `Engine Management `_ The feature is not exposed to the end user directly. It's mainly used internally by Holmes as a container for the execution of rules. It provides interface for rule verification and deployment/un-deployment. - -Besides, Holmes has been enhanced to meet the platform maturity requirements. The enhancement mainly covers: - -- Scaling: Holmes supports horizontal scale-in/scale-out operations in case it is overloaded by too large amounts of data. - -- Security: Holmes has updated all its APIs to support the HTTPS protocol. - -**Bug Fixes** - -N/A - -**Known Issues** - -- If the database is not stable, there may be data/status inconsistency between the rule management module and the engine management module. -- The current horizontal scaling mechanism can not efficiently balance the load. Optimization is needed in the future. - -**Security Issues** - -HOLMES code has been formally scanned during build time using NexusIQ and all Critical vulnerabilities have been addressed, items that remain open have been assessed for risk and determined to be false positive. The HOLMES open Critical security vulnerabilities and their risk assessment have been documented as part of the `project `_. - -Quick Links: - - `HOLMES project page `_ - - - `Passing Badge information for HOLMES `_ - - - `Project Vulnerability Review Table for HOLMES `_ - - -**Upgrade Notes** - -- `HOLMES-99 `_ Updated the Drools engine to Version 6.5.0. -- `HOLMES-104 `_ Update all interfaces to enforce the HTTPS protocal. -- `HOLMES-112 `_ Following the guideline of the Logging Enhancements Project to implement log collection. -- `HOLMES-106 `_ Implemented horizontal scaling. -- `HOLMES-123 `_ Fixed some vulnerability issues identified by Nexus IQ. - - -**Deprecation Notes** - -None of the HTTP APIs provided in the Amsterdam release are available in Beijing anymore. - - -**Other** - -N/A - -=========== - -Version: 1.0.0 --------------- - -:Release Date: 2017-11-16 - - -**New Features** -In the Amsterdam release, Holmes is mainly intended to support the alarm -correlation analysis for the VoLTE scenario. To get us there, Holmes provides -the following features: - -- `Rule Management `_ The feature provides interfaces for the users to create, query, update and delete rules. In this release, they are used along with the DCAE interfaces to accomplish the deployment (creation/update) of the control loop related rules. - -- `Engine Management `_ The feature is not exposed to the end user directly. It's mainly used internally by Holmes as a container for the execution of rules. It provides interface for rule verification and deployment/un-deployment. - -**Bug Fixes** - -This is the initial release. - -**Known Issues** - -If the database is not stable, there may be data/status inconsistency between the rule management module and the engine management module. - -**Security Issues** - -N/A - -**Upgrade Notes** - -N/A - - -End of Release Notes diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt deleted file mode 100644 index b3188dd..0000000 --- a/docs/requirements-docs.txt +++ /dev/null @@ -1,15 +0,0 @@ -tox -Sphinx -doc8 -docutils -setuptools -six -sphinx_rtd_theme>=0.4.3 -sphinxcontrib-blockdiag -sphinxcontrib-needs>=0.2.3 -sphinxcontrib-nwdiag -sphinxcontrib-seqdiag -sphinxcontrib-swaggerdoc -sphinxcontrib-plantuml -sphinx_bootstrap_theme -lfdocs-conf diff --git a/docs/tox.ini b/docs/tox.ini index edac8c3..a538317 100644 --- a/docs/tox.ini +++ b/docs/tox.ini @@ -1,22 +1,77 @@ [tox] minversion = 1.6 -envlist = docs, +envlist = docs,docs-linkcheck skipsdist = true [testenv:docs] basepython = python3 -deps = -r{toxinidir}/requirements-docs.txt +deps = + -r{toxinidir}/etc/requirements.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt commands = - sphinx-build -b html -n -d {envtmpdir}/doctrees ./ {toxinidir}/_build/html - echo "Generated docs available in {toxinidir}/_build/html" + sphinx-build -W -q -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html + echo "Generated docs available in {toxinidir}/docs/_build/html" whitelist_externals = echo git sh +[testenv:docs-templates] +basepython = python3 +deps = + -r{toxinidir}/etc/requirements.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt +commands = + sphinx-build -b html -n -d {envtmpdir}/doctrees -c {toxinidir}/docs ./docs/guides/onap-developer/how-to-use-docs/templates {toxinidir}/docs/_build/html/templates + echo "Generated docs available in {toxinidir}/docs/_build/html/templates" +whitelist_externals = + echo + +[testenv:local] +basepython = python3 +deps = + -r{toxinidir}/etc/requirements.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt +commands = + git submodule update --depth 100 --init + sphinx-build -q -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html + echo "Generated docs available in {toxinidir}/docs/_build/html" +whitelist_externals = + echo + git + [testenv:docs-linkcheck] basepython = python3 -#deps = -r{toxinidir}/requirements-docs.txt -commands = echo "Link Checking not enforced" -#commands = sphinx-build -b linkcheck -d {envtmpdir}/doctrees ./ {toxinidir}/_build/linkcheck -whitelist_externals = echo +deps = + -r{toxinidir}/etc/requirements.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt +commands = sphinx-build -q -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck + +[testenv:spellcheck] +basepython = python3 +deps = + -r{toxinidir}/etc/requirements.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt +commands = + sphinx-build -b spelling -Dextensions=sphinxcontrib.spelling -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/spellcheck + +[testenv:autopep8] +deps = + -r{toxinidir}/etc/requirements.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt +commands = + autopep8 --max-line-length 120 --in-place docs/conf.py + +[testenv:pylint] +deps = + -r{toxinidir}/etc/requirements.txt + -c{toxinidir}/etc/upper-constraints.os.txt + -c{toxinidir}/etc/upper-constraints.onap.txt +commands = + pylint --max-line-length=120 --disable=missing-docstring --reports=y --score=y --output-format=colorized docs/conf.py -- cgit 1.2.3-korg