Merge "DCAE Controller documentation DCAEGEN2-213"

1 files changed, 454 insertions, 0 deletions

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 00000000..38612e17
--- /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"

+        }]

+    }