+++ /dev/null
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.\r
-.. http://creativecommons.org/licenses/by/4.0\r
-\r
-.. _docker-requirements:\r
-\r
-Component Spec Requirements\r
-===========================\r
-\r
-The component specification contains the following groups of\r
-information. \r
-\r
-- :any:`Metadata <metadata>`\r
-- :any:`Interfaces <interfaces>` including the\r
- associated :any:`Data Formats <data-formats>`\r
-- :any:`Parameters <common-specification-parameters>`\r
-- :any:`Auxiliary Details <docker-auxiliary-details>`\r
-- :any:`List of Artifacts <artifacts>`\r
-\r
-.. _docker-auxiliary-details:\r
-\r
-Auxiliary Details\r
------------------\r
-\r
-``auxiliary`` contains Docker specific details like health check, port\r
-mapping, volume mapping and policy reconfiguration script details.\r
-\r
-\r
-+--------------------------------+---------+---------------------------+\r
-| Name | Type | Description |\r
-+================================+=========+===========================+\r
-| healthcheck | JSON | *Required*. Health check |\r
-| | object | definition details |\r
-+--------------------------------+---------+---------------------------+\r
-| ports | JSON | each array item maps a |\r
-| | array | container port to the |\r
-| | | host port. See example |\r
-| | | below. |\r
-+--------------------------------+---------+---------------------------+\r
-| volumes | JSON | each array item contains |\r
-| | array | volume definition of eith\|\r
-| | | er: host path or config m\|\r
-| | | ap volume. |\r
-+--------------------------------+---------+---------------------------+\r
-| policy | JSON | *Required*. Policy |\r
-| | array | reconfiguration script |\r
-| | | details |\r
-+--------------------------------+---------+---------------------------+\r
-| tls_info | JSON | *Optional*. Information |\r
-| | object | about usage of tls certif\|\r
-| | | icates |\r
-+--------------------------------+---------+---------------------------+\r
-\r
-Health Check Definition\r
-~~~~~~~~~~~~~~~~~~~~~~~\r
-\r
-The platform currently supports http and docker script based health checks. \r
-\r
-When choosing a value for interval, consider that too frequent\r
-healthchecks will put unnecessary load on the platform. If there is a\r
-problematic resource, then more frequent healthchecks are warranted (eg\r
-15s or 60s), but as stability increases, so can these values, (eg\r
-300s).\r
-\r
-When choosing a value for timeout, consider that too small a number will\r
-result in increasing timeout failures, and too large a number will\r
-result in a delay in the notification of the resource problem. A\r
-suggestion is to start with 5s and work from there.\r
-\r
-http\r
-^^^^\r
-\r
-+--------------------------------+---------+---------------------------+\r
-| Property Name | Type | Description |\r
-+================================+=========+===========================+\r
-| type | string | *Required*. ``http`` |\r
-+--------------------------------+---------+---------------------------+\r
-| interval | string | Interval duration in |\r
-| | | seconds i.e. ``60s`` |\r
-+--------------------------------+---------+---------------------------+\r
-| timeout | string | Timeout in seconds i.e. |\r
-| | | ``5s`` |\r
-+--------------------------------+---------+---------------------------+\r
-| endpoint | string | *Required*. GET endpoint |\r
-| | | provided by the component |\r
-| | | for checking health |\r
-+--------------------------------+---------+---------------------------+\r
-\r
-Example:\r
-\r
-.. code:: json\r
-\r
- "auxilary": {\r
- "healthcheck": {\r
- "type": "http",\r
- "interval": "15s",\r
- "timeout": "1s",\r
- "endpoint": "/my-health"\r
- }\r
- }\r
-\r
-docker script example\r
-^^^^^^^^^^^^^^^^^^^^^\r
-\r
-+--------------------------------+---------+---------------------------+\r
-| Property Name | Type | Description |\r
-+================================+=========+===========================+\r
-| type | string | *Required*. ``docker`` |\r
-+--------------------------------+---------+---------------------------+\r
-| interval | string | Interval duration in |\r
-| | | seconds i.e. ``15s`` |\r
-+--------------------------------+---------+---------------------------+\r
-| timeout | string | Timeout in seconds i.e. |\r
-| | | ``1s`` |\r
-+--------------------------------+---------+---------------------------+\r
-| script | string | *Required*. Full path of |\r
-| | | script that exists in the |\r
-| | | Docker container to be |\r
-| | | executed |\r
-+--------------------------------+---------+---------------------------+\r
-\r
-During deployment, the K8S plugin maps the healthcheck defined into \r
-into a Kubernetes readiness probe. \r
-\r
-Kubernetes execs the script in the container (using the `docker exec API <https://docs.docker.com/engine/api/v1.29/#tag/Exec>`__ ). \r
-It will examine the script result to identify whether your component is healthy. Your\r
-component is considered healthy when the script returns ``0`` otherwise your component is considered not healthy.\r
-\r
-Example:\r
-\r
-.. code:: json\r
-\r
- "auxilary": {\r
- "healthcheck": {\r
- "type": "docker",\r
- "script": "/app/resources/check_health.py",\r
- "timeout": "30s",\r
- "interval": "180s"\r
- }\r
- }\r
-\r
-Ports\r
-~~~~~\r
-\r
-This method of exposing/mapping a local port to a host port is NOT\r
-RECOMMENDED because of the possibility of port conflicts. If multiple\r
-instances of a docker container will be running, there definitely will\r
-be port conflicts. Use at your own risk. (The preferred way to expose a\r
-port is to do so in the Dockerfile as described\r
-:any:`here <dcae-cli-docker-ports>`).\r
-\r
-.. code:: json\r
-\r
- "auxilary": {\r
- "ports": ["8080:8000"]\r
- }\r
-\r
-In the example above, container port 8080 maps to host port 8000.\r
-\r
-Volume Mapping\r
-~~~~~~~~~~~~~~\r
-\r
-.. code:: json\r
-\r
- "auxilary": {\r
- "volumes": [\r
- {\r
- "container": {\r
- "bind": "/tmp/docker.sock",\r
- "mode": "ro"\r
- },\r
- "host": {\r
- "path": "/var/run/docker.sock"\r
- }\r
- },\r
- {\r
- "container": {\r
- "bind": "/tmp/mount_path"\r
- "mode": "ro"\r
- },\r
- "config_volume": {\r
- "name": "config_map_name"\r
- }\r
- }\r
- ]\r
- }\r
-\r
-At the top-level:\r
-\r
-+---------------+-------+-------------------------------------+\r
-| Property Name | Type | Description |\r
-+===============+=======+=====================================+\r
-| volumes | array | Contains container with host/config\|\r
-| | | _volume objects |\r
-+---------------+-------+-------------------------------------+\r
-\r
-The ``container`` object contains:\r
-\r
-\r
-+-----------------------+-----------------------+-------------------------------+\r
-| Property Name | Type | Description |\r
-+=======================+=======================+===============================+\r
-| bind | string | path to the container |\r
-| | | volume |\r
-+-----------------------+-----------------------+-------------------------------+\r
-| mode | string | ro - indicates |\r
-| | | read-only volume |\r
-+-----------------------+-----------------------+-------------------------------+\r
-| | | w - indicates that |\r
-| | | the contain can write |\r
-| | | into the bind mount |\r
-+-----------------------+-----------------------+-------------------------------+\r
-\r
-The ``host`` object contains:\r
-\r
-+---------------+--------+-------------------------+\r
-| Property Name | Type | Description |\r
-+===============+========+=========================+\r
-| path | string | path to the host volume |\r
-+---------------+--------+-------------------------+\r
-\r
-The ``config_volume`` object contains:\r
-\r
-+---------------+--------+-------------------------+\r
-| Property Name | Type | Description |\r
-+===============+========+=========================+\r
-| name | string | name of config map |\r
-+---------------+--------+-------------------------+\r
-\r
-Here is an example of the minimal JSON with host path volume that must be provided as an input:\r
-\r
-.. code:: json\r
-\r
- "auxilary": {\r
- "volumes": [\r
- {\r
- "container": {\r
- "bind": "/tmp/docker.sock"\r
- },\r
- "host": {\r
- "path": "/var/run/docker.sock"\r
- }\r
- }\r
- ]\r
- }\r
-\r
-In the example above, the container volume “/tmp/docker.sock” maps to\r
-host volume “/var/run/docker.sock”.\r
-\r
-Here is an example of the minimal JSON with config map volume that must be provided as an input:\r
-\r
-.. code:: json\r
-\r
- "auxilary": {\r
- "volumes": [\r
- {\r
- "container": {\r
- "bind": "/tmp/mount_path"\r
- },\r
- "config_volume": {\r
- "name": "config_map_name"\r
- }\r
- }\r
- ]\r
- }\r
-\r
-In the example above, config map named "config_map_name" is mounted at "/tmp/mount_path".\r
-\r
-Policy \r
-~~~~~~~\r
-\r
-Policy changes made in the Policy UI will be provided to the Docker\r
-component by triggering a script that is defined here.\r
-\r
-+--------------------------------+---------+---------------------------+\r
-| Property Name | Type | Description |\r
-+================================+=========+===========================+\r
-| reconfigure_type | string | *Required*. Current value |\r
-| | | supported is ``policy`` |\r
-+--------------------------------+---------+---------------------------+\r
-| script_path | string | *Required*. Current value |\r
-| | | for ‘policy’ |\r
-| | | reconfigure_type must be |\r
-| | | “/opt/app/reconfigure.sh” |\r
-+--------------------------------+---------+---------------------------+\r
-\r
-Example:\r
-\r
-.. code:: json\r
-\r
- "auxilary": {\r
- "policy": {\r
- "reconfigure_type": "policy",\r
- "script_path": "/opt/app/reconfigure.sh"\r
- }\r
- }\r
-\r
-The docker script interface is as follows: \`/opt/app/reconfigure.sh\r
-$reconfigure_type {“updated policies”: , “application config”: }\r
-\r
-+---------------------+--------------+----------------------------------------+\r
-| Name | Type | Description |\r
-+=====================+==============+========================================+\r
-| reconfigure_type | string | policy |\r
-+---------------------+--------------+----------------------------------------+\r
-| updated_policies | json | TBD |\r
-+---------------------+--------------+----------------------------------------+\r
-| updated_appl_config | json | complete generated app_config, not |\r
-| | | fully-resolved, but ``policy-enabled`` |\r
-| | | parameters have been updated. In order |\r
-| | | to get the complete updated |\r
-| | | app_config, the component would have |\r
-| | | to call ``config-binding-service``. |\r
-+---------------------+--------------+----------------------------------------+\r
-\r
-TLS Info\r
-~~~~~~~~~~~~~~~~~\r
-\r
-TLS Info is used to trigger addition of init containers that can provide main application containers with certificates\r
-for internal and external communication.\r
-\r
-+--------------------------------+---------+---------------------------------------------------------------------------+\r
-| Property Name | Type | Description |\r
-+================================+=========+===========================================================================+\r
-| cert_directory | string | *Required*. Directory where certificates should be created. |\r
-| | | i.e. ``/opt/app/dcae-certificate`` |\r
-+--------------------------------+---------+---------------------------------------------------------------------------+\r
-| use_tls | boolean | *Required*. A boolean that indicates whether server certificates for int\ |\r
-| | | ernal communication should be added to the main container |\r
-| | | i.e ``true`` |\r
-+--------------------------------+---------+---------------------------------------------------------------------------+\r
-| use_external_tls | boolean | *Optional*. A boolean that indicates whether the component uses OOM Cert\ |\r
-| | | Service to acquire operator certificate to protect external (between xNFs |\r
-| | | and ONAP) traffic. For a time being only operator certificate from CMPv2 |\r
-| | | server is supported. |\r
-| | | i.e ``true`` |\r
-+--------------------------------+---------+---------------------------------------------------------------------------+\r
-\r
-\r
-Example:\r
-\r
-.. code:: json\r
-\r
- "auxilary": {\r
- "tls_info": {\r
- "cert_directory": "/opt/app/dcae-certificate",\r
- "use_tls": true\r
- "use_external_tls": true,\r
- }\r
- },\r
-\r
-Docker Component Spec - Complete Example\r
-----------------------------------------\r
-\r
-.. code:: json\r
-\r
- {\r
- "self": {\r
- "version": "1.0.0",\r
- "name": "yourapp.component.kpi_anomaly",\r
- "description": "Classifies VNF KPI data as anomalous",\r
- "component_type": "docker"\r
- },\r
- "streams": {\r
- "subscribes": [{\r
- "format": "dcae.vnf.kpi",\r
- "version": "1.0.0",\r
- "route": "/data",\r
- "type": "http"\r
- }],\r
- "publishes": [{\r
- "format": "yourapp.format.integerClassification",\r
- "version": "1.0.0",\r
- "config_key": "prediction",\r
- "type": "http"\r
- }]\r
- },\r
- "services": {\r
- "calls": [{\r
- "config_key": "vnf-db",\r
- "request": {\r
- "format": "dcae.vnf.meta",\r
- "version": "1.0.0"\r
- },\r
- "response": {\r
- "format": "dcae.vnf.kpi",\r
- "version": "1.0.0"\r
- }\r
- }],\r
- "provides": [{\r
- "route": "/score-vnf",\r
- "request": {\r
- "format": "dcae.vnf.meta",\r
- "version": "1.0.0"\r
- },\r
- "response": {\r
- "format": "yourapp.format.integerClassification",\r
- "version": "1.0.0"\r
- }\r
- }]\r
- },\r
- "parameters": [\r
- {\r
- "name": "threshold",\r
- "value": 0.75,\r
- "description": "Probability threshold to exceed to be anomalous"\r
- }\r
- ],\r
- "auxilary": {\r
- "healthcheck": {\r
- "type": "http",\r
- "interval": "15s",\r
- "timeout": "1s",\r
- "endpoint": "/my-health"\r
- }\r
- },\r
- "artifacts": [{\r
- "uri": "fake.nexus.att.com/dcae/kpi_anomaly:1.0.0",\r
- "type": "docker image"\r
- }]\r
- }\r
Code Review / dcaegen2.git / blobdiff