dcae design doc updates

Change-Id: I7145f840d9a7de34bb6a615fe992ba22e1ff0380
Signed-off-by: VENKATESH KUMAR <vv770d@att.com>
Issue-ID: DCAEGEN2-2024
Issue-ID: DCAEGEN2-1865
Signed-off-by: VENKATESH KUMAR <vv770d@att.com>

1 files changed, 0 insertions, 351 deletions

diff --git a/docs/sections/components/component-specification/docker-specification.rst b/docs/sections/components/component-specification/docker-specification.rst
deleted file mode 100755
index 128c006d..00000000
--- a/docs/sections/components/component-specification/docker-specification.rst
+++ /dev/null
@@ -1,351 +0,0 @@
-.. 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 <metadata>`

--  :any:`Interfaces <interfaces>` including the

-   associated :any:`Data Formats <data-formats>`

--  :any:`Parameters <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.

-(Policy reconfiguration is not yet supported).

-

-+--------------------------------+---------+---------------------------+

-| 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.                    |

-+--------------------------------+---------+---------------------------+

-| *Planned for 1806*             |         |                           |

-+--------------------------------+---------+---------------------------+

-| policy                         | JSON    | *Required*. Policy        |

-|                                | array   | reconfiguration script    |

-|                                |         | details                   |

-+--------------------------------+---------+---------------------------+

-

-Health Check Definition

-~~~~~~~~~~~~~~~~~~~~~~~

-

-The platform uses Consul to perform periodic health check calls. Consul

-provides different types of `check

-definitions <https://www.consul.io/docs/agent/checks.html>`__. 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 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 Consul to call to     |

-|                                |         | check 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                  |

-+--------------------------------+---------+---------------------------+

-

-Consul will use the `Docker exec

-API <https://docs.docker.com/engine/api/v1.29/#tag/Exec>`__ 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

-~~~~~

-

-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 (not yet supported)

-~~~~~~~~~~~~~~~~~~~~~~~~~~

-

-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"

-        }]

-    }