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-requirements:
\r
6 Component Spec Requirements
\r
7 ===========================
\r
9 The component specification contains the following groups of
\r
12 - :any:`Metadata <metadata>`
\r
13 - :any:`Interfaces <interfaces>` including the
\r
14 associated :any:`Data Formats <data-formats>`
\r
15 - :any:`Parameters <common-specification-parameters>`
\r
16 - :any:`Auxiliary Details <docker-auxiliary-details>`
\r
17 - :any:`List of Artifacts <artifacts>`
\r
19 .. _docker-auxiliary-details:
\r
24 ``auxiliary`` contains Docker specific details like health check, port
\r
25 mapping, volume mapping and policy reconfiguration script details.
\r
28 +--------------------------------+---------+---------------------------+
\r
29 | Name | Type | Description |
\r
30 +================================+=========+===========================+
\r
31 | healthcheck | JSON | *Required*. Health check |
\r
32 | | object | definition details |
\r
33 +--------------------------------+---------+---------------------------+
\r
34 | ports | JSON | each array item maps a |
\r
35 | | array | container port to the |
\r
36 | | | host port. See example |
\r
38 +--------------------------------+---------+---------------------------+
\r
39 | volumes | JSON | each array item contains |
\r
40 | | array | volume definition of eith\|
\r
41 | | | er: host path or config m\|
\r
43 +--------------------------------+---------+---------------------------+
\r
44 | policy | JSON | *Required*. Policy |
\r
45 | | array | reconfiguration script |
\r
47 +--------------------------------+---------+---------------------------+
\r
48 | tls_info | JSON | *Optional*. Information |
\r
49 | | object | about usage of tls certif\|
\r
51 +--------------------------------+---------+---------------------------+
\r
53 Health Check Definition
\r
54 ~~~~~~~~~~~~~~~~~~~~~~~
\r
56 The platform currently supports http and docker script based health checks.
\r
58 When choosing a value for interval, consider that too frequent
\r
59 healthchecks will put unnecessary load on the platform. If there is a
\r
60 problematic resource, then more frequent healthchecks are warranted (eg
\r
61 15s or 60s), but as stability increases, so can these values, (eg
\r
64 When choosing a value for timeout, consider that too small a number will
\r
65 result in increasing timeout failures, and too large a number will
\r
66 result in a delay in the notification of the resource problem. A
\r
67 suggestion is to start with 5s and work from there.
\r
72 +--------------------------------+---------+---------------------------+
\r
73 | Property Name | Type | Description |
\r
74 +================================+=========+===========================+
\r
75 | type | string | *Required*. ``http`` |
\r
76 +--------------------------------+---------+---------------------------+
\r
77 | interval | string | Interval duration in |
\r
78 | | | seconds i.e. ``60s`` |
\r
79 +--------------------------------+---------+---------------------------+
\r
80 | timeout | string | Timeout in seconds i.e. |
\r
82 +--------------------------------+---------+---------------------------+
\r
83 | endpoint | string | *Required*. GET endpoint |
\r
84 | | | provided by the component |
\r
85 | | | for checking health |
\r
86 +--------------------------------+---------+---------------------------+
\r
97 "endpoint": "/my-health"
\r
101 docker script example
\r
102 ^^^^^^^^^^^^^^^^^^^^^
\r
104 +--------------------------------+---------+---------------------------+
\r
105 | Property Name | Type | Description |
\r
106 +================================+=========+===========================+
\r
107 | type | string | *Required*. ``docker`` |
\r
108 +--------------------------------+---------+---------------------------+
\r
109 | interval | string | Interval duration in |
\r
110 | | | seconds i.e. ``15s`` |
\r
111 +--------------------------------+---------+---------------------------+
\r
112 | timeout | string | Timeout in seconds i.e. |
\r
114 +--------------------------------+---------+---------------------------+
\r
115 | script | string | *Required*. Full path of |
\r
116 | | | script that exists in the |
\r
117 | | | Docker container to be |
\r
119 +--------------------------------+---------+---------------------------+
\r
121 During deployment, the K8S plugin maps the healthcheck defined into
\r
122 into a Kubernetes readiness probe.
\r
124 Kubernetes execs the script in the container (using the `docker exec API <https://docs.docker.com/engine/api/v1.29/#tag/Exec>`__ ).
\r
125 It will examine the script result to identify whether your component is healthy. Your
\r
126 component is considered healthy when the script returns ``0`` otherwise your component is considered not healthy.
\r
135 "script": "/app/resources/check_health.py",
\r
144 This method of exposing/mapping a local port to a host port is NOT
\r
145 RECOMMENDED because of the possibility of port conflicts. If multiple
\r
146 instances of a docker container will be running, there definitely will
\r
147 be port conflicts. Use at your own risk. (The preferred way to expose a
\r
148 port is to do so in the Dockerfile as described
\r
149 :any:`here <dcae-cli-docker-ports>`).
\r
154 "ports": ["8080:8000"]
\r
157 In the example above, container port 8080 maps to host port 8000.
\r
168 "bind": "/tmp/docker.sock",
\r
172 "path": "/var/run/docker.sock"
\r
177 "bind": "/tmp/mount_path"
\r
181 "name": "config_map_name"
\r
189 +---------------+-------+-------------------------------------+
\r
190 | Property Name | Type | Description |
\r
191 +===============+=======+=====================================+
\r
192 | volumes | array | Contains container with host/config\|
\r
193 | | | _volume objects |
\r
194 +---------------+-------+-------------------------------------+
\r
196 The ``container`` object contains:
\r
199 +-----------------------+-----------------------+-------------------------------+
\r
200 | Property Name | Type | Description |
\r
201 +=======================+=======================+===============================+
\r
202 | bind | string | path to the container |
\r
204 +-----------------------+-----------------------+-------------------------------+
\r
205 | mode | string | ro - indicates |
\r
206 | | | read-only volume |
\r
207 +-----------------------+-----------------------+-------------------------------+
\r
208 | | | w - indicates that |
\r
209 | | | the contain can write |
\r
210 | | | into the bind mount |
\r
211 +-----------------------+-----------------------+-------------------------------+
\r
213 The ``host`` object contains:
\r
215 +---------------+--------+-------------------------+
\r
216 | Property Name | Type | Description |
\r
217 +===============+========+=========================+
\r
218 | path | string | path to the host volume |
\r
219 +---------------+--------+-------------------------+
\r
221 The ``config_volume`` object contains:
\r
223 +---------------+--------+-------------------------+
\r
224 | Property Name | Type | Description |
\r
225 +===============+========+=========================+
\r
226 | name | string | name of config map |
\r
227 +---------------+--------+-------------------------+
\r
229 Here is an example of the minimal JSON with host path volume that must be provided as an input:
\r
237 "bind": "/tmp/docker.sock"
\r
240 "path": "/var/run/docker.sock"
\r
246 In the example above, the container volume “/tmp/docker.sock” maps to
\r
247 host volume “/var/run/docker.sock”.
\r
249 Here is an example of the minimal JSON with config map volume that must be provided as an input:
\r
257 "bind": "/tmp/mount_path"
\r
260 "name": "config_map_name"
\r
266 In the example above, config map named "config_map_name" is mounted at "/tmp/mount_path".
\r
271 Policy changes made in the Policy UI will be provided to the Docker
\r
272 component by triggering a script that is defined here.
\r
274 +--------------------------------+---------+---------------------------+
\r
275 | Property Name | Type | Description |
\r
276 +================================+=========+===========================+
\r
277 | reconfigure_type | string | *Required*. Current value |
\r
278 | | | supported is ``policy`` |
\r
279 +--------------------------------+---------+---------------------------+
\r
280 | script_path | string | *Required*. Current value |
\r
281 | | | for ‘policy’ |
\r
282 | | | reconfigure_type must be |
\r
283 | | | “/opt/app/reconfigure.sh” |
\r
284 +--------------------------------+---------+---------------------------+
\r
292 "reconfigure_type": "policy",
\r
293 "script_path": "/opt/app/reconfigure.sh"
\r
297 The docker script interface is as follows: \`/opt/app/reconfigure.sh
\r
298 $reconfigure_type {“updated policies”: , “application config”: }
\r
300 +---------------------+--------------+----------------------------------------+
\r
301 | Name | Type | Description |
\r
302 +=====================+==============+========================================+
\r
303 | reconfigure_type | string | policy |
\r
304 +---------------------+--------------+----------------------------------------+
\r
305 | updated_policies | json | TBD |
\r
306 +---------------------+--------------+----------------------------------------+
\r
307 | updated_appl_config | json | complete generated app_config, not |
\r
308 | | | fully-resolved, but ``policy-enabled`` |
\r
309 | | | parameters have been updated. In order |
\r
310 | | | to get the complete updated |
\r
311 | | | app_config, the component would have |
\r
312 | | | to call ``config-binding-service``. |
\r
313 +---------------------+--------------+----------------------------------------+
\r
318 TLS Info is used to trigger addition of init containers that can provide main application containers with certificates
\r
319 for internal and external communication.
\r
321 +--------------------------------+---------+---------------------------------------------------------------------------+
\r
322 | Property Name | Type | Description |
\r
323 +================================+=========+===========================================================================+
\r
324 | cert_directory | string | *Required*. Directory where certificates should be created. |
\r
325 | | | i.e. ``/opt/app/dcae-certificate`` |
\r
326 +--------------------------------+---------+---------------------------------------------------------------------------+
\r
327 | use_tls | boolean | *Required*. A boolean that indicates whether server certificates for int\ |
\r
328 | | | ernal communication should be added to the main container |
\r
329 | | | i.e ``true`` |
\r
330 +--------------------------------+---------+---------------------------------------------------------------------------+
\r
331 | use_external_tls | boolean | *Optional*. A boolean that indicates whether the component uses OOM Cert\ |
\r
332 | | | Service to acquire operator certificate to protect external (between xNFs |
\r
333 | | | and ONAP) traffic. For a time being only operator certificate from CMPv2 |
\r
334 | | | server is supported. |
\r
335 | | | i.e ``true`` |
\r
336 +--------------------------------+---------+---------------------------------------------------------------------------+
\r
345 "cert_directory": "/opt/app/dcae-certificate",
\r
347 "use_external_tls": true,
\r
351 Docker Component Spec - Complete Example
\r
352 ----------------------------------------
\r
358 "version": "1.0.0",
\r
359 "name": "yourapp.component.kpi_anomaly",
\r
360 "description": "Classifies VNF KPI data as anomalous",
\r
361 "component_type": "docker"
\r
365 "format": "dcae.vnf.kpi",
\r
366 "version": "1.0.0",
\r
371 "format": "yourapp.format.integerClassification",
\r
372 "version": "1.0.0",
\r
373 "config_key": "prediction",
\r
379 "config_key": "vnf-db",
\r
381 "format": "dcae.vnf.meta",
\r
385 "format": "dcae.vnf.kpi",
\r
390 "route": "/score-vnf",
\r
392 "format": "dcae.vnf.meta",
\r
396 "format": "yourapp.format.integerClassification",
\r
403 "name": "threshold",
\r
405 "description": "Probability threshold to exceed to be anomalous"
\r
413 "endpoint": "/my-health"
\r
417 "uri": "fake.nexus.att.com/dcae/kpi_anomaly:1.0.0",
\r
418 "type": "docker image"
\r