diff options
Diffstat (limited to 'docs/components/component-specification/docker-specification.md')
| -rw-r--r-- | docs/components/component-specification/docker-specification.md | 246 |
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"] + } +} +``` |