docs/sections/design-components/component-specification/docker-specification.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.\r
   2 .. http://creativecommons.org/licenses/by/4.0\r
   3 \r
   4 .. _docker-requirements:\r
   5 \r
   6 Component Spec Requirements\r
   7 ===========================\r
   8 \r
   9 The component specification contains the following groups of\r
  10 information. \r
  11 \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
  18 \r
  19 .. _docker-auxiliary-details:\r
  20 \r
  21 Auxiliary Details\r
  22 -----------------\r
  23 \r
  24 ``auxiliary`` contains Docker specific details like health check, port\r
  25 mapping, volume mapping and policy reconfiguration script details.\r
  26 \r
  27 \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
  37 |                                |         | below.                    |\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
  42 |                                |         | ap volume.                |\r
  43 +--------------------------------+---------+---------------------------+\r
  44 | policy                         | JSON    | *Required*. Policy        |\r
  45 |                                | array   | reconfiguration script    |\r
  46 |                                |         | details                   |\r
  47 +--------------------------------+---------+---------------------------+\r
  48 | tls_info                       | JSON    | *Optional*. Information   |\r
  49 |                                | object  | about usage of tls certif\|\r
  50 |                                |         | icates                    |\r
  51 +--------------------------------+---------+---------------------------+\r
  52 \r
  53 Health Check Definition\r
  54 ~~~~~~~~~~~~~~~~~~~~~~~\r
  55 \r
  56 The platform currently supports http and docker script based health checks. \r
  57 \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
  62 300s).\r
  63 \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
  68 \r
  69 http\r
  70 ^^^^\r
  71 \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
  81 |                                |         | ``5s``                    |\r
  82 +--------------------------------+---------+---------------------------+\r
  83 | endpoint                       | string  | *Required*. GET endpoint  |\r
  84 |                                |         | provided by the component |\r
  85 |                                |         | for checking health       |\r
  86 +--------------------------------+---------+---------------------------+\r
  87 \r
  88 Example:\r
  89 \r
  90 .. code:: json\r
  91 \r
  92     "auxilary": {\r
  93         "healthcheck": {\r
  94             "type": "http",\r
  95             "interval": "15s",\r
  96             "timeout": "1s",\r
  97             "endpoint": "/my-health"\r
  98         }\r
  99     }\r
 100 \r
 101 docker script example\r
 102 ^^^^^^^^^^^^^^^^^^^^^\r
 103 \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
 113 |                                |         | ``1s``                    |\r
 114 +--------------------------------+---------+---------------------------+\r
 115 | script                         | string  | *Required*. Full path of  |\r
 116 |                                |         | script that exists in the |\r
 117 |                                |         | Docker container to be    |\r
 118 |                                |         | executed                  |\r
 119 +--------------------------------+---------+---------------------------+\r
 120 \r
 121 During deployment, the K8S plugin maps the healthcheck defined into \r
 122 into a Kubernetes readiness probe.  \r
 123 \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
 127 \r
 128 Example:\r
 129 \r
 130 .. code:: json\r
 131 \r
 132     "auxilary": {\r
 133         "healthcheck": {\r
 134             "type": "docker",\r
 135             "script": "/app/resources/check_health.py",\r
 136             "timeout": "30s",\r
 137             "interval": "180s"\r
 138         }\r
 139     }\r
 140 \r
 141 Ports\r
 142 ~~~~~\r
 143 \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
 150 \r
 151 .. code:: json\r
 152 \r
 153     "auxilary": {\r
 154         "ports": ["8080:8000"]\r
 155     }\r
 156 \r
 157 In the example above, container port 8080 maps to host port 8000.\r
 158 \r
 159 Volume Mapping\r
 160 ~~~~~~~~~~~~~~\r
 161 \r
 162 .. code:: json\r
 163 \r
 164     "auxilary": {\r
 165         "volumes": [\r
 166             {\r
 167                "container": {\r
 168                    "bind": "/tmp/docker.sock",\r
 169                    "mode": "ro"\r
 170                 },\r
 171                 "host": {\r
 172                     "path": "/var/run/docker.sock"\r
 173                 }\r
 174             },\r
 175             {\r
 176                "container": {\r
 177                    "bind": "/tmp/mount_path"\r
 178                    "mode": "ro"\r
 179                 },\r
 180                 "config_volume": {\r
 181                     "name": "config_map_name"\r
 182                 }\r
 183             }\r
 184         ]\r
 185     }\r
 186 \r
 187 At the top-level:\r
 188 \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
 195 \r
 196 The ``container`` object contains:\r
 197 \r
 198 \r
 199 +-----------------------+-----------------------+-------------------------------+\r
 200 | Property Name         | Type                  | Description                   |\r
 201 +=======================+=======================+===============================+\r
 202 | bind                  | string                | path to the container         |\r
 203 |                       |                       | volume                        |\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
 212 \r
 213 The ``host`` object contains:\r
 214 \r
 215 +---------------+--------+-------------------------+\r
 216 | Property Name | Type   | Description             |\r
 217 +===============+========+=========================+\r
 218 | path          | string | path to the host volume |\r
 219 +---------------+--------+-------------------------+\r
 220 \r
 221 The ``config_volume`` object contains:\r
 222 \r
 223 +---------------+--------+-------------------------+\r
 224 | Property Name | Type   | Description             |\r
 225 +===============+========+=========================+\r
 226 | name          | string | name of config map      |\r
 227 +---------------+--------+-------------------------+\r
 228 \r
 229 Here is an example of the minimal JSON with host path volume that must be provided as an input:\r
 230 \r
 231 .. code:: json\r
 232 \r
 233     "auxilary": {\r
 234         "volumes": [\r
 235             {\r
 236                "container": {\r
 237                    "bind": "/tmp/docker.sock"\r
 238                 },\r
 239                 "host": {\r
 240                     "path": "/var/run/docker.sock"\r
 241                 }\r
 242             }\r
 243         ]\r
 244     }\r
 245 \r
 246 In the example above, the container volume “/tmp/docker.sock” maps to\r
 247 host volume “/var/run/docker.sock”.\r
 248 \r
 249 Here is an example of the minimal JSON with config map volume that must be provided as an input:\r
 250 \r
 251 .. code:: json\r
 252 \r
 253     "auxilary": {\r
 254         "volumes": [\r
 255             {\r
 256                "container": {\r
 257                    "bind": "/tmp/mount_path"\r
 258                 },\r
 259                 "config_volume": {\r
 260                     "name": "config_map_name"\r
 261                 }\r
 262             }\r
 263         ]\r
 264     }\r
 265 \r
 266 In the example above, config map named "config_map_name" is mounted at "/tmp/mount_path".\r
 267 \r
 268 Policy \r
 269 ~~~~~~~\r
 270 \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
 273 \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
 285 \r
 286 Example:\r
 287 \r
 288 .. code:: json\r
 289 \r
 290     "auxilary": {\r
 291         "policy": {\r
 292             "reconfigure_type": "policy",\r
 293             "script_path": "/opt/app/reconfigure.sh"\r
 294         }\r
 295     }\r
 296 \r
 297 The docker script interface is as follows: \`/opt/app/reconfigure.sh\r
 298 $reconfigure_type {“updated policies”: , “application config”: }\r
 299 \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
 314 \r
 315 TLS Info\r
 316 ~~~~~~~~~~~~~~~~~\r
 317 \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
 320 \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
 337 \r
 338 \r
 339 Example:\r
 340 \r
 341 .. code:: json\r
 342 \r
 343         "auxilary": {\r
 344                 "tls_info": {\r
 345                         "cert_directory": "/opt/app/dcae-certificate",\r
 346                         "use_tls": true\r
 347                         "use_external_tls": true,\r
 348                 }\r
 349         },\r
 350 \r
 351 Docker Component Spec - Complete Example\r
 352 ----------------------------------------\r
 353 \r
 354 .. code:: json\r
 355 \r
 356     {\r
 357         "self": {\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
 362         },\r
 363         "streams": {\r
 364             "subscribes": [{\r
 365                 "format": "dcae.vnf.kpi",\r
 366                 "version": "1.0.0",\r
 367                 "route": "/data",\r
 368                 "type": "http"\r
 369             }],\r
 370             "publishes": [{\r
 371                 "format": "yourapp.format.integerClassification",\r
 372                 "version": "1.0.0",\r
 373                 "config_key": "prediction",\r
 374                 "type": "http"\r
 375             }]\r
 376         },\r
 377         "services": {\r
 378             "calls": [{\r
 379                 "config_key": "vnf-db",\r
 380                 "request": {\r
 381                     "format": "dcae.vnf.meta",\r
 382                     "version": "1.0.0"\r
 383                     },\r
 384                 "response": {\r
 385                     "format": "dcae.vnf.kpi",\r
 386                     "version": "1.0.0"\r
 387                     }\r
 388             }],\r
 389             "provides": [{\r
 390                 "route": "/score-vnf",\r
 391                 "request": {\r
 392                     "format": "dcae.vnf.meta",\r
 393                     "version": "1.0.0"\r
 394                     },\r
 395                 "response": {\r
 396                     "format": "yourapp.format.integerClassification",\r
 397                     "version": "1.0.0"\r
 398                     }\r
 399             }]\r
 400         },\r
 401         "parameters": [\r
 402             {\r
 403                 "name": "threshold",\r
 404                 "value": 0.75,\r
 405                 "description": "Probability threshold to exceed to be anomalous"\r
 406             }\r
 407         ],\r
 408         "auxilary": {\r
 409             "healthcheck": {\r
 410                 "type": "http",\r
 411                 "interval": "15s",\r
 412                 "timeout": "1s",\r
 413                 "endpoint": "/my-health"\r
 414             }\r
 415         },\r
 416         "artifacts": [{\r
 417             "uri": "fake.nexus.att.com/dcae/kpi_anomaly:1.0.0",\r
 418             "type": "docker image"\r
 419         }]\r
 420     }\r