From 53ba1707f0da9d64aae53a43d59a5257dd4e12ce Mon Sep 17 00:00:00 2001 From: kjaniak Date: Thu, 25 Oct 2018 14:25:13 +0200 Subject: Publish HV-VES documentation including perf3gpp Change-Id: I8d3e926ce6bc99f981d52eb72fcbe92e8ce67cde Signed-off-by: kjaniak Issue-ID: DCAEGEN2-859 --- docs/sections/services/ves-hv/deployment.rst | 88 ++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 docs/sections/services/ves-hv/deployment.rst (limited to 'docs/sections/services/ves-hv/deployment.rst') diff --git a/docs/sections/services/ves-hv/deployment.rst b/docs/sections/services/ves-hv/deployment.rst new file mode 100644 index 00000000..55529061 --- /dev/null +++ b/docs/sections/services/ves-hv/deployment.rst @@ -0,0 +1,88 @@ +.. 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. + +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 options have precedence over environment variables. + ++-------------+------------+-------------------+----------+-----+-------------------------------------------------+ +| 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 | ++-------------+------------+-------------------+----------+-----+-------------------------------------------------+ + +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. + ++-------------+------------+-------------------+----------+-----+-------------------------------------------------+ +| Long form | Short form | Env form | Required | Arg | Description | ++=============+============+===================+==========+=====+=================================================+ +| ssl-disable | l | VESHV_SSL_DISABLE | no | no | Disables SSL encryption | ++-------------+------------+-------------------+----------+-----+-------------------------------------------------+ + + +Minimal command for running the container: + +.. code-block:: bash + + 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 | ++-----------------------+------------+----------------------------+----------+-----+-----------------+-------------------------------------------------------+ + +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`. + +Healthcheck +=========== + +Inside HV-VES docker container runs small http service for healthcheck - exact port for this service can be configured +at deployment using `--health-check-api-port` command line option. + +This service exposes single endpoint **GET /health/ready** which returns **HTTP 200 OK** in case HV-VES is healthy +and ready for connections. Otherwise it returns **HTTP 503 Service Unavailable** with short reason of unhealthiness. -- cgit 1.2.3-korg