DCAE Controller documentation DCAEGEN2-213
Issue-ID: DCAEGEN2-213
Change-Id: I7f2023b7f88b73eef852eca0bbf9086e14903cd6
Signed-off-by: Ralph Knag <rhknag@research.att.com>
diff --git a/docs/sections/components/component-specification/docker-specification.rst b/docs/sections/components/component-specification/docker-specification.rst
new file mode 100755
index 0000000..38612e1
--- /dev/null
+++ b/docs/sections/components/component-specification/docker-specification.rst
@@ -0,0 +1,454 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _docker-specification:
+
+Component specification (Docker)
+================================
+
+The Docker component specification contains the following groups of
+information. Many of these are common to both Docker and CDAP components
+and are therefore described in the common specification.
+
+- :any:`Metadata <metadata>`
+- :any:`Interfaces <interfaces>` including the
+ associated :any:`Data Formats <data-formats>`
+- :any:`Parameters <parameters>`
+- :any:`Auxiliary Details <docker-auxiliary-details>`
+- :any:`List of Artifacts <artifacts>`
+
+.. _docker-auxiliary-details:
+
+Auxiliary Details
+-----------------
+
+``auxiliary`` contains Docker specific details like health check, port
+mapping, volume mapping, and policy reconfiguration script details.
+
++-------------+----+----------+
+| Name | Ty\| Descript\|
+| | pe | ion |
++=============+====+==========+
+| healthcheck | JS\| *Require\|
+| | ON | d*. |
+| | ob\| Health |
+| | je\| check |
+| | ct | definiti\|
+| | | on |
+| | | details |
++-------------+----+----------+
+| ports | JS\| each |
+| | ON | array |
+| | ar\| item |
+| | ra\| maps a |
+| | y | containe\|
+| | | r |
+| | | port to |
+| | | the host |
+| | | port. |
+| | | See |
+| | | example |
+| | | below. |
++-------------+----+----------+
+| volume | JS\| each |
+| | ON | array |
+| | ar\| item |
+| | ra\| contains |
+| | y | a host |
+| | | and |
+| | | containe\|
+| | | r |
+| | | object. |
+| | | See |
+| | | example |
+| | | below. |
++-------------+----+----------+
+| policy | JS\| *Require\|
+| | ON | d*. |
+| | ar\| Policy |
+| | ra\| script |
+| | y | details |
++-------------+----+----------+
+
+Health Check Definition
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The platform uses Consul to perform periodic health check calls. Consul
+provides different types of `check definitions <https://www.consul.io/docs/agent/checks.html>`_. The
+platform currently supports http and docker health checks.
+
+When choosing a value for interval, consider that too frequent
+healthchecks will put unnecessary load on Consul and DCAE. If there is a
+problematic resource, then more frequent healthchecks are warranted (eg
+15s or 60s), but as stablility increases, so can these values, (eg
+300s).
+
+When choosing a value for timeout, consider that too small a number will
+result in increasing timeout failures, and too large a number will
+result in a delay in the notification of resource problem. A suggestion
+is to start with 5s and workd from there.
+
+http
+^^^^
+
++-------------+----+----------+
+| Property | Ty\| Descript\|
+| Name | pe | ion |
++=============+====+==========+
+| type | st\| *Require\|
+| | ri\| d*. |
+| | ng | ``http`` |
++-------------+----+----------+
+| interval | st\| Interval |
+| | ri\| duration |
+| | ng | in |
+| | | seconds |
+| | | i.e. |
+| | | ``60s`` |
++-------------+----+----------+
+| timeout | st\| Timeout |
+| | ri\| in |
+| | ng | seconds |
+| | | i.e. |
+| | | ``5s`` |
++-------------+----+----------+
+| endpoint | st\| *Require\|
+| | ri\| d*. |
+| | ng | GET |
+| | | endpoint |
+| | | provided |
+| | | by the |
+| | | componen\|
+| | | t |
+| | | for |
+| | | Consul |
+| | | to call |
+| | | to check |
+| | | health |
++-------------+----+----------+
+
+Example:
+
+.. code:: json
+
+ "auxilary": {
+ "healthcheck": {
+ "type": "http",
+ "interval": "15s",
+ "timeout": "1s",
+ "endpoint": "/my-health"
+ }
+ }
+
+docker script example
+^^^^^^^^^^^^^^^^^^^^^
+
++-------------+----+------------+
+| Property | Ty\| Descript\ |
+| Name | pe | ion |
++=============+====+============+
+| type | st\| *Require\ |
+| | ri\| d*. |
+| | ng | ``docker`` |
++-------------+----+------------+
+| interval | st\| Interval |
+| | ri\| duration |
+| | ng | in |
+| | | seconds |
+| | | i.e. |
+| | | ``15s`` |
++-------------+----+------------+
+| timeout | st\| Timeout |
+| | ri\| in |
+| | ng | seconds |
+| | | i.e. |
+| | | ``1s`` |
++-------------+----+------------+
+| script | st\| *Require\ |
+| | ri\| d*. |
+| | ng | Full |
+| | | path of |
+| | | script |
+| | | that |
+| | | exists |
+| | | in the |
+| | | Docker |
+| | | containe\ |
+| | | r |
+| | | to be |
+| | | executed |
++-------------+----+------------+
+
+Consul will use the `Docker exec API <https://docs.docker.com/engine/api/v1.29/#tag/Exec>`_ to
+periodically call your script in your container. It will examine the
+script result to identify whether your component is healthy. Your
+component is considered healthy when the script returns ``0`` otherwise
+your component is considered not healthy.
+
+Example:
+
+.. code:: json
+
+ "auxilary": {
+ "healthcheck": {
+ "type": "docker",
+ "script": "/app/resources/check_health.py",
+ "timeout": "30s",
+ "interval": "180s"
+ }
+ }
+
+Ports
+~~~~~
+
+.. code:: json
+
+ "auxilary": {
+ "ports": ["8080:8000"]
+ }
+
+In the example above, container port 8080 maps to host port 8000.
+
+Volume Mapping
+~~~~~~~~~~~~~~
+
+.. code:: json
+
+ "auxilary": {
+ "volumes": [
+ {
+ "container": {
+ "bind": "/tmp/docker.sock",
+ "mode": "ro"
+ },
+ "host": {
+ "path": "/var/run/docker.sock"
+ }
+ }
+ ]
+ }
+
+At the top-level:
+
++---------------+-------+-------------------------------------+
+| Property Name | Type | Description |
++===============+=======+=====================================+
+| volumes | array | Contains container and host objects |
++---------------+-------+-------------------------------------+
+
+The ``container`` object contains:
+
++----------------------+----------------------+----------------------+
+| Property Name | Type | Description |
++======================+======================+======================+
+| bind | string | path to the |
+| | | container volume |
++----------------------+----------------------+----------------------+
+| mode | string | “ro” - indicates |
+| | | read-only volume |
+| | | “” - indicates that |
+| | | the container can |
+| | | write into the bind |
+| | | mount |
++----------------------+----------------------+----------------------+
+
+The ``host`` object contains:
+
++---------------+--------+-------------------------+
+| Property Name | Type | Description |
++===============+========+=========================+
+| path | string | path to the host volume |
++---------------+--------+-------------------------+
+
+Here’s an example of the minimal JSON that must be provided as an input:
+
+.. code:: json
+
+ "auxilary": {
+ "volumes": [
+ {
+ "container": {
+ "bind": "/tmp/docker.sock"
+ },
+ "host": {
+ "path": "/var/run/docker.sock"
+ }
+ }
+ ]
+ }
+
+In the example above, the container volume “/tmp/docker.sock” maps to
+host volume “/var/run/docker.sock”.
+
+Policy
+~~~~~~
+
+Policy changes made in the Policy UI will be provided to the Docker
+component by triggering a script that is defined here.
+
++-------------+----+------------+
+| Property | Ty\| Descript\ |
+| Name | pe | ion |
++=============+====+============+
+| reconfigure | st\| *Require\ |
+| _type | ri\| d*. |
+| | ng | Current |
+| | | value |
+| | | supporte |
+| | | d |
+| | | is |
+| | | ``policy`` |
++-------------+----+------------+
+| script_path | st\| *Require\ |
+| | ri\| d*. |
+| | ng | Current |
+| | | value |
+| | | for |
+| | | ‘policy’ |
+| | | reconfig\ |
+| | | ure_type |
+| | | must be |
+| | | “/opt/ap\ |
+| | | p/reconf\ |
+| | | igure.sh |
+| | | ” |
++-------------+----+------------+
+
+Example:
+
+.. code:: json
+
+ "auxilary": {
+ "policy": {
+ "reconfigure_type": "policy",
+ "script_path": "/opt/app/reconfigure.sh"
+ }
+ }
+
+The docker script interface is as follows: \`/opt/app/reconfigure.sh
+$reconfigure_type {“updated policies”: , “application config”: }
+
++-----+----+---------------------------+
+| Na\ | Ty\| Descript\ |
+| me | pe | ion |
++=====+====+===========================+
+| re\ | st\| “policy” |
+| co\ | ri\| |
+| nf\ | ng | |
+| ig\ | | |
+| ur\ | | |
+| e_t\| | |
+| y\ | | |
+| pe\ | | |
++-----+----+---------------------------+
+| up\ | js\| TBD |
+| da\ | on | |
+| te\ | | |
+| d_p\| | |
+| o\ | | |
+| li\ | | |
+| ci\ | | |
+| es | | |
++-----+----+---------------------------+
+| up\ | js\| complete |
+| da\ | on | generate\ |
+| te\ | | d |
+| d_a\| | app_conf\ |
+| p\ | | ig, |
+| pl\ | | not |
+| _c\ | | fully-re\ |
+| on\ | | solved, |
+| fi\ | | but |
+| g | | ``policy-enabled`` |
+| | | paramete\ |
+| | | rs |
+| | | have |
+| | | been |
+| | | updated. |
+| | | In order |
+| | | to get |
+| | | the |
+| | | complete |
+| | | updated |
+| | | app_conf\ |
+| | | ig, |
+| | | the |
+| | | componen\ |
+| | | t |
+| | | would |
+| | | have to |
+| | | call |
+| | | ``config-binding-service``|
+| | | . |
++-----+----+---------------------------+
+
+Docker Component Spec - Complete Example
+----------------------------------------
+
+.. code:: json
+
+ {
+ "self": {
+ "version": "1.0.0",
+ "name": "asimov.component.kpi_anomaly",
+ "description": "Classifies VNF KPI data as anomalous",
+ "component_type": "docker"
+ },
+ "streams": {
+ "subscribes": [{
+ "format": "dcae.vnf.kpi",
+ "version": "1.0.0",
+ "route": "/data",
+ "type": "http"
+ }],
+ "publishes": [{
+ "format": "asimov.format.integerClassification",
+ "version": "1.0.0",
+ "config_key": "prediction",
+ "type": "http"
+ }]
+ },
+ "services": {
+ "calls": [{
+ "config_key": "vnf-db",
+ "request": {
+ "format": "dcae.vnf.meta",
+ "version": "1.0.0"
+ },
+ "response": {
+ "format": "dcae.vnf.kpi",
+ "version": "1.0.0"
+ }
+ }],
+ "provides": [{
+ "route": "/score-vnf",
+ "request": {
+ "format": "dcae.vnf.meta",
+ "version": "1.0.0"
+ },
+ "response": {
+ "format": "asimov.format.integerClassification",
+ "version": "1.0.0"
+ }
+ }]
+ },
+ "parameters": [
+ {
+ "name": "threshold",
+ "value": 0.75,
+ "description": "Probability threshold to exceed to be anomalous"
+ }
+ ],
+ "auxilary": {
+ "healthcheck": {
+ "type": "http",
+ "interval": "15s",
+ "timeout": "1s",
+ "endpoint": "/my-health"
+ }
+ },
+ "artifacts": [{
+ "uri": "fake.nexus.com/dcae/kpi_anomaly:1.0.0",
+ "type": "docker image"
+ }]
+ }