.. 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" }] }