From 1fca6acb2918beef86a5a78dc659683830908cd2 Mon Sep 17 00:00:00 2001 From: Ralph Knag Date: Tue, 5 Dec 2017 12:05:57 -0500 Subject: DCAE Controller documentation DCAEGEN2-213 Issue-ID: DCAEGEN2-213 Change-Id: I7f2023b7f88b73eef852eca0bbf9086e14903cd6 Signed-off-by: Ralph Knag --- .../docker-specification.rst | 454 +++++++++++++++++++++ 1 file changed, 454 insertions(+) create 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 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 ` +- :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. + ++-------------+----+----------+ +| 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 `_. 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 `_ 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" + }] + } -- cgit 1.2.3-korg