path: root/docs/sections/design-components/component-specification/docker-specification.rst

.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0

.. _docker-requirements:

Component Spec Requirements
===========================

The component specification contains the following groups of
information. 

-  :any:`Metadata <metadata>`
-  :any:`Interfaces <interfaces>` including the
   associated :any:`Data Formats <data-formats>`
-  :any:`Parameters <common-specification-parameters>`
-  :any:`Auxiliary Details <docker-auxiliary-details>`
-  :any:`List of Artifacts <artifacts>`

.. _docker-auxiliary-details:

Auxiliary Details
-----------------

``auxiliary`` contains Docker specific details like health check, port
mapping, volume mapping and policy reconfiguration script details.


+--------------------------------+---------+---------------------------+
| Name                           | Type    | Description               |
+================================+=========+===========================+
| healthcheck                    | JSON    | *Required*. Health check  |
|                                | object  | definition details        |
+--------------------------------+---------+---------------------------+
| ports                          | JSON    | each array item maps a    |
|                                | array   | container port to the     |
|                                |         | host port. See example    |
|                                |         | below.                    |
+--------------------------------+---------+---------------------------+
| volume                         | JSON    | each array item contains  |
|                                | array   | a host and container      |
|                                |         | object. See example       |
|                                |         | below.                    |
+--------------------------------+---------+---------------------------+
| policy                         | JSON    | *Required*. Policy        |
|                                | array   | reconfiguration script    |
|                                |         | details                   |
+--------------------------------+---------+---------------------------+

Health Check Definition
~~~~~~~~~~~~~~~~~~~~~~~

The platform currently supports http and docker script based health checks. 

When choosing a value for interval, consider that too frequent
healthchecks will put unnecessary load on the platform. If there is a
problematic resource, then more frequent healthchecks are warranted (eg
15s or 60s), but as stability 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 the resource problem. A
suggestion is to start with 5s and work from there.

http
^^^^

+--------------------------------+---------+---------------------------+
| Property Name                  | Type    | Description               |
+================================+=========+===========================+
| type                           | string  | *Required*. ``http``      |
+--------------------------------+---------+---------------------------+
| interval                       | string  | Interval duration in      |
|                                |         | seconds i.e. ``60s``      |
+--------------------------------+---------+---------------------------+
| timeout                        | string  | Timeout in seconds i.e.   |
|                                |         | ``5s``                    |
+--------------------------------+---------+---------------------------+
| endpoint                       | string  | *Required*. GET endpoint  |
|                                |         | provided by the component |
|                                |         | for checking health       |
+--------------------------------+---------+---------------------------+

Example:

.. code:: json

    "auxilary": {
        "healthcheck": {
            "type": "http",
            "interval": "15s",
            "timeout": "1s",
            "endpoint": "/my-health"
        }
    }

docker script example
^^^^^^^^^^^^^^^^^^^^^

+--------------------------------+---------+---------------------------+
| Property Name                  | Type    | Description               |
+================================+=========+===========================+
| type                           | string  | *Required*. ``docker``    |
+--------------------------------+---------+---------------------------+
| interval                       | string  | Interval duration in      |
|                                |         | seconds i.e. ``15s``      |
+--------------------------------+---------+---------------------------+
| timeout                        | string  | Timeout in seconds i.e.   |
|                                |         | ``1s``                    |
+--------------------------------+---------+---------------------------+
| script                         | string  | *Required*. Full path of  |
|                                |         | script that exists in the |
|                                |         | Docker container to be    |
|                                |         | executed                  |
+--------------------------------+---------+---------------------------+

During deployment, the K8S plugin maps the healthcheck defined into 
into a Kubernetes readiness probe.  

Kubernetes execs the script in the container (using the `docker exec API
 <https://docs.docker.com/engine/api/v1.29/#tag/Exec>`__ ). 
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
~~~~~

This method of exposing/mapping a local port to a host port is NOT
RECOMMENDED because of the possibility of port conflicts. If multiple
instances of a docker container will be running, there definitely will
be port conflicts. Use at your own risk. (The preferred way to expose a
port is to do so in the Dockerfile as described
:any:`here <dcae-cli-docker-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              |
+-----------------------+-----------------------+-------------------------------+
|                       |                       | w - indicates that            |
|                       |                       | the contain 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 Name                  | Type    | Description               |
+================================+=========+===========================+
| reconfigure_type               | string  | *Required*. Current value |
|                                |         | supported is ``policy``   |
+--------------------------------+---------+---------------------------+
| script_path                    | string  | *Required*. Current value |
|                                |         | for ‘policy’              |
|                                |         | reconfigure_type must be  |
|                                |         | “/opt/app/reconfigure.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”: }

+---------------------+--------------+----------------------------------------+
| Name                | Type         | Description                            |
+=====================+==============+========================================+
| reconfigure_type    | string       | policy                                 |
+---------------------+--------------+----------------------------------------+
| updated_policies    | json         | TBD                                    |
+---------------------+--------------+----------------------------------------+
| updated_appl_config | json         | complete generated app_config, not     |
|                     |              | fully-resolved, but ``policy-enabled`` |
|                     |              | parameters have been updated. In order |
|                     |              | to get the complete updated            |
|                     |              | app_config, the component would have   |
|                     |              | to call ``config-binding-service``.    |
+---------------------+--------------+----------------------------------------+

Docker Component Spec - Complete Example
----------------------------------------

.. code:: json

    {
        "self": {
            "version": "1.0.0",
            "name": "yourapp.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": "yourapp.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": "yourapp.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.att.com/dcae/kpi_anomaly:1.0.0",
            "type": "docker image"
        }]
    }