docs/overview.rst

   1 ..
   2 .. Copyright (c) 2019 AT&T Intellectual Property.
   3 ..
   4 .. Copyright (c) 2019 Nokia.
   5 ..
   6 ..
   7 .. Licensed under the Creative Commons Attribution 4.0 International
   8 ..
   9 .. Public License (the "License"); you may not use this file except
  10 ..
  11 .. in compliance with the License. You may obtain a copy of the License at
  12 ..
  13 ..
  14 ..     https://creativecommons.org/licenses/by/4.0/
  15 ..
  16 ..
  17 .. Unless required by applicable law or agreed to in writing, documentation
  18 ..
  19 .. distributed under the License is distributed on an "AS IS" BASIS,
  20 ..
  21 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  22 ..
  23 .. See the License for the specific language governing permissions and
  24 ..
  25 .. limitations under the License.
  26 ..
  27
  28
  29 VESPA Manager Overview
  30 ======================
  31
  32 The VESPA Manager uses the VES Agent (https://github.com/nokia/ONAP-VESPA) to adapt near-RT RIC internal statistics' collection using Prometheus to scrape metrics from platform and xApp microservices and forward to ONAP or VES Collector via VES interface (VNF event streaming).
  33
  34 The VESPA Manager deployment runs two processes: the VESPA manager and the VES Agent (i.s. VESPA). The VESPA manager starts and configures the VES Agent.
  35 The VES Agent is a service acting as a bridge between Prometheus and ONAP / VES Collector.
  36
  37 Application Metrics Definition
  38 ==============================
  39
  40 The application metrics are defined in the application descriptor. For each counter, the following fields are required in the "metrics" section of the descriptor:
  41
  42 * name - Prometheus name of the counter
  43 * objectName - object name in VES
  44 * objectInstance - object instance in VE
  45
  46 The VESPA manager receives the application metrics configuration from the application manager. It subscribes the app notification messages from the application manager, and after having received one, requests the latest application configuration, creates the VES Agent configuration based on it,
  47 and restarts the VES Agent.
  48
  49 The VES Agent does not report any other metrics to VES.
  50
  51 Prometheus Configuration
  52 ========================
  53
  54 The VES Agent reads the ricComponentName from Prometheus label
  55 "kubernetes_name".
  56
  57 VES Collector Event Format
  58 ==========================
  59
  60 The VES Agent transmits events to the VES Collector in the VES Common Event Format v5.4.1. The Common Event Format is expressed in JSON schema v28.4.1.
  61
  62 VES Event Listener 5.4.1:
  63  earlier under h t t p s://docs.onap.org/en/casablanca/submodules/vnfsdk/model.git/docs/files/VESEventListener.html
  64
  65 JSON schema v28.4.1:
  66 <https://github.com/nokia/ONAP-VESPA/blob/8e9d9e93bb00bed0f5402c9de9502385d5e80acc/doc/CommonEventFormat_28.4.1.json>
  67
  68 Environment Variables
  69 =====================
  70
  71 The VESPA manager container requires the following environment variables:
  72
  73 * VESMGR_VNFNAME - VNF name as a string. Default: Vespa.
  74 * VESMGR_NFNAMINGCODE - NF naming code as a string. Default: ricp.
  75 * VESMGR_HB_INTERVAL - VES heartbeat interval as a string. For example: 30s.
  76 * VESMGR_MEAS_INTERVAL - Measurement interval as a string. For example: 60s.
  77 * VESMGR_PROMETHEUS_ADDR - Prometheus address. For example: h t t p://127.0.0.1:123
  78 * VESMGR_ALERTMANAGER_BIND_ADDR - Bind address to receive alerts from Prometheus AlertManager
  79
  80 * VESMGR_PRICOLLECTOR_ADDR - Primary collector FQDN as a string. For example: ricaux-entry.
  81 * VESMGR_PRICOLLECTOR_PORT - Primary collector port id as an integer. Default: 8443.
  82 * VESMGR_PRICOLLECTOR_SERVERROOT - Path before the /eventListener part of the POST URL as a string.
  83 * VESMGR_PRICOLLECTOR_TOPIC - Primary collector topic as a string.
  84 * VESMGR_PRICOLLECTOR_SECURE - Use HTTPS for VES collector. Possible string values: true or false.
  85 * VESMGR_PRICOLLECTOR_USER - User name as a string.
  86 * VESMGR_PRICOLLECTOR_PASSWORD - Password as a string.
  87 * VESMGR_PRICOLLECTOR_PASSPHASE - Passphrase as a string.
  88
  89 * VESMGR_APPMGRDOMAIN - Application manager domain. This is for testing purposes, only. Default: service-ricplt-appmgr-http.ricplt.svc.cluster.local.
  90
  91 Liveness probe
  92 ==============
  93
  94 The VESPA manager replies to liveness HTTP GET at path /supervision.
  95
  96 Errors
  97 ======
  98
  99 The VESPA manager exits in the following error cases:
 100
 101 * The VES Agent exits
 102 * An unrecoverable system error during the initialization, for example
 103   * Creation of the VES Agent configuration file fails
 104   * Creation of a HTTP request message fails
 105
 106 Unit Tests
 107 ==========
 108
 109 In order to run the VESPA manager unit tests, give the following command:
 110
 111 ```shell
 112 go test ./... -v
 113 ```
 114