From 64559741f071b37556b7745ffa2cdcc25f40af94 Mon Sep 17 00:00:00 2001 From: VENKATESH KUMAR Date: Wed, 29 Apr 2020 18:53:53 -0400 Subject: dcae design doc updates Change-Id: I7145f840d9a7de34bb6a615fe992ba22e1ff0380 Signed-off-by: VENKATESH KUMAR Issue-ID: DCAEGEN2-2024 Issue-ID: DCAEGEN2-1865 Signed-off-by: VENKATESH KUMAR --- .../docker-specification.rst | 351 --------------------- 1 file changed, 351 deletions(-) delete mode 100755 docs/sections/components/component-specification/docker-specification.rst (limited to 'docs/sections/components/component-specification/docker-specification.rst') diff --git a/docs/sections/components/component-specification/docker-specification.rst b/docs/sections/components/component-specification/docker-specification.rst deleted file mode 100755 index 128c006d..00000000 --- a/docs/sections/components/component-specification/docker-specification.rst +++ /dev/null @@ -1,351 +0,0 @@ -.. 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 ` -- :any:`Interfaces ` including the - associated :any:`Data Formats ` -- :any:`Parameters ` -- :any:`Auxiliary Details ` -- :any:`List of Artifacts ` - -.. _docker-auxiliary-details: - -Auxiliary Details ------------------ - -``auxiliary`` contains Docker specific details like health check, port -mapping, volume mapping and policy reconfiguration script details. -(Policy reconfiguration is not yet supported). - -+--------------------------------+---------+---------------------------+ -| Name | Type | Description | -+================================+=========+===========================+ -| healthcheck | JSON | *Required*. Health check | -| | object | definition details | -+--------------------------------+---------+---------------------------+ -| ports | JSON | each array item maps a | -| | array | container port to the | -| | | host port. See example | -| | | below. | -+--------------------------------+---------+---------------------------+ -| volume | JSON | each array item contains | -| | array | a host and container | -| | | object. See example | -| | | below. | -+--------------------------------+---------+---------------------------+ -| *Planned for 1806* | | | -+--------------------------------+---------+---------------------------+ -| policy | JSON | *Required*. Policy | -| | array | reconfiguration script | -| | | details | -+--------------------------------+---------+---------------------------+ - -Health Check Definition -~~~~~~~~~~~~~~~~~~~~~~~ - -The platform uses Consul to perform periodic health check calls. Consul -provides different types of `check -definitions `__. 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 stability 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 the resource problem. A -suggestion is to start with 5s and work from there. - -http -^^^^ - -+--------------------------------+---------+---------------------------+ -| Property Name | Type | Description | -+================================+=========+===========================+ -| type | string | *Required*. ``http`` | -+--------------------------------+---------+---------------------------+ -| interval | string | Interval duration in | -| | | seconds i.e. ``60s`` | -+--------------------------------+---------+---------------------------+ -| timeout | string | Timeout in seconds i.e. | -| | | ``5s`` | -+--------------------------------+---------+---------------------------+ -| endpoint | string | *Required*. GET endpoint | -| | | provided by the component | -| | | 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 Name | Type | Description | -+================================+=========+===========================+ -| type | string | *Required*. ``docker`` | -+--------------------------------+---------+---------------------------+ -| interval | string | Interval duration in | -| | | seconds i.e. ``15s`` | -+--------------------------------+---------+---------------------------+ -| timeout | string | Timeout in seconds i.e. | -| | | ``1s`` | -+--------------------------------+---------+---------------------------+ -| script | string | *Required*. Full path of | -| | | script that exists in the | -| | | Docker container to be | -| | | executed | -+--------------------------------+---------+---------------------------+ - -Consul will use the `Docker exec -API `__ 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 -~~~~~ - -This method of exposing/mapping a local port to a host port is NOT -RECOMMENDED because of the possibility of port conflicts. If multiple -instances of a docker container will be running, there definitely will -be port conflicts. Use at your own risk. (The preferred way to expose a -port is to do so in the Dockerfile as described -:any:`here `). - -.. 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 | -+-----------------------+-----------------------+-------------------------------+ -| | | w - indicates that | -| | | the contain 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 (not yet supported) -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Policy changes made in the Policy UI will be provided to the Docker -component by triggering a script that is defined here. - -+--------------------------------+---------+---------------------------+ -| Property Name | Type | Description | -+================================+=========+===========================+ -| reconfigure_type | string | *Required*. Current value | -| | | supported is ``policy`` | -+--------------------------------+---------+---------------------------+ -| script_path | string | *Required*. Current value | -| | | for ‘policy’ | -| | | reconfigure_type must be | -| | | “/opt/app/reconfigure.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”: } - -+---------------------+--------------+----------------------------------------+ -| Name | Type | Description | -+=====================+==============+========================================+ -| reconfigure_type | string | policy | -+---------------------+--------------+----------------------------------------+ -| updated_policies | json | TBD | -+---------------------+--------------+----------------------------------------+ -| updated_appl_config | json | complete generated app_config, not | -| | | fully-resolved, but ``policy-enabled`` | -| | | parameters have been updated. In order | -| | | to get the complete updated | -| | | app_config, the component would have | -| | | to call ``config-binding-service``. | -+---------------------+--------------+----------------------------------------+ - -Docker Component Spec - Complete Example ----------------------------------------- - -.. code:: json - - { - "self": { - "version": "1.0.0", - "name": "yourapp.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": "yourapp.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": "yourapp.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.att.com/dcae/kpi_anomaly:1.0.0", - "type": "docker image" - }] - } -- cgit 1.2.3-korg