diff options
23 files changed, 1096 insertions, 336 deletions
diff --git a/docs/sections/apis/DFC.json b/docs/sections/apis/DFC.json new file mode 100644 index 00000000..08d03993 --- /dev/null +++ b/docs/sections/apis/DFC.json @@ -0,0 +1,621 @@ +{ + "swagger": "2.0", + "info": { + "description": "This page lists all the rest apis for DATAFILE app server.", + "version": "1.0", + "title": "DATAFILE app server" + }, + "host": "localhost:8100", + "basePath": "/", + "tags": [ + { + "name": "heartbeat-controller", + "description": "Heartbeat Controller" + }, + { + "name": "operation-handler", + "description": "Operation Handler" + }, + { + "name": "schedule-controller", + "description": "Schedule Controller" + }, + { + "name": "web-mvc-links-handler", + "description": "Web Mvc Links Handler" + } + ], + "paths": { + "/actuator": { + "get": { + "tags": [ + "web-mvc-links-handler" + ], + "summary": "links", + "operationId": "linksUsingGET", + "produces": [ + "application/json", + "application/vnd.spring-boot.actuator.v2+json" + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object", + "additionalProperties": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/Link" + } + } + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/actuator/health": { + "get": { + "tags": [ + "operation-handler" + ], + "summary": "handle", + "operationId": "handleUsingGET_2", + "produces": [ + "application/json", + "application/vnd.spring-boot.actuator.v2+json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "body", + "required": false, + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/actuator/health/{component}": { + "get": { + "tags": [ + "operation-handler" + ], + "summary": "handle", + "operationId": "handleUsingGET_1", + "produces": [ + "application/json", + "application/vnd.spring-boot.actuator.v2+json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "body", + "required": false, + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/actuator/health/{component}/{instance}": { + "get": { + "tags": [ + "operation-handler" + ], + "summary": "handle", + "operationId": "handleUsingGET", + "produces": [ + "application/json", + "application/vnd.spring-boot.actuator.v2+json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "body", + "required": false, + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/actuator/info": { + "get": { + "tags": [ + "operation-handler" + ], + "summary": "handle", + "operationId": "handleUsingGET_3", + "produces": [ + "application/json", + "application/vnd.spring-boot.actuator.v2+json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "body", + "required": false, + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/actuator/logfile": { + "get": { + "tags": [ + "operation-handler" + ], + "summary": "handle", + "operationId": "handleUsingGET_4", + "produces": [ + "application/octet-stream" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "body", + "required": false, + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/actuator/loggers": { + "get": { + "tags": [ + "operation-handler" + ], + "summary": "handle", + "operationId": "handleUsingGET_6", + "produces": [ + "application/json", + "application/vnd.spring-boot.actuator.v2+json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "body", + "required": false, + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/actuator/loggers/{name}": { + "get": { + "tags": [ + "operation-handler" + ], + "summary": "handle", + "operationId": "handleUsingGET_5", + "produces": [ + "application/json", + "application/vnd.spring-boot.actuator.v2+json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "body", + "required": false, + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + }, + "post": { + "tags": [ + "operation-handler" + ], + "summary": "handle", + "operationId": "handleUsingPOST", + "consumes": [ + "application/json", + "application/vnd.spring-boot.actuator.v2+json" + ], + "produces": [ + "*/*" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "body", + "required": false, + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object" + } + }, + "201": { + "description": "Created" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/actuator/metrics": { + "get": { + "tags": [ + "operation-handler" + ], + "summary": "handle", + "operationId": "handleUsingGET_8", + "produces": [ + "application/json", + "application/vnd.spring-boot.actuator.v2+json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "body", + "required": false, + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/actuator/metrics/{requiredMetricName}": { + "get": { + "tags": [ + "operation-handler" + ], + "summary": "handle", + "operationId": "handleUsingGET_7", + "produces": [ + "application/json", + "application/vnd.spring-boot.actuator.v2+json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "body", + "required": false, + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/heartbeat": { + "get": { + "tags": [ + "heartbeat-controller" + ], + "summary": "Returns liveness of DATAFILE service", + "operationId": "heartbeatUsingGET", + "produces": [ + "*/*" + ], + "responses": { + "200": { + "description": "DATAFILE service is living", + "schema": { + "$ref": "#/definitions/Mono«ResponseEntity«string»»" + } + }, + "401": { + "description": "You are not authorized to view the resource" + }, + "403": { + "description": "Accessing the resource you were trying to reach is forbidden" + }, + "404": { + "description": "The resource you were trying to reach is not found" + } + } + } + }, + "/start": { + "get": { + "tags": [ + "schedule-controller" + ], + "summary": "Start scheduling worker request", + "operationId": "startTasksUsingGET", + "produces": [ + "*/*" + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/Mono«ResponseEntity«string»»" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + }, + "/stopDatafile": { + "get": { + "tags": [ + "schedule-controller" + ], + "summary": "Receiving stop scheduling worker request", + "operationId": "stopTaskUsingGET", + "produces": [ + "*/*" + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/Mono«ResponseEntity«string»»" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + } + } + } + }, + "definitions": { + "Link": { + "type": "object", + "properties": { + "href": { + "type": "string" + }, + "templated": { + "type": "boolean" + } + }, + "title": "Link" + }, + "Map«string,Link»": { + "type": "object", + "title": "Map«string,Link»", + "additionalProperties": { + "$ref": "#/definitions/Link" + } + }, + "Mono«ResponseEntity«string»»": { + "type": "object", + "title": "Mono«ResponseEntity«string»»" + } + } +}
\ No newline at end of file diff --git a/docs/sections/apis/DFC.rst b/docs/sections/apis/DFC.rst index 57e2914c..f345d93f 100644 --- a/docs/sections/apis/DFC.rst +++ b/docs/sections/apis/DFC.rst @@ -2,7 +2,7 @@ DFC (DataFile Collector) ======================== -:Date: 2018-09-21 +:Date: 2019-04-24 .. contents:: :depth: 3 @@ -16,184 +16,11 @@ Component description can be found under `DFC`_. .. _DFC: ../../sections/services/dfc/index.html -Paths -===== +Offered APIs +============ -GET /events/unauthenticated.VES_NOTIFICATION_OUTPUT ---------------------------------------------------- +.. csv-table:: + :header: "API name", "Swagger JSON" + :widths: 10,5 -Description -~~~~~~~~~~~ - -Reads fileReady events from DMaaP (Data Movement as a Platform) - - -Responses -~~~~~~~~~ - -+-----------+---------------------+ -| HTTP Code | Description | -+===========+=====================+ -| **200** | successful response | -+-----------+---------------------+ - - - -POST /publish -------------- - -Description -~~~~~~~~~~~ - -Publish the collected file/s as a stream to DataRouter - - file as stream - - compression - - fileFormatType - - fileFormatVersion - - -Responses -~~~~~~~~~ - -+-----------+---------------------+ -| HTTP Code | Description | -+===========+=====================+ -| **200** | successful response | -+-----------+---------------------+ - -Compiling DFC -============= - -Whole project (top level of DFC directory) and each module (sub module directory) can be compiled using -`mvn clean install` command. - -Configuration file: Config/datafile_endpoints.json - -Maven GroupId: -============== - -org.onap.dcaegen2.collectors - -Maven Parent ArtifactId: -======================== - -dcae-collectors - -Maven Children Artifacts: -========================= - -1. datafile-app-server: DFC server -2. datafile-dmaap-client: Contains implementation of DmaaP client -3. datafile-commons: Common code for whole DFC modules -4. docker-compose: Contains the docker-compose - -Configuration of Certificates in test environment(For FTP over TLS): -==================================================================== - -DFC supports two protocols: FTPES and SFTP. -For FTPES, it is mutual authentication with certificates. -In our test environment, we use vsftpd to simulate xNF, and we generate self-signed -keys & certificates on both vsftpd server and DFC. - -1. Generate key/certificate with openssl for DFC: -------------------------------------------------- -.. code:: bash - - openssl genrsa -out dfc.key 2048 - openssl req -new -out dfc.csr -key dfc.key - openssl x509 -req -days 365 -in dfc.csr -signkey dfc.key -out dfc.crt - -2. Generate key & certificate with openssl for vsftpd: ------------------------------------------------------- -.. code:: bash - - openssl genrsa -out ftp.key 2048 - openssl req -new -out ftp.csr -key ftp.key - openssl x509 -req -days 365 -in ftp.csr -signkey ftp.key -out ftp.crt - -3. Configure java keystore in DFC: ----------------------------------- -We have two keystore files, one for TrustManager, one for KeyManager. - -**For TrustManager:** - -1. First, convert your certificate in a DER format : - - .. code:: bash - - openssl x509 -outform der -in ftp.crt -out ftp.der - -2. And after, import it in the keystore : - - .. code:: bash - - keytool -import -alias ftp -keystore ftp.jks -file ftp.der - -**For KeyManager:** - -1. First, create a jks keystore: - - .. code:: bash - - keytool -keystore dfc.jks -genkey -alias dfc - -2. Second, import dfc.crt and dfc.key to dfc.jks. This is a bit troublesome. - - 1). Step one: Convert x509 Cert and Key to a pkcs12 file - - .. code:: bash - - openssl pkcs12 -export -in dfc.crt -inkey dfc.key -out dfc.p12 -name [some-alias] - - Note: Make sure you put a password on the p12 file - otherwise you'll get a null reference exception when yy to import it. (In case anyone else had this headache). - - Note 2: You might want to add the -chainoption to preserve the full certificate chain. - - 2). Step two: Convert the pkcs12 file to a java keystore: - - .. code:: bash - - keytool -importkeystore -deststorepass [changeit] -destkeypass [changeit] -destkeystore dfc.jks -srckeystore dfc.p12 -srcstoretype PKCS12 -srcstorepass [some-password] -alias [some-alias] - -3. Finished - -4. Configure vsftpd: --------------------- - update /etc/vsftpd/vsftpd.conf: - - .. code-block:: bash - - rsa_cert_file=/etc/ssl/private/ftp.crt - rsa_private_key_file=/etc/ssl/private/ftp.key - ssl_enable=YES - allow_anon_ssl=NO - force_local_data_ssl=YES - force_local_logins_ssl=YES - - ssl_tlsv1=YES - ssl_sslv2=YES - ssl_sslv3=YES - - require_ssl_reuse=NO - ssl_ciphers=HIGH - - require_cert=YES - ssl_request_cert=YES - ca_certs_file=/home/vsftpd/myuser/dfc.crt - -5. Configure config/datafile_endpoints.json: --------------------------------------------- - Update the file accordingly: - - .. code-block:: javascript - - "ftpesConfiguration": { - "keyCert": "/config/dfc.jks", - "keyPassword": "[yourpassword]", - "trustedCA": "/config/ftp.jks", - "trustedCAPassword": "[yourpassword]" - } - -6. This has been tested with vsftpd and dfc, with self-signed certificates. ---------------------------------------------------------------------------- - In real deployment, we should use ONAP-CA signed certificate for DFC, and vendor-CA signed certificate for xNF + "Datafile Collector API", ":download:`link <DFC.json>`" diff --git a/docs/sections/apis/ves-hv/index.rst b/docs/sections/apis/ves-hv/index.rst index d87d1aa0..c61c1e16 100644 --- a/docs/sections/apis/ves-hv/index.rst +++ b/docs/sections/apis/ves-hv/index.rst @@ -58,6 +58,9 @@ By default, **HV-VES** will use routing defined in **k8s-hv-ves.yaml-template** - perf3gpp -> HV_VES_PERF3GPP + +.. _supported_domains: + Supported domains ================= @@ -65,7 +68,7 @@ Domains supported by **HV-VES**: - perf3gpp -For domains descriptions, see :ref:`supported_domains` +For domains descriptions, see :ref:`domains_supported_by_hvves` .. _hv_ves_behaviors: diff --git a/docs/sections/apis/ves-hv/supported-domains.rst b/docs/sections/apis/ves-hv/supported-domains.rst index d1badaa6..68d5d226 100644 --- a/docs/sections/apis/ves-hv/supported-domains.rst +++ b/docs/sections/apis/ves-hv/supported-domains.rst @@ -1,7 +1,7 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 -.. _supported_domains: +.. _domains_supported_by_hvves: Domains supported by HV-VES =========================== diff --git a/docs/sections/services/bbs-event-processor/installation.rst b/docs/sections/services/bbs-event-processor/installation.rst index 5c00c0d3..242f9f9b 100644 --- a/docs/sections/services/bbs-event-processor/installation.rst +++ b/docs/sections/services/bbs-event-processor/installation.rst @@ -7,58 +7,77 @@ The following docker-compose-yaml file shows a default configuration. The file c .. code-block:: yaml -version: '3' -services: - bbs-event-processor: - image: onap/org.onap.dcaegen2.services.components.bbs-event-processor:latest - container_name: bbs-event-processor - hostname: bbs-event-processor - ports: - - 32100:8100 - environment: - CONFIGS_DMAAP_CONSUMER_RE-REGISTRATION_DMAAPHOSTNAME: 10.133.115.190 - CONFIGS_DMAAP_CONSUMER_RE-REGISTRATION_DMAAPPORTNUMBER: 30227 - CONFIGS_DMAAP_CONSUMER_RE-REGISTRATION_DMAAPTOPICNAME: /events/unauthenticated.PNF_UPDATE - CONFIGS_DMAAP_CONSUMER_RE-REGISTRATION_CONSUMERGROUP: foo - CONFIGS_DMAAP_CONSUMER_RE-REGISTRATION_CONSUMERID: bar - CONFIGS_DMAAP_CONSUMER_CPE-AUTHENTICATION_DMAAPHOSTNAME: 10.133.115.190 - CONFIGS_DMAAP_CONSUMER_CPE-AUTHENTICATION_DMAAPPORTNUMBER: 30227 - CONFIGS_DMAAP_CONSUMER_CPE-AUTHENTICATION_DMAAPTOPICNAME: /events/unauthenticated.CPE_AUTHENTICATION - CONFIGS_DMAAP_CONSUMER_CPE-AUTHENTICATION_CONSUMERGROUP: foo - CONFIGS_DMAAP_CONSUMER_CPE-AUTHENTICATION_CONSUMERID: bar - CONFIGS_DMAAP_PRODUCER_DMAAPHOSTNAME: 10.133.115.190 - CONFIGS_DMAAP_PRODUCER_DMAAPPORTNUMBER: 30227 - CONFIGS_DMAAP_PRODUCER_DMAAPTOPICNAME: /events/unauthenticated.DCAE_CL_OUTPUT - CONFIGS_AAI_CLIENT_AAIHOST: 10.133.115.190 - CONFIGS_AAI_CLIENT_AAIPORT: 30233 - CONFIGS_APPLICATION_PIPELINESPOLLINGINTERVALSEC: 30 - CONFIGS_APPLICATION_PIPELINESTIMEOUTSEC: 15 - CONFIGS_APPLICATION_RE-REGISTRATION_POLICYSCOPE: policyScope - CONFIGS_APPLICATION_RE-REGISTRATION_CLCONTROLNAME: controName - CONFIGS_APPLICATION_CPE-AUTHENTICATION_POLICYSCOPE: policyScope - CONFIGS_APPLICATION_CPE-AUTHENTICATION_CLCONTROLNAME: controlName - LOGGING_LEVEL_ORG_ONAP_BBS: TRACE + version: '3' + services: + bbs-event-processor: + image: onap/org.onap.dcaegen2.services.components.bbs-event-processor:latest + container_name: bbs-event-processor + hostname: bbs-event-processor + ports: + - 32100:8100 + environment: + CONFIGS_DMAAP_CONSUMER_RE-REGISTRATION_DMAAPHOSTNAME: 10.133.115.190 + CONFIGS_DMAAP_CONSUMER_RE-REGISTRATION_DMAAPPORTNUMBER: 30227 + CONFIGS_DMAAP_CONSUMER_RE-REGISTRATION_DMAAPTOPICNAME: /events/unauthenticated.PNF_UPDATE + CONFIGS_DMAAP_CONSUMER_RE-REGISTRATION_CONSUMERGROUP: foo + CONFIGS_DMAAP_CONSUMER_RE-REGISTRATION_CONSUMERID: bar + CONFIGS_DMAAP_CONSUMER_CPE-AUTHENTICATION_DMAAPHOSTNAME: 10.133.115.190 + CONFIGS_DMAAP_CONSUMER_CPE-AUTHENTICATION_DMAAPPORTNUMBER: 30227 + CONFIGS_DMAAP_CONSUMER_CPE-AUTHENTICATION_DMAAPTOPICNAME: /events/unauthenticated.CPE_AUTHENTICATION + CONFIGS_DMAAP_CONSUMER_CPE-AUTHENTICATION_CONSUMERGROUP: foo + CONFIGS_DMAAP_CONSUMER_CPE-AUTHENTICATION_CONSUMERID: bar + CONFIGS_DMAAP_PRODUCER_DMAAPHOSTNAME: 10.133.115.190 + CONFIGS_DMAAP_PRODUCER_DMAAPPORTNUMBER: 30227 + CONFIGS_DMAAP_PRODUCER_DMAAPTOPICNAME: /events/unauthenticated.DCAE_CL_OUTPUT + CONFIGS_AAI_CLIENT_AAIHOST: 10.133.115.190 + CONFIGS_AAI_CLIENT_AAIPORT: 30233 + CONFIGS_APPLICATION_PIPELINESPOLLINGINTERVALSEC: 30 + CONFIGS_APPLICATION_PIPELINESTIMEOUTSEC: 15 + CONFIGS_APPLICATION_RE-REGISTRATION_POLICYSCOPE: policyScope + CONFIGS_APPLICATION_RE-REGISTRATION_CLCONTROLNAME: controName + CONFIGS_APPLICATION_CPE-AUTHENTICATION_POLICYSCOPE: policyScope + CONFIGS_APPLICATION_CPE-AUTHENTICATION_CLCONTROLNAME: controlName + LOGGING_LEVEL_ORG_ONAP_BBS: TRACE For Dublin release, it will be a DCAE component that can dynamically be deployed via Cloudify blueprint installation. Steps to deploy are shown below - Transfer blueprint component file in DCAE bootstrap POD under /blueprints directory. Blueprint can be found in - https://gerrit.onap.org/r/gitweb?p=dcaegen2/services.git;a=blob_plain;f=components/bbs-event-processor/dpo/blueprints/k8s-bbs-event-processor.yaml-template;hb=refs/heads/master + + https://gerrit.onap.org/r/gitweb?p=dcaegen2/services.git;a=blob_plain;f=components/bbs-event-processor/dpo/blueprints/k8s-bbs-event-processor.yaml-template;hb=refs/heads/master - Transfer blueprint component inputs file in DCAE bootstrap POD under / directory. Blueprint inputs file can be found in - https://gerrit.onap.org/r/gitweb?p=dcaegen2/services.git;a=blob_plain;f=components/bbs-event-processor/dpo/blueprints/bbs-event-processor-input.yaml;h=36e69cf64bee3b46ee2e1b95f1a16380b7046482;hb=refs/heads/master + + https://gerrit.onap.org/r/gitweb?p=dcaegen2/services.git;a=blob_plain;f=components/bbs-event-processor/dpo/blueprints/bbs-event-processor-input.yaml;hb=refs/heads/master - Enter the Bootstrap POD - Validate blueprint - cfy blueprints validate /blueprints/k8s-bbs-event-processor.yaml-template + .. code-block:: bash + + cfy blueprints validate /blueprints/k8s-bbs-event-processor.yaml-template - Upload validated blueprint - cfy blueprints upload -b bbs-ep /blueprints/k8s-bbs-event-processor.yaml-template + .. code-block:: bash + + + cfy blueprints upload -b bbs-ep /blueprints/k8s-bbs-event-processor.yaml-template - Create deployment - cfy deployments create -b bbs-ep -i /bbs-event-processor-input.yaml bbs-ep + .. code-block:: bash + + + cfy deployments create -b bbs-ep -i /bbs-event-processor-input.yaml bbs-ep - Deploy blueprint - cfy executions start -d bbs-ep install + .. code-block:: bash + + + cfy executions start -d bbs-ep install To undeploy BBS-ep, steps are shown below -- Validate blueprint by running command - cfy uninstall bbs-ep -- Validate blueprint by running command - cfy blueprints delete bbs-ep
\ No newline at end of file +- Uninstall running BBS-ep and delete deployment + .. code-block:: bash + + + cfy uninstall bbs-ep +- Delete blueprint + .. code-block:: bash + + + cfy blueprints delete bbs-ep
\ No newline at end of file diff --git a/docs/sections/services/dfc/architecture.rst b/docs/sections/services/dfc/architecture.rst index 73597541..ac0c8d14 100644 --- a/docs/sections/services/dfc/architecture.rst +++ b/docs/sections/services/dfc/architecture.rst @@ -39,4 +39,20 @@ The event is received from the Message Router (MR), the files are fetched from a (DR). Both fetching of a file and publishing is retried a number of times with an increasing delay between each attempt. After a number of attempts, the DFC will log an error message and give up. Failing of processing of one file does not -affect the handling of others.
\ No newline at end of file +affect the handling of others. + +Maven GroupId: +============== + +org.onap.dcaegen2.collectors + +Maven Parent ArtifactId: +======================== + +dcae-collectors + +Maven Children Artifacts: +========================= + +1. datafile-app-server: DFC server + diff --git a/docs/sections/services/dfc/certificates.rst b/docs/sections/services/dfc/certificates.rst new file mode 100644 index 00000000..17bfb2f3 --- /dev/null +++ b/docs/sections/services/dfc/certificates.rst @@ -0,0 +1,115 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Certificates +============ + +Configuration of Certificates in test environment(For FTP over TLS): + +DFC supports two protocols: FTPES and SFTP. +For FTPES, it is mutual authentication with certificates. +In our test environment, we use vsftpd to simulate xNF, and we generate self-signed +keys & certificates on both vsftpd server and DFC. + +1. Generate key/certificate with openssl for DFC: +------------------------------------------------- +.. code:: bash + + openssl genrsa -out dfc.key 2048 + openssl req -new -out dfc.csr -key dfc.key + openssl x509 -req -days 365 -in dfc.csr -signkey dfc.key -out dfc.crt + +2. Generate key & certificate with openssl for vsftpd: +------------------------------------------------------ +.. code:: bash + + openssl genrsa -out ftp.key 2048 + openssl req -new -out ftp.csr -key ftp.key + openssl x509 -req -days 365 -in ftp.csr -signkey ftp.key -out ftp.crt + +3. Configure java keystore in DFC: +---------------------------------- +We have two keystore files, one for TrustManager, one for KeyManager. + +**For TrustManager:** + +1. First, convert your certificate in a DER format : + + .. code:: bash + + openssl x509 -outform der -in ftp.crt -out ftp.der + +2. And after, import it in the keystore : + + .. code:: bash + + keytool -import -alias ftp -keystore ftp.jks -file ftp.der + +**For KeyManager:** + +1. First, create a jks keystore: + + .. code:: bash + + keytool -keystore dfc.jks -genkey -alias dfc + +2. Second, import dfc.crt and dfc.key to dfc.jks. This is a bit troublesome. + + 1). Step one: Convert x509 Cert and Key to a pkcs12 file + + .. code:: bash + + openssl pkcs12 -export -in dfc.crt -inkey dfc.key -out dfc.p12 -name [some-alias] + + Note: Make sure you put a password on the p12 file - otherwise you'll get a null reference exception when you try to import it. + + Note 2: You might want to add the -chainoption to preserve the full certificate chain. + + 2). Step two: Convert the pkcs12 file to a java keystore: + + .. code:: bash + + keytool -importkeystore -deststorepass [changeit] -destkeypass [changeit] -destkeystore dfc.jks -srckeystore dfc.p12 -srcstoretype PKCS12 -srcstorepass [some-password] -alias [some-alias] + +3. Finished + +4. Configure vsftpd: +-------------------- + update /etc/vsftpd/vsftpd.conf: + + .. code-block:: bash + + rsa_cert_file=/etc/ssl/private/ftp.crt + rsa_private_key_file=/etc/ssl/private/ftp.key + ssl_enable=YES + allow_anon_ssl=NO + force_local_data_ssl=YES + force_local_logins_ssl=YES + + ssl_tlsv1=YES + ssl_sslv2=YES + ssl_sslv3=YES + + require_ssl_reuse=NO + ssl_ciphers=HIGH + + require_cert=YES + ssl_request_cert=YES + ca_certs_file=/home/vsftpd/myuser/dfc.crt + +5. Configure config/datafile_endpoints.json: +-------------------------------------------- + Update the file accordingly: + + .. code-block:: javascript + + "ftpesConfiguration": { + "keyCert": "/config/dfc.jks", + "keyPassword": "[yourpassword]", + "trustedCA": "/config/ftp.jks", + "trustedCAPassword": "[yourpassword]" + } + +6. This has been tested with vsftpd and dfc, with self-signed certificates. +--------------------------------------------------------------------------- + In real deployment, we should use ONAP-CA signed certificate for DFC, and vendor-CA signed certificate for xNF diff --git a/docs/sections/services/dfc/configuration.rst b/docs/sections/services/dfc/configuration.rst index 22f50eeb..b8d0df95 100644 --- a/docs/sections/services/dfc/configuration.rst +++ b/docs/sections/services/dfc/configuration.rst @@ -7,6 +7,16 @@ Configuration **datafile** configuration is controlled via a single JSON file called datafile_endpoints.json.
This is located under datafile-app-server/config.
+Compiling DFC
+=============
+
+Whole project (top level of DFC directory) and each module (sub module directory) can be compiled using
+`mvn clean install` command.
+
+Configuration file: Config/datafile_endpoints.json
+
+
+
JSON CONFIGURATION EXPLAINED
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/docs/sections/services/dfc/consumedapis.rst b/docs/sections/services/dfc/consumedapis.rst new file mode 100644 index 00000000..0ab10498 --- /dev/null +++ b/docs/sections/services/dfc/consumedapis.rst @@ -0,0 +1,72 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Paths +===== + +GET /events/unauthenticated.VES_NOTIFICATION_OUTPUT +--------------------------------------------------- + +Description +~~~~~~~~~~~ + +Reads fileReady events from DMaaP (Data Movement as a Platform) + + +Responses +~~~~~~~~~ + ++-----------+---------------------+ +| HTTP Code | Description | ++===========+=====================+ +| **200** | successful response | ++-----------+---------------------+ + +GET /FEEDLOG_TOPIC/DEFAULT_FEED_ID?type=pub&filename=FILENAME +------------- + +Description +~~~~~~~~~~~ + +Querying the Data Router to check whether a file has been published previously. + +Responses +~~~~~~~~~ + ++-----------+------------+-----------------------+ +| HTTP Code | Body | Description | ++===========+============+=======================+ +| **400** | NA | error in query | ++-----------+------------+-----------------------+ +| **200** | [] | Not published yet | ++-----------+------------+-----------------------+ +| **200** | [$FILENAME]| Already published | ++-----------+------------+-----------------------+ + +POST /publish +------------- + +Description +~~~~~~~~~~~ + +Publish the collected file/s as a stream to DataRouter + - file as stream + - compression + - fileFormatType + - fileFormatVersion + - productName + - vendorName + - lastEpochMicrosec + - sourceName + - startEpochMicrosec + - timeZoneOffset + + +Responses +~~~~~~~~~ + ++-----------+---------------------+ +| HTTP Code | Description | ++===========+=====================+ +| **200** | successful response | ++-----------+---------------------+
\ No newline at end of file diff --git a/docs/sections/services/dfc/index.rst b/docs/sections/services/dfc/index.rst index 176c403c..780d63fc 100644 --- a/docs/sections/services/dfc/index.rst +++ b/docs/sections/services/dfc/index.rst @@ -14,6 +14,8 @@ DATAFILE COLLECTOR MS (DFC) ./delivery.rst
./logging.rst
./installation.rst
+ ./certificates.rst
./configuration.rst
+ ./consumedapis.rst
./administration.rst
./release-notes.rst
diff --git a/docs/sections/services/ves-hv/architecture.rst b/docs/sections/services/ves-hv/architecture.rst index 986e8bb3..1812f4ee 100644 --- a/docs/sections/services/ves-hv/architecture.rst +++ b/docs/sections/services/ves-hv/architecture.rst @@ -12,7 +12,7 @@ High Volume Collector is deployed with DCAEGEN2 via OOM Helm charts and Cloudify Input messages come from TCP interface and Wire Transfer Protocol. Each frame includes Google Protocol Buffers (GPB) encoded payload. Based on information provided in CommonEventHeader, domain messages are validated and published to specific Kafka topic in DMaaP. -.. image:: ONAP_VES_HV_Architecture.png +.. image:: resources/ONAP_VES_HV_Architecture.png Messages published in DMaaP's Kafka topic will be consumed by DCAE analytics application or other ONAP component that consumes messages from DMaaP/Kafka. DMaaP serves direct access to Kafka allowing other analytics applications to utilize its data. diff --git a/docs/sections/services/ves-hv/deployment.rst b/docs/sections/services/ves-hv/deployment.rst index 07d26b94..3a14eb18 100644 --- a/docs/sections/services/ves-hv/deployment.rst +++ b/docs/sections/services/ves-hv/deployment.rst @@ -7,83 +7,106 @@ Deployment ============ -To run HV-VES Collector container, you need to specify required parameters by passing them as command -line arguments either by using long form (--long-form) or short form (-s) followed by argument if needed. +To run HV-VES Collector container you need to specify required command line options and environment variables. -All parameters can also be configured by specifying environment variables. These variables have to be named after command line option name -rewritten using `UPPER_SNAKE_CASE` and prepended with `VESHV_` prefix, for example `VESHV_LISTEN_PORT`. +Command line parameters can be specified either by using long form (--long-form) or short form (-s) followed by argument if needed (see `Arg` column in table below). These parameters can be omitted if corresponding environment variables are set. These variables are named after command line option name rewritten using `UPPER_SNAKE_CASE` and prepended with `VESHV_` prefix, for example `VESHV_CONFIGURATION_FILE`. -Command line options have precedence over environment variables. +Command line options have precedence over environment variables in cases when both are present. -+-------------+------------+-------------------+----------+-----+-------------------------------------------------+ -| Long form | Short form | Env form | Required | Arg | Description | -+=============+============+===================+==========+=====+=================================================+ -| listen-port | p | VESHV_LISTEN_PORT | yes | yes | Port on which HV-VES listens internally | -+-------------+------------+-------------------+----------+-----+-------------------------------------------------+ -| config-url | c | VESHV_CONFIG_URL | yes | yes | URL of HV-VES configuration on Consul service | -+-------------+------------+-------------------+----------+-----+-------------------------------------------------+ +Currently HV-VES requires single command line parameter which points to base configuration file. -HV-VES requires also to specify if SSL should be used when handling incoming TCP connections. -This can be done by passing the flag below to the command line. +.. csv-table:: + :widths: auto + :delim: ; + :header: Long form , Short form , Arg , Env form , Description -+-------------+------------+-------------------+----------+-----+-------------------------------------------------+ -| Long form | Short form | Env form | Required | Arg | Description | -+=============+============+===================+==========+=====+=================================================+ -| ssl-disable | l | VESHV_SSL_DISABLE | no | no | Disables SSL encryption | -+-------------+------------+-------------------+----------+-----+-------------------------------------------------+ + configuration-file ; c ; yes ; VESHV_CONFIGURATION_FILE ; Path to JSON file containing HV-VES configuration +Environment variables that are required by HV-VES are used by collector for provisioning of run-time configuration and are usually provided by DCAE platform. -Minimal command for running the container: +.. csv-table:: + :widths: auto + :delim: ; + :header: Environment variable name , Description -.. code-block:: bash + CONSUL_HOST ; Hostname under which Consul service is available + CONFIG_BINDING_SERVICE ; Hostname under which Config Binding Service is available + HOSTNAME ; Configuration key of HV-VES as seen by CBS, usually *dcae-hv-ves-collector* + +There is also optional command line parameter which configures container-internal port for Healthcheck Server API (see :ref:`healthcheck_and_monitoring`). + +.. csv-table:: + :widths: auto + :delim: ; + :header: Long form , Short form , Arg , Env form , Description + + health-check-api-port ; H ; yes ; VESHV_HEALTH_CHECK_API_PORT ; Health check rest api listen port + +.. _configuration_file: + +Configuration file +------------------ + +File must provide base configuration for HV-VES Collector in JSON format. + +Some entries in configuration can also be obtained from Config Binding Service (see :ref:`run_time_configuration`). **Every entry defined in configuration file will be OVERRIDEN if it is also present in run-time configuration.** + +Following JSON shows every possible configuration option. Default file shipped with HV-VES container can be found in the collector's repository (see :ref:`repositories`). + +.. literalinclude:: resources/base-configuration.json + :language: json + + +The configuration is split into smaller sections. +Tables show restrictions on fields in file configuration and short description. + +.. csv-table:: + :widths: auto + :delim: ; + :header-rows: 2 + + Server + Key ; Value type ; Description + server.listenPort ; number ; Port on which HV-VES listens internally + server.idleTimeoutSec ; number ; Idle timeout for remote hosts. After given time without any data exchange, the connection might be closed + +.. csv-table:: + :widths: auto + :delim: ; + :header-rows: 2 + + Config Binding Service + Key ; Value type ; Description + cbs.firstRequestDelaySec ; number ; Delay of first request to Config Binding Service in seconds + cbs.requestIntervalSec ; number ; Interval of configuration requests in seconds + +.. csv-table:: + :widths: auto + :delim: ; + :header-rows: 2 + + Security + Key ; Value type ; Description + security.sslDisable ; boolean ; Disables SSL encryption + security.keys.keyStoreFile ; String ; Key store path used in HV-VES incoming connections + security.keys.keyStorePasswordFile ; String ; Key store password file used in HV-VES incoming connections + security.keys.trustStoreFile ; String ; Path to file with trusted certificates bundle used in HV-VES incoming connections + security.keys.trustStorePasswordFile ; String ; Trust store password file used in HV-VES incoming connections + +All security entries are mandatory with `security.sslDisable` set to `false`. Otherwise only `security.sslDisable` needs to be specified. If `security.sslDisable` flag is missing, then it is interpreted same as it would be set to `false`. + +.. csv-table:: + :widths: auto + :delim: ; + :header-rows: 2 + + Uncategorized + Key ; Value type ; Description + logLevel ; String ; Log level on which HV-VES publishes all log messages. Valid argument values are (case insensitive): ERROR, WARN, INFO, DEBUG, TRACE. - docker run nexus3.onap.org:10001/onap/org.onap.dcaegen2.collectors.hv-ves.hv-collector-main --listen-port 6061 --config-url http://consul:8500/v1/kv/dcae-hv-ves-collector --ssl-disable - -Optional configuration parameters: - -+-----------------------+------------+----------------------------+----------+-----+-----------------+-------------------------------------------------------+ -| Long form | Short form | Env form | Required | Arg | Default | Description | -+=======================+============+============================+==========+=====+=================+=======================================================+ -| health-check-api-port | H | VESHV_HEALTHCHECK_API_PORT | no | yes | 6060 | Health check REST API listen port | -+-----------------------+------------+----------------------------+----------+-----+-----------------+-------------------------------------------------------+ -| first-request-delay | d | VESHV_FIRST_REQUEST_DELAY | no | yes | 10 | Delay of first request to Consul service in seconds | -+-----------------------+------------+----------------------------+----------+-----+-----------------+-------------------------------------------------------+ -| request-interval | I | VESHV_REQUEST_INTERVAL | no | yes | 5 | Interval of Consul configuration requests in seconds | -+-----------------------+------------+----------------------------+----------+-----+-----------------+-------------------------------------------------------+ -| idle-timeout-sec | i | VESHV_IDLE_TIMEOUT_SEC | no | yes | 60 | Idle timeout for remote hosts. After given time | -| | | | | | | without any data exchange, the connection | -| | | | | | | might be closed. | -+-----------------------+------------+----------------------------+----------+-----+-----------------+-------------------------------------------------------+ -| max-payload-size | m | VESHV_MAX_PAYLOAD_SIZE | no | yes | 1048576 (1 MiB) | Maximum supported payload size in bytes | -+-----------------------+------------+----------------------------+----------+-----+-----------------+-------------------------------------------------------+ -| log-level | ll | VESHV_LOG_LEVEL | no | yes | INFO | Log level on which HV-VES publishes all log messages | -| | | | | | | Valid argument values are (case insensitive): ERROR, | -| | | | | | | WARN, INFO, DEBUG, TRACE. | -+-----------------------+------------+----------------------------+----------+-----+-----------------+-------------------------------------------------------+ - -As part of experimental API if you do not specify `ssl-disable` flag, there is need to specify additional -parameters for security configuration. - -+-----------------------+------------+----------------------------+----------+-----+------------------------+--------------------------------------------------------------+ -| Long form | Short form | Env form | Required | Arg | Default | Description | -+=======================+============+============================+==========+=====+========================+==============================================================+ -| key-store | k | VESHV_KEY_STORE | no | yes | /etc/ves-hv/server.p12 | Key store in PKCS12 format path | -+-----------------------+------------+----------------------------+----------+-----+------------------------+--------------------------------------------------------------+ -| key-store-password | kp | VESHV_KEY_STORE_PASSWORD | no | yes | | Key store password | -+-----------------------+------------+----------------------------+----------+-----+------------------------+--------------------------------------------------------------+ -| trust-store | t | VESHV_TRUST_STORE | no | yes | /etc/ves-hv/trust.p12 | File with trusted certificate bundle in PKCS12 format path | -+-----------------------+------------+----------------------------+----------+-----+------------------------+--------------------------------------------------------------+ -| trust-store-password | tp | VESHV_TRUST_STORE_PASSWORD | no | yes | | Trust store password | -+-----------------------+------------+----------------------------+----------+-----+------------------------+--------------------------------------------------------------+ - -Passwords are mandatory without ssl-disable flag. If key-store or trust-store location is not specified, HV-VES will try to read them from default locations. - -These parameters can be configured either by passing command line option during `docker run` call or -by specifying environment variables named after command line option name -rewritten using `UPPER_SNAKE_CASE` and prepended with `VESHV_` prefix e.g. `VESHV_LISTEN_PORT`. Horizontal Scaling -================== +------------------ Kubernetes command line tool (`kubectl`) is recommended for manual horizontal scaling of HV-VES Collector. diff --git a/docs/sections/services/ves-hv/design.rst b/docs/sections/services/ves-hv/design.rst index a6c2b864..fb4fa2c7 100644 --- a/docs/sections/services/ves-hv/design.rst +++ b/docs/sections/services/ves-hv/design.rst @@ -33,13 +33,13 @@ The proto file (with the VES CommonHeader) comes with a binary-type **Payload** Domain-specific data are encoded as well with GPB. A domain-specific proto file is required to decode the data. This domain-specific proto has to be shared with analytics applications - HV-VES does not analyze domain-specific data. -In order to support the RT-PM use-case, HV-VES includes a **perf3gpp** domain proto file. Within this domain, high volume data are expected to be reported to HV-VES collector. +In order to support the RT-PM use-case, HV-VES uses a **perf3gpp** domain proto file. Within this domain, high volume data are expected to be reported to HV-VES collector. Additional domains can be defined based on existing VES domains (like Fault, Heartbeat) or completely new domains. New domains can be added when needed. GPB proto files are backwards compatible, and a new domain can be added without affecting existing systems. Analytics applications have to be equipped with the new domain-specific proto file as well. -Currently, these additional, domain specific proto files can be added to respective repos of HV-VES collector. +Currently, these additional, domain specific proto files can be added to hv-ves-client protobuf library repository (artifactId: hvvesclient-protobuf). Implementation details ---------------------- diff --git a/docs/sections/services/ves-hv/example-event.rst b/docs/sections/services/ves-hv/example-event.rst index 3a335395..a413d401 100644 --- a/docs/sections/services/ves-hv/example-event.rst +++ b/docs/sections/services/ves-hv/example-event.rst @@ -11,5 +11,5 @@ The message consists of several parts. Each part is encoded in a different way. Values of fields can be changed according to types specified in noted definition files. -.. literalinclude:: WTP.yaml +.. literalinclude:: resources/WTP.yaml :language: yaml diff --git a/docs/sections/services/ves-hv/healthcheck-and-monitoring.rst b/docs/sections/services/ves-hv/healthcheck-and-monitoring.rst index 18333778..9d35e1ef 100644 --- a/docs/sections/services/ves-hv/healthcheck-and-monitoring.rst +++ b/docs/sections/services/ves-hv/healthcheck-and-monitoring.rst @@ -9,7 +9,7 @@ Healthcheck and Monitoring Healthcheck ----------- Inside HV-VES docker container runs a small HTTP service for healthcheck. Port for healthchecks can be configured -at deployment using ``--health-check-api-port`` command line option or via `VESHV_HEALTHCHECK_API_PORT` environment variable (for details see :ref:`deployment`). +at deployment using command line (for details see :ref:`deployment`). This service exposes endpoint **GET /health/ready** which returns a **HTTP 200 OK** when HV-VES is healthy and ready for connections. Otherwise it returns a **HTTP 503 Service Unavailable** message with a short reason of unhealthiness. @@ -90,4 +90,4 @@ JVM metrics: Sample response for **GET monitoring/prometheus**: -.. literalinclude:: metrics_sample_response.txt +.. literalinclude:: resources/metrics_sample_response.txt diff --git a/docs/sections/services/ves-hv/index.rst b/docs/sections/services/ves-hv/index.rst index 5bb83ddc..144f557e 100644 --- a/docs/sections/services/ves-hv/index.rst +++ b/docs/sections/services/ves-hv/index.rst @@ -29,11 +29,11 @@ High Volume VES Collector overview and functions architecture design - run-time-configuration repositories deployment - troubleshooting + run-time-configuration HV-VES Offered APIs <../../apis/ves-hv/index> authorization example-event healthcheck-and-monitoring + troubleshooting diff --git a/docs/sections/services/ves-hv/ONAP_VES_HV_Architecture.png b/docs/sections/services/ves-hv/resources/ONAP_VES_HV_Architecture.png Binary files differindex 7652b970..7652b970 100644 --- a/docs/sections/services/ves-hv/ONAP_VES_HV_Architecture.png +++ b/docs/sections/services/ves-hv/resources/ONAP_VES_HV_Architecture.png diff --git a/docs/sections/services/ves-hv/WTP.yaml b/docs/sections/services/ves-hv/resources/WTP.yaml index 835ab309..835ab309 100644 --- a/docs/sections/services/ves-hv/WTP.yaml +++ b/docs/sections/services/ves-hv/resources/WTP.yaml diff --git a/docs/sections/services/ves-hv/resources/base-configuration.json b/docs/sections/services/ves-hv/resources/base-configuration.json new file mode 100644 index 00000000..6580287d --- /dev/null +++ b/docs/sections/services/ves-hv/resources/base-configuration.json @@ -0,0 +1,12 @@ +{ + "logLevel": "INFO", + "server.listenPort": 6061, + "server.idleTimeoutSec": 60, + "cbs.firstRequestDelaySec": 10, + "cbs.requestIntervalSec": 5, + "security.sslDisable": false, + "security.keys.keyStoreFile": "/etc/ves-hv/ssl/server.p12", + "security.keys.keyStorePasswordFile": "/etc/ves-hv/ssl/server.pass", + "security.keys.trustStoreFile": "/etc/ves-hv/ssl/trust.p12", + "security.keys.trustStorePasswordFile": "/etc/ves-hv/ssl/trust.pass" +}
\ No newline at end of file diff --git a/docs/sections/services/ves-hv/resources/blueprint-snippet.yaml b/docs/sections/services/ves-hv/resources/blueprint-snippet.yaml new file mode 100644 index 00000000..912c0c5a --- /dev/null +++ b/docs/sections/services/ves-hv/resources/blueprint-snippet.yaml @@ -0,0 +1,24 @@ +node_templates: + hv-ves: + properties: + application_config: + logLevel: "INFO" + server.listenPort: 6061 + server.idleTimeoutSec: 60 + cbs.requestIntervalSec: 5 + security.sslDisable: false + security.keys.keyStoreFile: "/etc/ves-hv/ssl/cert.jks" + security.keys.keyStorePasswordFile: "/etc/ves-hv/ssl/jks.pass" + security.keys.trustStoreFile: "/etc/ves-hv/ssl/trust.jks" + security.keys.trustStorePasswordFile: "/etc/ves-hv/ssl/trust.pass" + stream_publishes: + perf3gpp: + type: "kafka" + kafka_info: + bootstrap_servers: "message-router-kafka:9092" + topic_name: "HV_VES_PERF3GPP" + heartbeat: + type: "kafka" + kafka_info: + bootstrap_servers: "message-router-kafka:9092" + topic_name: "HV_VES_HEARTBEAT" diff --git a/docs/sections/services/ves-hv/resources/dynamic-configuration.json b/docs/sections/services/ves-hv/resources/dynamic-configuration.json new file mode 100644 index 00000000..0a1cd89d --- /dev/null +++ b/docs/sections/services/ves-hv/resources/dynamic-configuration.json @@ -0,0 +1,28 @@ +{ + "logLevel": "INFO", + "server.listenPort": 6061, + "server.idleTimeoutSec": 60, + "cbs.requestIntervalSec": 5, + "security.sslDisable": false, + "security.keys.keyStoreFile": "/etc/ves-hv/ssl/cert.jks", + "security.keys.keyStorePasswordFile": "/etc/ves-hv/ssl/jks.pass", + "security.keys.trustStoreFile": "/etc/ves-hv/ssl/trust.jks", + "security.keys.trustStorePasswordFile": "/etc/ves-hv/ssl/trust.pass", + "streams_publishes": { + "perf3gpp": { + "type": "kafka", + "kafka_info": { + "bootstrap_servers": "message-router-kafka:9092", + "topic_name": "HV_VES_PERF3GPP" + } + }, + "heartbeat": { + "type": "kafka", + "kafka_info": { + "bootstrap_servers": "message-router-kafka:9092", + "topic_name": "HV_VES_HEARTBEAT" + } + } + } +} + diff --git a/docs/sections/services/ves-hv/metrics_sample_response.txt b/docs/sections/services/ves-hv/resources/metrics_sample_response.txt index da54e3ea..da54e3ea 100644 --- a/docs/sections/services/ves-hv/metrics_sample_response.txt +++ b/docs/sections/services/ves-hv/resources/metrics_sample_response.txt diff --git a/docs/sections/services/ves-hv/run-time-configuration.rst b/docs/sections/services/ves-hv/run-time-configuration.rst index 76d622c6..95bad674 100644 --- a/docs/sections/services/ves-hv/run-time-configuration.rst +++ b/docs/sections/services/ves-hv/run-time-configuration.rst @@ -6,54 +6,42 @@ Run-Time configuration ====================== -(see :ref:`deployment`) +HV-VES dynamic configuration is primarily meant to provide DMaaP Connection Objects (see :ref:`dmaap-connection-objects`). +These objects contain information necessary to route received VES Events to correct Kafka topic. This metadata will be later referred to as Routing definition. -HV-VES can fetch configuration directly from Consul service in the following JSON format: +Collector internally uses DCAE-SDK to fetch configuration from Config Binding Service. -.. code-block:: json +HV-VES waits 10 seconds (default, configurable during deployment with **firstRequestDelay** option, see :ref:`configuration_file`) before the first attempt to retrieve configuration from CBS. This is to prevent possible synchronization issues. During that time HV-VES declines any connection attempts from xNF (VNF/PNF). - { - "dmaap.kafkaBootstrapServers": "message-router-kafka:9093", - "collector.routing": [ - { - "fromDomain": "perf3gpp", - "toTopic": "HV_VES_PERF3GPP" - }, - { - "fromDomain": "heartbeat", - "toTopic": "HV_VES_HEARTBEAT" - }, - ... - ] - } +After first request, HV-VES asks for configuration in fixed intervals, configurable from file configuration (**requestInterval**). By default interval is set to 5 seconds. -HV-VES does not verify the correctness of configuration data and uses them as is, in particular: +In case of failing to retrieve configuration, collector retries the action. After five unsuccessful attempts, container becomes unhealthy and cannot recover. HV-VES in this state is unusable and the container should be restarted. -- **KafkaBootstrapServers** is used as host name and port for publishing events to Kafka service. -- Every **routing** array object specifies one event publishing route. - - **fromDomain** node should be a case-sensitive string of single domain taken from VES Common Event Header specification. - - **toTopic** should be a case-sensitive string of Kafka topic. - - When HV-VES receives VES Event, it checks the domain contained in it. If the route from that domain to any topic exists in configuration, then HV-VES publishes that event to topic in that route. - - If there are two routes from the same domain to different topics, then it is undefined which route will be used. +Configuration format +-------------------- -The configuration is created from HV-VES Cloudify blueprint by specifying **application_config** node during ONAP OOM/Kubernetes deployment. Example of the node specification: +Following JSON format presents dynamic configuration options recognized by HV-VES Collector. +Note that there is no verification of the data correctness (e.g. if specified security files are present on machine) and thus invalid data can result in service malfunctioning or even container shutdown. + +.. literalinclude:: resources/dynamic-configuration.json + :language: json + +Fields have same meaning as in file configuration with only difference being Routing definition. -.. code-block:: YAML +Routing +------- - node_templates: - hv-ves: - properties: - application_config: - dmaap.kafkaBootstrapServers: message-router-kafka:9092 - collector.routing: - fromDomain: perf3gpp - toTopic: HV_VES_PERF3GPP +For every JSON key-object pair defined in **"stream_publishes"**, the key is used as domain and related object is used to setup Kafka's bootstrap servers and Kafka topic **for this domain**. -Endpoint on which HV-VES seeks configuration can be set during deployment as described in :ref:`deployment`. +Collector when receiving VES Event from client checks if domain from the event corresponds to any from Routing and publishes this event onto related topic. If there is no match, the event is dropped. If there are two routes from the same domain to different topics, then it is undefined which route will be used. -HV-VES waits 10 seconds (default, configurable during deplyoment with **first-request-delay** option, see :ref:`deployment`) before the first attempt to retrieve configuration from Consul. This is to prevent possible synchronization issues. During that time HV-VES declines any connection attempts from xNF (VNF/PNF). +For more informations see :ref:`supported_domains` -After first request, HV-VES asks for configuration in fixed intervals, configurable from command line (**request-interval**). By defualt interval is set to 5 seconds. +Providing configuration during OOM deployment +--------------------------------------------- + +The configuration is created from HV-VES Cloudify blueprint by specifying **application_config** node during ONAP OOM/Kubernetes deployment. Example of the node specification: -In case of failing to retrieve configuration, collector temporarily extends this interval and retries. After five unsuccessfull attempts, container becomes unhealthy and cannot recover. HV-VES in this state is unusable and the container should be restarted. +.. literalinclude:: resources/blueprint-snippet.yaml + :language: yaml
\ No newline at end of file |
