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, 0 insertions, 246 deletions
diff --git a/docs/components/component-specification/docker-specification.md b/docs/components/component-specification/docker-specification.md deleted file mode 100644 index 2bff6c47..00000000 --- a/docs/components/component-specification/docker-specification.md +++ /dev/null @@ -1,246 +0,0 @@ -# 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"] - } -} -``` |