summaryrefslogtreecommitdiffstats
path: root/docs/components/component-specification/docker-specification.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/components/component-specification/docker-specification.md')
-rw-r--r--docs/components/component-specification/docker-specification.md246
1 files changed, 246 insertions, 0 deletions
diff --git a/docs/components/component-specification/docker-specification.md b/docs/components/component-specification/docker-specification.md
new file mode 100644
index 00000000..2bff6c47
--- /dev/null
+++ b/docs/components/component-specification/docker-specification.md
@@ -0,0 +1,246 @@
+# Component specification (Docker)
+
+This page contains details specific to Dockerized applications.
+
+The component specification contains the following top-level groups of information:
+
+* [Component metadata](#metadata)
+* [Component interfaces](#interfaces) including the associated [data formats](/components/data-formats.md)
+* [Configuration parameters](#configuration-parameters)
+* [Auxiliary details](#auxilary)
+* [List of artifacts](#artifacts)
+
+## Metadata
+
+See [Metadata](common-specification.md#metadata)
+
+## Interfaces
+
+See [Interfaces](common-specification.md#interfaces)
+
+## Configuration parameters
+
+`parameters` is where to specify the component's application configuration parameters that are not connection information.
+
+Property Name | Type | Description
+------------- | ---- | -----------
+parameters | JSON array | Each entry is a parameter object
+
+Parameter object has the following available properties:
+
+Property Name | Type | Description | Default
+------------- | ---- | ----------- | -------
+name | string | *Required*. The property name that will be used as the key in the generated config |
+value | any | *Required*. The default value for the given parameter |
+description | string | *Required*. Human-readable text describing the parameter like what its for |
+type | string | The required data type for the parameter |
+required | boolean | An optional key that declares a parameter as required (true) or not (false) | true
+constraints | array | The optional list of sequenced constraint clauses for the parameter |
+entry_schema | string | The optional key that is used to declare the name of the Datatype definition for entries of set types such as the TOSCA list or map |
+designer_editable | boolean | An optional key that declares a parameter to be editable by designer (true) or not (false) | true
+policy_editable | boolean | An optional key that declares a parameter to be editable by policy (true) or not (false) | true
+policy_schema | array | The optional list of schema definitions used for policy |
+
+Many of the parameter properties have been copied from TOSCA model property definitions and are to be used for service design composition and policy creation. See [section 3.5.8 *Property definition*](http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.1/TOSCA-Simple-Profile-YAML-v1.1.html).
+
+The property `constraints` is a list of objects where each constraint object:
+
+Property Name | Type | Description
+------------- | ---- | -----------
+equal | | Constrains a property or parameter to a value equal to (‘=’) the value declared
+greater_than | number | Constrains a property or parameter to a value greater than (‘>’) the value declared
+greater_or_equal | number | Constrains a property or parameter to a value greater than or equal to (‘>=’) the value declared
+less_than | number | Constrains a property or parameter to a value less than (‘<’) the value declared
+less_or_equal | number | Constrains a property or parameter to a value less than or equal to (‘<=’) the value declared
+valid_values | array | Constrains a property or parameter to a value that is in the list of declared values
+length | number | Constrains the property or parameter to a value of a given length
+min_length | number | Constrains the property or parameter to a value to a minimum length
+max_length | number | Constrains the property or parameter to a value to a maximum length
+
+From the example specification:
+
+```json
+"parameters": [
+ {
+ "name": "threshold",
+ "value": 0.75,
+ "description": "Probability threshold to exceed to be anomalous"
+ }
+]
+```
+
+`threshold` is the configuration parameter and will get set to 0.75 when the configuration gets generated.
+
+## Auxiliary
+
+`auxilary` contains Docker specific details like health check and port mapping information.
+
+Property Name | Type | Description
+------------- | ---- | -----------
+healthcheck | JSON object | *Required*. Health check definition details
+ports | JSON array | each array item maps a container port to the host port. See example below.
+
+### 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.
+
+#### http
+
+Property Name | Type | Description
+------------- | ---- | -----------
+type | string | *Required*. `http`
+interval | string | Interval duration in seconds i.e. `15s`
+timeout | string | Timeout in seconds i.e. `1s`
+endpoint | string | *Required*. GET endpoint provided by the component for Consul to call to check health
+
+Example:
+
+```json
+"auxilary": {
+ "healthcheck": {
+ "type": "http",
+ "interval": "15s",
+ "timeout": "1s",
+ "endpoint": "/my-health"
+ }
+}
+```
+
+#### docker
+
+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:
+
+```json
+"auxilary": {
+ "healthcheck": {
+ "type": "docker",
+ "script": "/app/resources/check_health.py",
+ "timeout": "30s",
+ "interval": "180s"
+ }
+}
+```
+
+### Ports example
+
+Example:
+
+```json
+"auxilary": {
+ "ports": ["8080:8000"]
+}
+```
+
+In the example above, container port 8080 maps to host port 8000.
+
+## Artifacts
+
+`artifacts` contains a list of artifacts associated with this component. For Docker, this would be where you specify your Docker image full path including registry.
+
+Property Name | Type | Description
+------------- | ---- | -----------
+artifacts | JSON array | Each entry is a artifact object
+
+Each artifact object has:
+
+Property Name | Type | Description
+------------- | ---- | -----------
+uri | string | *Required*. Uri to the artifact
+type | string | *Required*. `docker image` or `jar`
+
+## Example
+Here is a full example of a component spec:
+
+```json
+{
+ "self": {
+ "version": "1.0.0",
+ "name": "asimov.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": "asimov.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": "asimov.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": "YOUR_NEXUS_DOCKER_REGISTRY/kpi_anomaly:1.0.0",
+ "type": "docker image"
+ }]
+}
+```
+
+## Generate application configuration
+
+The above example `asimov.component.kpi_anomaly` will get transformed into the following application configuration JSON that is fully resolved and provided at runtime by calling the config binding service:
+
+```json
+{
+ "streams_publishes": {
+ "prediction": ["10.100.1.100:32567"]
+ },
+ "streams_subscribes": {},
+ "threshold": 0.75,
+ "services_calls": {
+ "vnf-db": ["10.100.1.101:32890"]
+ }
+}
+```