.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
-
.. _deployment:
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 an argument if needed (see `Arg` column in table below).
+These parameters can be omitted if the corresponding environment variables are set.
+These variables are named after the 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 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 is 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 as it was 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.
To scale HV-VES deployment you need to determine its name and namespace in which it is deployed.
-For default OOM deployment, HV-VES full deployment name is `deployment/dep-dcae-hv-ves-collector` and it is installed under `onap` namespace.
+For default OOM deployment, HV-VES full deployment name is `deployment/dep-dcae-hv-ves-collector`
+and it is installed under `onap` namespace.
1. If the namespace is unknown, execute the following command to determine possible namespaces.
ONAP_NAMESPACE=onap
kubectl get --namespace ${ONAP_NAMESPACE} deployment
-3. To scale deployment execute:
+3. To scale deployment, execute the following commands:
.. code-block:: bash
Code Review / dcaegen2.git / blobdiff