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