platformdoc/docs/components/component-specification/docker-specification.md

   1 # Component specification (Docker)
   2
   3 This page contains details specific to Dockerized applications.
   4
   5 The component specification contains the following top-level groups of information:
   6
   7 * [Component metadata](#metadata)
   8 * [Component interfaces](#interfaces) including the associated [data formats](/components/data-formats.md)
   9 * [Configuration parameters](#configuration-parameters)
  10 * [Auxiliary details](#auxilary)
  11 * [List of artifacts](#artifacts)
  12
  13 ## Metadata
  14
  15 See [Metadata](common-specification.md#metadata)
  16
  17 ## Interfaces
  18
  19 See [Interfaces](common-specification.md#interfaces)
  20
  21 ## Configuration parameters
  22
  23 `parameters` is where to specify the component's application configuration parameters that are not connection information.
  24
  25 Property Name | Type | Description
  26 ------------- | ---- | -----------
  27 parameters | JSON array | Each entry is a parameter object
  28
  29 Parameter object has the following available properties:
  30
  31 Property Name | Type | Description | Default
  32 ------------- | ---- | ----------- | -------
  33 name | string | *Required*. The property name that will be used as the key in the generated config |
  34 value | any | *Required*.  The default value for the given parameter |
  35 description | string | *Required*.  Human-readable text describing the parameter like what its for |
  36 type | string | The required data type for the parameter |
  37 required | boolean | An optional key that declares a parameter as required (true) or not (false) | true
  38 constraints | array | The optional list of sequenced constraint clauses for the parameter |
  39 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 |
  40 designer_editable | boolean | An optional key that declares a parameter to be editable by designer (true) or not (false) | true
  41 policy_editable | boolean | An optional key that declares a parameter to be editable by policy (true) or not (false) | true
  42 policy_schema | array | The optional list of schema definitions used for policy |
  43
  44 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).
  45
  46 The property `constraints` is a list of objects where each constraint object:
  47
  48 Property Name | Type | Description
  49 ------------- | ---- | -----------
  50 equal | | Constrains a property or parameter to a value equal to (‘=’) the value declared
  51 greater_than | number | Constrains a property or parameter to a value greater than (‘>’) the value declared
  52 greater_or_equal | number | Constrains a property or parameter to a value greater than or equal to (‘>=’) the value declared
  53 less_than | number | Constrains a property or parameter to a value less than (‘<’) the value declared
  54 less_or_equal | number | Constrains a property or parameter to a value less than or equal to (‘<=’) the value declared
  55 valid_values | array | Constrains a property or parameter to a value that is in the list of declared values
  56 length | number | Constrains the property or parameter to a value of a given length
  57 min_length | number | Constrains the property or parameter to a value to a minimum length
  58 max_length | number | Constrains the property or parameter to a value to a maximum length
  59
  60 From the example specification:
  61
  62 ```json
  63 "parameters": [
  64     {
  65         "name": "threshold",
  66         "value": 0.75,
  67         "description": "Probability threshold to exceed to be anomalous"
  68     }
  69 ]
  70 ```
  71
  72 `threshold` is the configuration parameter and will get set to 0.75 when the configuration gets generated.
  73
  74 ## Auxiliary
  75
  76 `auxilary` contains Docker specific details like health check and port mapping information.
  77
  78 Property Name | Type | Description
  79 ------------- | ---- | -----------
  80 healthcheck | JSON object | *Required*.  Health check definition details
  81 ports | JSON array | each array item maps a container port to the host port. See example below.
  82
  83 ### Health check definition
  84
  85 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.
  86
  87 #### http
  88
  89 Property Name | Type | Description
  90 ------------- | ---- | -----------
  91 type | string | *Required*.  `http`
  92 interval | string | Interval duration in seconds i.e. `15s`
  93 timeout | string | Timeout in seconds i.e. `1s`
  94 endpoint | string | *Required*. GET endpoint provided by the component for Consul to call to check health
  95
  96 Example:
  97
  98 ```json
  99 "auxilary": {
 100     "healthcheck": {
 101         "type": "http",
 102         "interval": "15s",
 103         "timeout": "1s",
 104         "endpoint": "/my-health"
 105     }
 106 }
 107 ```
 108
 109 #### docker
 110
 111 Property Name | Type | Description
 112 ------------- | ---- | -----------
 113 type | string | *Required*.  `docker`
 114 interval | string | Interval duration in seconds i.e. `15s`
 115 timeout | string | Timeout in seconds i.e. `1s`
 116 script | string | *Required*. Full path of script that exists in the Docker container to be executed
 117
 118 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.
 119
 120 Example:
 121
 122 ```json
 123 "auxilary": {
 124     "healthcheck": {
 125         "type": "docker",
 126         "script": "/app/resources/check_health.py",
 127         "timeout": "30s",
 128         "interval": "180s"
 129     }
 130 }
 131 ```
 132
 133 ### Ports example
 134
 135 Example:
 136
 137 ```json
 138 "auxilary": {
 139     "ports": ["8080:8000"]
 140 }
 141 ```
 142
 143 In the example above, container port 8080 maps to host port 8000.
 144
 145 ## Artifacts
 146
 147 `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.
 148
 149 Property Name | Type | Description
 150 ------------- | ---- | -----------
 151 artifacts | JSON array | Each entry is a artifact object
 152
 153 Each artifact object has:
 154
 155 Property Name | Type | Description
 156 ------------- | ---- | -----------
 157 uri | string | *Required*. Uri to the artifact
 158 type | string | *Required*. `docker image` or `jar`
 159
 160 ## Example
 161 Here is a full example of a component spec:
 162
 163 ```json
 164 {
 165     "self": {
 166         "version": "1.0.0",
 167         "name": "asimov.component.kpi_anomaly",
 168         "description": "Classifies VNF KPI data as anomalous",
 169         "component_type": "docker"
 170     },
 171     "streams": {
 172         "subscribes": [{
 173             "format": "dcae.vnf.kpi",
 174             "version": "1.0.0",
 175             "route": "/data",
 176             "type": "http"
 177         }],
 178         "publishes": [{
 179             "format": "asimov.format.integerClassification",
 180             "version": "1.0.0",
 181             "config_key": "prediction",
 182             "type": "http"
 183         }]
 184     },
 185     "services": {
 186         "calls": [{
 187             "config_key": "vnf-db",
 188             "request": {
 189                 "format": "dcae.vnf.meta",
 190                 "version": "1.0.0"
 191                 },
 192             "response": {
 193                 "format": "dcae.vnf.kpi",
 194                 "version": "1.0.0"
 195                 }
 196         }],
 197         "provides": [{
 198             "route": "/score-vnf",
 199             "request": {
 200                 "format": "dcae.vnf.meta",
 201                 "version": "1.0.0"
 202                 },
 203             "response": {
 204                 "format": "asimov.format.integerClassification",
 205                 "version": "1.0.0"
 206                 }
 207         }]
 208     },
 209     "parameters": [
 210         {
 211             "name": "threshold",
 212             "value": 0.75,
 213             "description": "Probability threshold to exceed to be anomalous"
 214         }
 215     ],
 216     "auxilary": {
 217         "healthcheck": {
 218             "type": "http",
 219             "interval": "15s",
 220             "timeout": "1s",
 221             "endpoint": "/my-health"
 222         }
 223     },
 224     "artifacts": [{
 225         "uri": "YOUR_NEXUS_DOCKER_REGISTRY/kpi_anomaly:1.0.0",
 226         "type": "docker image"
 227     }]
 228 }
 229 ```
 230
 231 ## Generate application configuration
 232
 233 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:
 234
 235 ```json
 236 {
 237     "streams_publishes": {
 238         "prediction": ["10.100.1.100:32567"]
 239     },
 240     "streams_subscribes": {},
 241     "threshold": 0.75,
 242     "services_calls": {
 243         "vnf-db": ["10.100.1.101:32890"]
 244     }
 245 }
 246 ```