1 # Common Elements of the Component Specification
3 This page describes the component specification (JSON) sections that are common to both Docker and CDAP components. Differences for each are pointed out below. Elements that are very different, and described in the CDAP or Docker specific pages.
6 Metadata refers to the properties found under the `self` JSON. This group of properties is used to uniquely identify this component specification and identify the component that this specification is used to capture.
13 "name": "asimov.component.kpi_anomaly",
14 "description": "Classifies VNF KPI data as anomalous",
15 "component_type": "docker"
21 Property Name | Type | Description
22 ------------- | ---- | -----------
23 version | string | *Required*. Semantic version for this specification
24 name | string | *Required*. Full name of this component which is also used as this component's catalog id.
25 description | string | *Required*. Human-readable text describing the component and the components functional purpose.
26 component_type | string | *Required*. Identify what containerization technology this component uses: `docker` or `cdap`.
29 Interfaces are the JSON objects found under the `streams` key and the `services` key. These are used to describe the interfaces that the component uses and the interfaces that the component provides. The description of each interface includes the associated [data format](/components/data-formats.md).
32 * The `streams` JSON is for specifying data produced for consumption by other components, and the streams expected to subscribe to that is produced by other components. These are "fire and forget" type interfaces where the publisher of a stream does not expect or parse a response from the subscriber.
33 * The term `stream` here is abstract and neither refers to "CDAP streams" or "DMaaP feeds". While a stream is very likely a DMaaP feed, it could be a direct stream of data being routed via HTTP too. It abstractly refers to a sequence of data leaving a publisher.
34 * Streams have anonymous publish/subscribe semantics, which decouples the production of information from its consumption.
35 * In general, components are not aware of who they are communicating with.
36 * Instead, components that are interested in data, subscribe to the relevant stream; components that generate data publish to the relevant stream.
37 * There can be multiple publishers and subscribers to a stream. Streams are intended for unidirectional, streaming communication.
40 Streams interfaces that implement an HTTP endpoint must support POST.
42 Streams are split into:
44 Property Name | Type | Description
45 ------------- | ---- | -----------
46 subscribes | JSON list | *Required*. List of all available stream interfaces that this component has that can be used for subscribing
47 publishes | JSON list | *Required*. List of all stream interfaces that this component will publish onto
56 "format": "dcae.vnf.kpi",
58 "route": "/data", // for CDAP this value is not used
65 This describes that `asimov.component.kpi_anomaly` exposes an HTTP endpoint called `/data` which accepts requests that have the data format of `dcae.vnf.kpi` version `1.0.0`.
69 Property Name | Type | Description
70 ------------- | ---- | -----------
71 format | string | *Required*. Data format id of the data format that is used by this interface
72 version | string | *Required*. Data format version of the data format that is used by this interface
73 route | string | *Required for HTTP and data router*. The HTTP route that this interface listens on
74 config_key | string | *Required for message_router and data router*. The HTTP route that this interface listens on
75 type | string | *Required*. Type of stream: `http`, `message_router`, `data_router`
80 Message router subscribers are http clients rather than http services and performs a http a `GET` call. Thus, message router subscribers description is structured like message router publishers and requires `config_key`:
85 "format": "dcae.some-format",
87 "config_key": "some_format_handle",
88 "type": "message router"
96 Data router subscribers are http or https services that handle `PUT` requests from data router. Developers must provide the `route` or url path/endpoint that is expected to handle data router requests. This will be used to construct the delivery url needed to register the subscriber to the provisioned feed. Developers must also provide a `config_key` because there is dynamic configuration information associated with the feed that the application will need e.g. username and password. See the page on [DMaaP connection objects](../dcae-cli/dmaap-connection-objects) for more details on the configuration information.
98 Example (not tied to the larger example):
103 "config_key": "some-sub-dr",
104 "format": "sandbox.platform.any",
105 "route": "/identity",
106 "type": "data_router",
121 "format": "asimov.format.integerClassification",
123 "config_key": "prediction",
130 This describes that `asimov.component.kpi_anomaly` publishes by making POST requests to streams that support the data format `asimov.format.integerClassification` version `1.0.0`.
134 Property Name | Type | Description
135 ------------- | ---- | -----------
136 format | string | *Required*. Data format id of the data format that is used by this interface
137 version | string | *Required*. Data format version of the data format that is used by this interface
138 config_key | string | *Required*. The JSON key in the generated application configuration that will be used to pass the downstream component's (the subscriber's) connection information.
139 type | string | *Required*. Type of stream: `http`, `message router`, `data router`
143 Message router publishers are http clients of DMaap message_router. Developers must provide a `config_key` because there is dynamic configuration information associated with the feed that the application will need to receive e.g. topic url, username, password. See the page on [DMaaP connection objects](../dcae-cli/dmaap-connection-objects/#message_router) for more details on the configuration information.
145 Example (not tied to the larger example):
151 "config_key": "some-pub-mr",
152 "format": "sandbox.platform.any",
153 "type": "message_router",
161 Data router publishers are http clients that make `PUT` requests to data router. Developers must also provide a `config_key` because there is dynamic configuration information associated with the feed that the application will need to receive e.g. publish url, username, password. See the page on [DMaaP connection objects](../dcae-cli/dmaap-connection-objects) for more details on the configuration information.
163 Example (not tied to the larger example):
169 "config_key": "some-pub-dr",
170 "format": "sandbox.platform.any",
171 "type": "data_router",
179 Refer to this [Quick Reference](/components/component-specification/streams-grid.md) for a comparison of the Streams 'Publishes' and 'Subscribes' sections.
184 * The publish / subscribe model is a very flexible communication paradigm, but its many-to-many one-way transport is not appropriate for RPC
185 request / reply interactions, which are often required in a distributed system.
186 * Request / reply is done via a Service, which is defined by a pair of messages: one for the request and one for the reply.
188 Services are split into:
190 Property Name | Type | Description
191 ------------- | ---- | -----------
192 calls | JSON list | *Required*. List of all service interfaces that this component will call
193 provides | JSON list | *Required*. List of all service interfaces that this component exposes and provides
196 The JSON `services/calls` is for specifying that the component relies on an HTTP(S) service---the component sends that service an HTTP request, and that service responds with an HTTP reply.
197 An example of this is how string matching (SM) depends on the AAI Broker. SM performs a synchronous REST call to the AAI broker, providing it the VMNAME of the VNF, and the AAI Broker responds with additional details about the VNF. This dependency is expressed via `services/calls`. In contrast, the output of string matching (the alerts it computes) is sent directly to policy as a fire-and-forget interface, so that is an example of a `stream`.
204 "config_key": "vnf-db",
206 "format": "dcae.vnf.meta",
210 "format": "dcae.vnf.kpi",
218 This describes that `asimov.component.kpi_anomaly` will make HTTP calls to a downstream component that accepts requests of data format `dcae.vnf.meta` version `1.0.0` and is expecting the response to be `dcae.vnf.kpi` version `1.0.0`.
222 Property Name | Type | Description
223 ------------- | ---- | -----------
224 request | JSON object | *Required*. Description of the expected request for this downstream interface
225 response | JSON object | *Required*. Description of the expected response for this downstream interface
226 config_key | string | *Required*. The JSON key in the generated application configuration that will be used to pass the downstream component connection information.
228 The JSON object schema for both `request` and `response`:
230 Property Name | Type | Description
231 ------------- | ---- | -----------
232 format | string | *Required*. Data format id of the data format that is used by this interface
233 version | string | *Required*. Data format version of the data format that is used by this interface
243 "route": "/score-vnf",
245 "format": "dcae.vnf.meta",
249 "format": "asimov.format.integerClassification",
256 This describes that `asimov.component.kpi_anomaly` provides a service interface and it is exposed on the `/score-vnf` HTTP endpoint. The endpoint accepts requests that have the data format `dcae.vnf.meta` version `1.0.0` and gives back a response of `asimov.format.integerClassification` version `1.0.0`.
258 `provides` Schema for a Docker component:
260 Property Name | Type | Description
261 ------------- | ---- | -----------
262 request | JSON object | *Required*. Description of the expected request for this interface
263 response | JSON object | *Required*. Description of the expected response for this interface
264 route | string | *Required*. The HTTP route that this interface listens on
266 The JSON object schema for both `request` and `response`:
268 Property Name | Type | Description
269 ------------- | ---- | -----------
270 format | string | *Required*. Data format id of the data format that is used by this interface
271 version | string | *Required*. Data format version of the data format that is used by this interface
273 Note, for CDAP, there is a slight variation due to the way CDAP exposes services:
275 "provides":[ // note this is a list of JSON
279 "service_name":"name CDAP service",
280 "service_endpoint":"greet", // E.g the URL is /services/service_name/methods/service_endpoint
281 "verb":"GET" // GET, PUT, or POST
286 `provides` Schema for a CDAP component:
288 Property Name | Type | Description
289 ------------- | ---- | -----------
290 request | JSON object | *Required*. Description of the expected request data format for this interface
291 response | JSON object | *Required*. Description of the expected response for this interface
292 service_name | string | *Required*. The CDAP service name (eg "Greeting")
293 service_endpoint | string | *Required*. The CDAP service endpoint for this service_name (eg "/greet")
294 verb | string | *Required*. 'GET', 'PUT' or 'POST'
299 `parameters` is where to specify the component's application configuration parameters that are not connection information.
301 Property Name | Type | Description
302 ------------- | ---- | -----------
303 parameters | JSON array | Each entry is a parameter object
305 Parameter object has the following available properties:
307 Property Name | Type | Description | Default
308 ------------- | ---- | ----------- | -------
309 name | string | *Required*. The property name that will be used as the key in the generated config |
310 value | any | *Required*. The default value for the given parameter |
311 description | string | *Required*. Human-readable text describing the parameter like what its for |
312 type | string | The required data type for the parameter |
313 required | boolean | An optional key that declares a parameter as required (true) or not (false) | true
314 constraints | array | The optional list of sequenced constraint clauses for the parameter. See below |
315 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'. Only 1 level is supported at this time |
316 designer_editable | boolean | An optional key that declares a parameter to be editable by designer (true) or not (false) | true
317 sourced_at_deployment | boolean | An optional key that declares a parameter's value to be assigned at deployment time (true) | false
318 policy_editable | boolean | An optional key that declares a parameter to be editable by policy (true) or not (false) | true
319 policy_schema | array | The optional list of schema definitions used for policy. See below |
328 "description": "Probability threshold to exceed to be anomalous"
333 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).
335 The property `constraints` is a list of objects where each constraint object:
337 Property Name | Type | Description
338 ------------- | ---- | -----------
339 equal | | Constrains a property or parameter to a value equal to (‘=’) the value declared
340 greater_than | number | Constrains a property or parameter to a value greater than (‘>’) the value declared
341 greater_or_equal | number | Constrains a property or parameter to a value greater than or equal to (‘>=’) the value declared
342 less_than | number | Constrains a property or parameter to a value less than (‘<’) the value declared
343 less_or_equal | number | Constrains a property or parameter to a value less than or equal to (‘<=’) the value declared
344 valid_values | array | Constrains a property or parameter to a value that is in the list of declared values
345 length | number | Constrains the property or parameter to a value of a given length
346 min_length | number | Constrains the property or parameter to a value to a minimum length
347 max_length | number | Constrains the property or parameter to a value to a maximum length
349 `threshold` is the configuration parameter and will get set to 0.75 when the configuration gets generated.
351 The property `policy_schema` is a list of objects where each policy_schema object:
353 Property Name | Type | Description | Default
354 ------------- | ---- | ----------- | -------
355 name | string | *Required*. parameter name
356 value | string | default value for the parameter
357 description | string | parameter description
358 type | enum | *Required*. data type of the parameter, 'string', 'number', 'boolean', 'datetime', 'list', or 'map'
359 required | boolean | is parameter required or not? | true
360 constraints | array | The optional list of sequenced constraint clauses for the parameter. See above |
361 entry_schema | string | The optional key that is used to declare the name of the Datatype definition for certain types. entry_schema must be defined when the type is either list or map. If the type is list and the entry type is a simple type (string, number, bookean, datetime), follow with an string to describe the entry |
362 | | If the type is list and the entry type is a map, follow with an array to describe the keys for the entry map |
363 | | If the type is list and the entry type is a list, that is not currently supported
364 | | If the type is map, follow with an aray to describe the keys for the map |
366 ## Generated Application Configuration
368 The above example for component `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`:
372 "streams_publishes": {
373 "prediction": ["10.100.1.100:32567"]
375 "streams_subscribes": {},
378 "vnf-db": ["10.100.1.101:32890"]
385 `artifacts` contains a list of artifacts associated with this component. For Docker, this is the full path (including the registry) to the Docker image. For CDAP, this is the full path to the CDAP jar.
387 Property Name | Type | Description
388 ------------- | ---- | -----------
389 artifacts | JSON array | Each entry is a artifact object
393 Property Name | Type | Description
394 ------------- | ---- | -----------
395 uri | string | *Required*. Uri to the artifact, full path
396 type | string | *Required*. `docker image` or `jar`