docs/sections/services/ves-hv/deployment.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4
   5 .. _deployment:
   6
   7 Deployment
   8 ============
   9
  10 To run HV-VES Collector container, you need to specify required parameters by passing them as command
  11 line arguments either by using long form (--long-form) or short form (-s) followed by argument if needed.
  12
  13 All parameters can also be configured by specifying environment variables. These variables have to be named after command line option name
  14 rewritten using `UPPER_SNAKE_CASE` and prepended with `VESHV_` prefix, for example `VESHV_LISTEN_PORT`.
  15
  16 Command line options have precedence over environment variables.
  17
  18 +-------------+------------+-------------------+----------+-----+-------------------------------------------------+
  19 | Long form   | Short form | Env form          | Required | Arg | Description                                     |
  20 +=============+============+===================+==========+=====+=================================================+
  21 | listen-port | p          | VESHV_LISTEN_PORT | yes      | yes | Port on which HV-VES listens internally         |
  22 +-------------+------------+-------------------+----------+-----+-------------------------------------------------+
  23 | config-url  | c          | VESHV_CONFIG_URL  | yes      | yes | URL of HV-VES configuration on Consul service   |
  24 +-------------+------------+-------------------+----------+-----+-------------------------------------------------+
  25
  26 HV-VES requires also to specify if SSL should be used when handling incoming TCP connections.
  27 This can be done by passing the flag below to the command line.
  28
  29 +-------------+------------+-------------------+----------+-----+-------------------------------------------------+
  30 | Long form   | Short form | Env form          | Required | Arg | Description                                     |
  31 +=============+============+===================+==========+=====+=================================================+
  32 | ssl-disable | l          | VESHV_SSL_DISABLE | no       | no  | Disables SSL encryption                         |
  33 +-------------+------------+-------------------+----------+-----+-------------------------------------------------+
  34
  35
  36 Minimal command for running the container:
  37
  38 .. code-block:: bash
  39
  40     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
  41
  42 Optional configuration parameters:
  43
  44 +-----------------------+------------+----------------------------+----------+-----+-----------------+-------------------------------------------------------+
  45 | Long form             | Short form | Env form                   | Required | Arg | Default         | Description                                           |
  46 +=======================+============+============================+==========+=====+=================+=======================================================+
  47 | health-check-api-port | H          | VESHV_HEALTHCHECK_API_PORT | no       | yes | 6060            | Health check REST API listen port                     |
  48 +-----------------------+------------+----------------------------+----------+-----+-----------------+-------------------------------------------------------+
  49 | first-request-delay   | d          | VESHV_FIRST_REQUEST_DELAY  | no       | yes | 10              | Delay of first request to Consul service in seconds   |
  50 +-----------------------+------------+----------------------------+----------+-----+-----------------+-------------------------------------------------------+
  51 | request-interval      | I          | VESHV_REQUEST_INTERVAL     | no       | yes | 5               | Interval of Consul configuration requests in seconds  |
  52 +-----------------------+------------+----------------------------+----------+-----+-----------------+-------------------------------------------------------+
  53 | idle-timeout-sec      | i          | VESHV_IDLE_TIMEOUT_SEC     | no       | yes | 60              | Idle timeout for remote hosts. After given time       |
  54 |                       |            |                            |          |     |                 | without any data exchange, the connection             |
  55 |                       |            |                            |          |     |                 | might be closed.                                      |
  56 +-----------------------+------------+----------------------------+----------+-----+-----------------+-------------------------------------------------------+
  57 | max-payload-size      | m          | VESHV_MAX_PAYLOAD_SIZE     | no       | yes | 1048576 (1 MiB) | Maximum supported payload size in bytes               |
  58 +-----------------------+------------+----------------------------+----------+-----+-----------------+-------------------------------------------------------+
  59
  60 As part of experimental API if you do not specify `ssl-disable` flag, there is need to specify additional
  61 parameters for security configuration.
  62
  63 +-----------------------+------------+----------------------------+----------+-----+------------------------+--------------------------------------------------------------+
  64 | Long form             | Short form | Env form                   | Required | Arg | Default                | Description                                                  |
  65 +=======================+============+============================+==========+=====+========================+==============================================================+
  66 | key-store             | k          | VESHV_KEY_STORE            | no       | yes | /etc/ves-hv/server.p12 | Key store in PKCS12 format path                              |
  67 +-----------------------+------------+----------------------------+----------+-----+------------------------+--------------------------------------------------------------+
  68 | key-store-password    | kp         | VESHV_KEY_STORE_PASSWORD   | no       | yes |                        | Key store password                                           |
  69 +-----------------------+------------+----------------------------+----------+-----+------------------------+--------------------------------------------------------------+
  70 | trust-store           | t          | VESHV_TRUST_STORE          | no       | yes | /etc/ves-hv/trust.p12  | File with trusted certificate bundle in PKCS12 format path   |
  71 +-----------------------+------------+----------------------------+----------+-----+------------------------+--------------------------------------------------------------+
  72 | trust-store-password  | tp         | VESHV_TRUST_STORE_PASSWORD | no       | yes |                        | Trust store password                                         |
  73 +-----------------------+------------+----------------------------+----------+-----+------------------------+--------------------------------------------------------------+
  74
  75 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.
  76
  77 These parameters can be configured either by passing command line option during `docker run` call or
  78 by specifying environment variables named after command line option name
  79 rewritten using `UPPER_SNAKE_CASE` and prepended with `VESHV_` prefix e.g. `VESHV_LISTEN_PORT`.
  80
  81 Healthcheck
  82 ===========
  83
  84 Inside HV-VES docker container runs small http service for healthcheck - exact port for this service can be configured
  85 at deployment using `--health-check-api-port` command line option.
  86
  87 This service exposes single endpoint **GET /health/ready** which returns **HTTP 200 OK** in case HV-VES is healthy
  88 and ready for connections. Otherwise it returns **HTTP 503 Service Unavailable** with short reason of unhealthiness.