diff options
Diffstat (limited to 'docs/sections/components/component-specification/docker-specification.rst')
| -rwxr-xr-x | docs/sections/components/component-specification/docker-specification.rst | 338 |
1 files changed, 118 insertions, 220 deletions
diff --git a/docs/sections/components/component-specification/docker-specification.rst b/docs/sections/components/component-specification/docker-specification.rst index 38612e17..01e11536 100755 --- a/docs/sections/components/component-specification/docker-specification.rst +++ b/docs/sections/components/component-specification/docker-specification.rst @@ -23,58 +23,38 @@ Auxiliary Details -----------------
``auxiliary`` contains Docker specific details like health check, port
-mapping, volume mapping, and policy reconfiguration script details.
-
-+-------------+----+----------+
-| Name | Ty\| Descript\|
-| | pe | ion |
-+=============+====+==========+
-| healthcheck | JS\| *Require\|
-| | ON | d*. |
-| | ob\| Health |
-| | je\| check |
-| | ct | definiti\|
-| | | on |
-| | | details |
-+-------------+----+----------+
-| ports | JS\| each |
-| | ON | array |
-| | ar\| item |
-| | ra\| maps a |
-| | y | containe\|
-| | | r |
-| | | port to |
-| | | the host |
-| | | port. |
-| | | See |
-| | | example |
-| | | below. |
-+-------------+----+----------+
-| volume | JS\| each |
-| | ON | array |
-| | ar\| item |
-| | ra\| contains |
-| | y | a host |
-| | | and |
-| | | containe\|
-| | | r |
-| | | object. |
-| | | See |
-| | | example |
-| | | below. |
-+-------------+----+----------+
-| policy | JS\| *Require\|
-| | ON | d*. |
-| | ar\| Policy |
-| | ra\| script |
-| | y | details |
-+-------------+----+----------+
+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
+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
@@ -85,47 +65,28 @@ problematic resource, then more frequent healthchecks are warranted (eg 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 resource problem. A suggestion
-is to start with 5s and workd from there.
+result in a delay in the notification of the resource problem. A
+suggestion is to start with 5s and work from there.
http
^^^^
-+-------------+----+----------+
-| Property | Ty\| Descript\|
-| Name | pe | ion |
-+=============+====+==========+
-| type | st\| *Require\|
-| | ri\| d*. |
-| | ng | ``http`` |
-+-------------+----+----------+
-| interval | st\| Interval |
-| | ri\| duration |
-| | ng | in |
-| | | seconds |
-| | | i.e. |
-| | | ``60s`` |
-+-------------+----+----------+
-| timeout | st\| Timeout |
-| | ri\| in |
-| | ng | seconds |
-| | | i.e. |
-| | | ``5s`` |
-+-------------+----+----------+
-| endpoint | st\| *Require\|
-| | ri\| d*. |
-| | ng | GET |
-| | | endpoint |
-| | | provided |
-| | | by the |
-| | | componen\|
-| | | t |
-| | | for |
-| | | Consul |
-| | | to call |
-| | | to check |
-| | | health |
-+-------------+----+----------+
++--------------------------------+---------+---------------------------+
+| 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:
@@ -143,43 +104,25 @@ Example: docker script example
^^^^^^^^^^^^^^^^^^^^^
-+-------------+----+------------+
-| Property | Ty\| Descript\ |
-| Name | pe | ion |
-+=============+====+============+
-| type | st\| *Require\ |
-| | ri\| d*. |
-| | ng | ``docker`` |
-+-------------+----+------------+
-| interval | st\| Interval |
-| | ri\| duration |
-| | ng | in |
-| | | seconds |
-| | | i.e. |
-| | | ``15s`` |
-+-------------+----+------------+
-| timeout | st\| Timeout |
-| | ri\| in |
-| | ng | seconds |
-| | | i.e. |
-| | | ``1s`` |
-+-------------+----+------------+
-| script | st\| *Require\ |
-| | ri\| d*. |
-| | ng | Full |
-| | | path of |
-| | | script |
-| | | that |
-| | | exists |
-| | | in the |
-| | | Docker |
-| | | containe\ |
-| | | r |
-| | | to be |
-| | | executed |
-+-------------+----+------------+
-
-Consul will use the `Docker exec API <https://docs.docker.com/engine/api/v1.29/#tag/Exec>`_ to
++--------------------------------+---------+---------------------------+
+| 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
@@ -201,6 +144,13 @@ Example: 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": {
@@ -238,19 +188,19 @@ At the top-level: The ``container`` object contains:
-+----------------------+----------------------+----------------------+
-| Property Name | Type | Description |
-+======================+======================+======================+
-| bind | string | path to the |
-| | | container volume |
-+----------------------+----------------------+----------------------+
-| mode | string | “ro” - indicates |
-| | | read-only volume |
-| | | “” - indicates that |
-| | | the container can |
-| | | write into the bind |
-| | | mount |
-+----------------------+----------------------+----------------------+
++-----------------------+-----------------------+-----------------------+
+| Property Name | Type | Description |
++=======================+=======================+=======================+
+| bind | string | path to the container |
+| | | volume |
++-----------------------+-----------------------+-----------------------+
+| mode | string | “ro” - indicates |
+| | | read-only volume |
++-----------------------+-----------------------+-----------------------+
+| | “” - indicates that |
+| | the contain can write |
+| | into the bind mount |
++-----------------------+-----------------------+-----------------------+
The ``host`` object contains:
@@ -280,39 +230,24 @@ Here’s an example of the minimal JSON that must be provided as an input: In the example above, the container volume “/tmp/docker.sock” maps to
host volume “/var/run/docker.sock”.
-Policy
-~~~~~~
+
+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 | Ty\| Descript\ |
-| Name | pe | ion |
-+=============+====+============+
-| reconfigure | st\| *Require\ |
-| _type | ri\| d*. |
-| | ng | Current |
-| | | value |
-| | | supporte |
-| | | d |
-| | | is |
-| | | ``policy`` |
-+-------------+----+------------+
-| script_path | st\| *Require\ |
-| | ri\| d*. |
-| | ng | Current |
-| | | value |
-| | | for |
-| | | ‘policy’ |
-| | | reconfig\ |
-| | | ure_type |
-| | | must be |
-| | | “/opt/ap\ |
-| | | p/reconf\ |
-| | | igure.sh |
-| | | ” |
-+-------------+----+------------+
++--------------------------------+---------+---------------------------+
+| 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:
@@ -328,59 +263,22 @@ Example: The docker script interface is as follows: \`/opt/app/reconfigure.sh
$reconfigure_type {“updated policies”: , “application config”: }
-+-----+----+---------------------------+
-| Na\ | Ty\| Descript\ |
-| me | pe | ion |
-+=====+====+===========================+
-| re\ | st\| “policy” |
-| co\ | ri\| |
-| nf\ | ng | |
-| ig\ | | |
-| ur\ | | |
-| e_t\| | |
-| y\ | | |
-| pe\ | | |
-+-----+----+---------------------------+
-| up\ | js\| TBD |
-| da\ | on | |
-| te\ | | |
-| d_p\| | |
-| o\ | | |
-| li\ | | |
-| ci\ | | |
-| es | | |
-+-----+----+---------------------------+
-| up\ | js\| complete |
-| da\ | on | generate\ |
-| te\ | | d |
-| d_a\| | app_conf\ |
-| p\ | | ig, |
-| pl\ | | not |
-| _c\ | | fully-re\ |
-| on\ | | solved, |
-| fi\ | | but |
-| g | | ``policy-enabled`` |
-| | | paramete\ |
-| | | rs |
-| | | have |
-| | | been |
-| | | updated. |
-| | | In order |
-| | | to get |
-| | | the |
-| | | complete |
-| | | updated |
-| | | app_conf\ |
-| | | ig, |
-| | | the |
-| | | componen\ |
-| | | t |
-| | | would |
-| | | have to |
-| | | call |
-| | | ``config-binding-service``|
-| | | . |
-+-----+----+---------------------------+
++--------------+--------------+----------------------------------------+
+| Name | Type | Description |
++==============+==============+========================================+
+| reconfigure_ | string | “policy” |
+| type | | |
++--------------+--------------+----------------------------------------+
+| updated_poli | json | TBD |
+| cies | | |
++--------------+--------------+----------------------------------------+
+| updated_appl | json | complete generated app_config, not |
+| _config | | 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
----------------------------------------
@@ -390,7 +288,7 @@ Docker Component Spec - Complete Example {
"self": {
"version": "1.0.0",
- "name": "asimov.component.kpi_anomaly",
+ "name": "yourapp.component.kpi_anomaly",
"description": "Classifies VNF KPI data as anomalous",
"component_type": "docker"
},
@@ -402,7 +300,7 @@ Docker Component Spec - Complete Example "type": "http"
}],
"publishes": [{
- "format": "asimov.format.integerClassification",
+ "format": "yourapp.format.integerClassification",
"version": "1.0.0",
"config_key": "prediction",
"type": "http"
@@ -427,7 +325,7 @@ Docker Component Spec - Complete Example "version": "1.0.0"
},
"response": {
- "format": "asimov.format.integerClassification",
+ "format": "yourapp.format.integerClassification",
"version": "1.0.0"
}
}]
@@ -448,7 +346,7 @@ Docker Component Spec - Complete Example }
},
"artifacts": [{
- "uri": "fake.nexus.com/dcae/kpi_anomaly:1.0.0",
+ "uri": "fake.nexus.att.com/dcae/kpi_anomaly:1.0.0",
"type": "docker image"
}]
}
|