1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
\r
2 .. http://creativecommons.org/licenses/by/4.0
\r
4 .. _docker-specification:
\r
6 Component specification (Docker)
\r
7 ================================
\r
9 The Docker component specification contains the following groups of
\r
10 information. Many of these are common to both Docker and CDAP components
\r
11 and are therefore described in the common specification.
\r
13 - :any:`Metadata <metadata>`
\r
14 - :any:`Interfaces <interfaces>` including the
\r
15 associated :any:`Data Formats <data-formats>`
\r
16 - :any:`Parameters <parameters>`
\r
17 - :any:`Auxiliary Details <docker-auxiliary-details>`
\r
18 - :any:`List of Artifacts <artifacts>`
\r
20 .. _docker-auxiliary-details:
\r
25 ``auxiliary`` contains Docker specific details like health check, port
\r
26 mapping, volume mapping, and policy reconfiguration script details.
\r
28 +-------------+----+----------+
\r
29 | Name | Ty\| Descript\|
\r
31 +=============+====+==========+
\r
32 | healthcheck | JS\| *Require\|
\r
39 +-------------+----+----------+
\r
40 | ports | JS\| each |
\r
52 +-------------+----+----------+
\r
53 | volume | JS\| each |
\r
65 +-------------+----+----------+
\r
66 | policy | JS\| *Require\|
\r
71 +-------------+----+----------+
\r
73 Health Check Definition
\r
74 ~~~~~~~~~~~~~~~~~~~~~~~
\r
76 The platform uses Consul to perform periodic health check calls. Consul
\r
77 provides different types of `check definitions <https://www.consul.io/docs/agent/checks.html>`_. The
\r
78 platform currently supports http and docker health checks.
\r
80 When choosing a value for interval, consider that too frequent
\r
81 healthchecks will put unnecessary load on Consul and DCAE. If there is a
\r
82 problematic resource, then more frequent healthchecks are warranted (eg
\r
83 15s or 60s), but as stablility increases, so can these values, (eg
\r
86 When choosing a value for timeout, consider that too small a number will
\r
87 result in increasing timeout failures, and too large a number will
\r
88 result in a delay in the notification of resource problem. A suggestion
\r
89 is to start with 5s and workd from there.
\r
94 +-------------+----+----------+
\r
95 | Property | Ty\| Descript\|
\r
97 +=============+====+==========+
\r
98 | type | st\| *Require\|
\r
100 | | ng | ``http`` |
\r
101 +-------------+----+----------+
\r
102 | interval | st\| Interval |
\r
103 | | ri\| duration |
\r
108 +-------------+----+----------+
\r
109 | timeout | st\| Timeout |
\r
114 +-------------+----+----------+
\r
115 | endpoint | st\| *Require\|
\r
128 +-------------+----+----------+
\r
139 "endpoint": "/my-health"
\r
143 docker script example
\r
144 ^^^^^^^^^^^^^^^^^^^^^
\r
146 +-------------+----+------------+
\r
147 | Property | Ty\| Descript\ |
\r
148 | Name | pe | ion |
\r
149 +=============+====+============+
\r
150 | type | st\| *Require\ |
\r
152 | | ng | ``docker`` |
\r
153 +-------------+----+------------+
\r
154 | interval | st\| Interval |
\r
155 | | ri\| duration |
\r
160 +-------------+----+------------+
\r
161 | timeout | st\| Timeout |
\r
166 +-------------+----+------------+
\r
167 | script | st\| *Require\ |
\r
180 +-------------+----+------------+
\r
182 Consul will use the `Docker exec API <https://docs.docker.com/engine/api/v1.29/#tag/Exec>`_ to
\r
183 periodically call your script in your container. It will examine the
\r
184 script result to identify whether your component is healthy. Your
\r
185 component is considered healthy when the script returns ``0`` otherwise
\r
186 your component is considered not healthy.
\r
195 "script": "/app/resources/check_health.py",
\r
207 "ports": ["8080:8000"]
\r
210 In the example above, container port 8080 maps to host port 8000.
\r
221 "bind": "/tmp/docker.sock",
\r
225 "path": "/var/run/docker.sock"
\r
233 +---------------+-------+-------------------------------------+
\r
234 | Property Name | Type | Description |
\r
235 +===============+=======+=====================================+
\r
236 | volumes | array | Contains container and host objects |
\r
237 +---------------+-------+-------------------------------------+
\r
239 The ``container`` object contains:
\r
241 +----------------------+----------------------+----------------------+
\r
242 | Property Name | Type | Description |
\r
243 +======================+======================+======================+
\r
244 | bind | string | path to the |
\r
245 | | | container volume |
\r
246 +----------------------+----------------------+----------------------+
\r
247 | mode | string | “ro” - indicates |
\r
248 | | | read-only volume |
\r
249 | | | “” - indicates that |
\r
250 | | | the container can |
\r
251 | | | write into the bind |
\r
253 +----------------------+----------------------+----------------------+
\r
255 The ``host`` object contains:
\r
257 +---------------+--------+-------------------------+
\r
258 | Property Name | Type | Description |
\r
259 +===============+========+=========================+
\r
260 | path | string | path to the host volume |
\r
261 +---------------+--------+-------------------------+
\r
263 Here’s an example of the minimal JSON that must be provided as an input:
\r
271 "bind": "/tmp/docker.sock"
\r
274 "path": "/var/run/docker.sock"
\r
280 In the example above, the container volume “/tmp/docker.sock” maps to
\r
281 host volume “/var/run/docker.sock”.
\r
286 Policy changes made in the Policy UI will be provided to the Docker
\r
287 component by triggering a script that is defined here.
\r
289 +-------------+----+------------+
\r
290 | Property | Ty\| Descript\ |
\r
291 | Name | pe | ion |
\r
292 +=============+====+============+
\r
293 | reconfigure | st\| *Require\ |
\r
294 | _type | ri\| d*. |
\r
301 +-------------+----+------------+
\r
302 | script_path | st\| *Require\ |
\r
315 +-------------+----+------------+
\r
323 "reconfigure_type": "policy",
\r
324 "script_path": "/opt/app/reconfigure.sh"
\r
328 The docker script interface is as follows: \`/opt/app/reconfigure.sh
\r
329 $reconfigure_type {“updated policies”: , “application config”: }
\r
331 +-----+----+---------------------------+
\r
332 | Na\ | Ty\| Descript\ |
\r
334 +=====+====+===========================+
\r
335 | re\ | st\| “policy” |
\r
343 +-----+----+---------------------------+
\r
352 +-----+----+---------------------------+
\r
353 | up\ | js\| complete |
\r
354 | da\ | on | generate\ |
\r
356 | d_a\| | app_conf\ |
\r
359 | _c\ | | fully-re\ |
\r
360 | on\ | | solved, |
\r
362 | g | | ``policy-enabled`` |
\r
381 | | | ``config-binding-service``|
\r
383 +-----+----+---------------------------+
\r
385 Docker Component Spec - Complete Example
\r
386 ----------------------------------------
\r
392 "version": "1.0.0",
\r
393 "name": "asimov.component.kpi_anomaly",
\r
394 "description": "Classifies VNF KPI data as anomalous",
\r
395 "component_type": "docker"
\r
399 "format": "dcae.vnf.kpi",
\r
400 "version": "1.0.0",
\r
405 "format": "asimov.format.integerClassification",
\r
406 "version": "1.0.0",
\r
407 "config_key": "prediction",
\r
413 "config_key": "vnf-db",
\r
415 "format": "dcae.vnf.meta",
\r
419 "format": "dcae.vnf.kpi",
\r
424 "route": "/score-vnf",
\r
426 "format": "dcae.vnf.meta",
\r
430 "format": "asimov.format.integerClassification",
\r
437 "name": "threshold",
\r
439 "description": "Probability threshold to exceed to be anomalous"
\r
447 "endpoint": "/my-health"
\r
451 "uri": "fake.nexus.com/dcae/kpi_anomaly:1.0.0",
\r
452 "type": "docker image"
\r
Code Review / dcaegen2.git / blob