1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
\r
2 .. http://creativecommons.org/licenses/by/4.0
\r
4 .. _common-specification:
\r
6 Common Elements of the Component Specification
\r
7 ==============================================
\r
9 This page describes the component specification (JSON) sections that are
\r
10 common to both Docker and CDAP components. Differences for each are
\r
11 pointed out below. Elements that are very different, and described in
\r
12 the CDAP or Docker specific pages.
\r
19 Metadata refers to the properties found under the ``self`` JSON. This
\r
20 group of properties is used to uniquely identify this component
\r
21 specification and identify the component that this specification is used
\r
30 "name": "asimov.component.kpi_anomaly",
\r
31 "description": "Classifies VNF KPI data as anomalous",
\r
32 "component_type": "docker"
\r
37 +-------------+--------+----------------+
\r
38 | Property | Type | Description |
\r
40 +=============+========+================+
\r
41 | version | string | *Required*. |
\r
45 | | | specification |
\r
46 +-------------+--------+----------------+
\r
47 | name | string | *Required*. |
\r
59 +-------------+--------+----------------+
\r
60 | description | string | *Required* |
\r
61 | | | Human-readable |
\r
70 +-------------+--------+----------------+
\r
71 | component_t\| string | *Required* |
\r
72 | ype | | Identify |
\r
86 +-------------+--------+----------------+
\r
93 Interfaces are the JSON objects found under the ``streams`` key and the
\r
94 ``services`` key. These are used to describe the interfaces that the
\r
95 component uses and the interfaces that the component provides. The
\r
96 description of each interface includes the associated :any:`data
\r
97 format <data-formats>`.
\r
102 - The ``streams`` JSON is for specifying data produced for consumption
\r
103 by other components, and the streams expected to subscribe to that is
\r
104 produced by other components. These are “fire and forget” type
\r
105 interfaces where the publisher of a stream does not expect or parse a
\r
106 response from the subscriber.
\r
107 - The term ``stream`` here is abstract and neither refers to “CDAP
\r
108 streams” or “DMaaP feeds”. While a stream is very likely a DMaaP
\r
109 feed, it could be a direct stream of data being routed via HTTP too.
\r
110 It abstractly refers to a sequence of data leaving a publisher.
\r
111 - Streams have anonymous publish/subscribe semantics, which decouples
\r
112 the production of information from its consumption.
\r
113 - In general, components are not aware of who they are communicating
\r
115 - Instead, components that are interested in data, subscribe to the
\r
116 relevant stream; components that generate data publish to the
\r
118 - There can be multiple publishers and subscribers to a stream. Streams
\r
119 are intended for unidirectional, streaming communication.
\r
121 Streams interfaces that implement an HTTP endpoint must support POST.
\r
123 Streams are split into:
\r
125 +-------------+----+----------+
\r
126 | Property | Ty\| Descript\|
\r
127 | Name | pe | ion |
\r
128 +=============+====+==========+
\r
129 | subscribes | JS\| *Require\|
\r
147 +-------------+----+----------+
\r
148 | publishes | JS\| *Require\|
\r
162 +-------------+----+----------+
\r
173 "format": "dcae.vnf.kpi",
\r
174 "version": "1.0.0",
\r
175 "route": "/data", // for CDAP this value is not used
\r
181 This describes that ``asimov.component.kpi_anomaly`` exposes an HTTP
\r
182 endpoint called ``/data`` which accepts requests that have the data
\r
183 format of ``dcae.vnf.kpi`` version ``1.0.0``.
\r
185 ``subscribes`` Schema:
\r
187 +-------------+----+--------------------+
\r
188 | Property | Ty\| Descript\ |
\r
189 | Name | pe | ion |
\r
190 +=============+====+====================+
\r
191 | format | st\| *Require\ |
\r
203 +-------------+----+--------------------+
\r
204 | version | st\| *Require\ |
\r
217 +-------------+----+--------------------+
\r
218 | route | st\| *Require\ |
\r
220 | | ng | for HTTP |
\r
231 +-------------+----+--------------------+
\r
232 | config_key | st\| *Require\ |
\r
235 | | | message_router\ |
\r
246 +-------------+----+--------------------+
\r
247 | type | st\| *Require\ |
\r
253 | | | ``message_router`` |
\r
255 | | | ``data_router`` |
\r
256 +-------------+----+--------------------+
\r
258 .. _message-router:
\r
263 Message router subscribers are http clients rather than http services
\r
264 and performs a http a ``GET`` call. Thus, message router subscribers
\r
265 description is structured like message router publishers and requires
\r
272 "format": "dcae.some-format",
\r
273 "version": "1.0.0",
\r
274 "config_key": "some_format_handle",
\r
275 "type": "message router"
\r
286 Data router subscribers are http or https services that handle ``PUT``
\r
287 requests from data router. Developers must provide the ``route`` or url
\r
288 path/endpoint that is expected to handle data router requests. This will
\r
289 be used to construct the delivery url needed to register the subscriber
\r
290 to the provisioned feed. Developers must also provide a ``config_key``
\r
291 because there is dynamic configuration information associated with the
\r
292 feed that the application will need e.g. username and password. See the
\r
293 page on :doc:`DMaaP connection objects <../dcae-cli/dmaap-connection-objects>` for more details on
\r
294 the configuration information.
\r
296 Example (not tied to the larger example):
\r
302 "config_key": "some-sub-dr",
\r
303 "format": "sandbox.platform.any",
\r
304 "route": "/identity",
\r
305 "type": "data_router",
\r
321 "format": "asimov.format.integerClassification",
\r
322 "version": "1.0.0",
\r
323 "config_key": "prediction",
\r
328 This describes that ``asimov.component.kpi_anomaly`` publishes by making
\r
329 POST requests to streams that support the data format
\r
330 ``asimov.format.integerClassification`` version ``1.0.0``.
\r
332 ``publishes`` Schema:
\r
334 +-------------+----+--------------------+
\r
335 | Property | Ty\| Descript\ |
\r
336 | Name | pe | ion |
\r
337 +=============+====+====================+
\r
338 | format | st\| *Require\ |
\r
350 +-------------+----+--------------------+
\r
351 | version | st\| *Require\ |
\r
364 +-------------+----+--------------------+
\r
365 | config_key | st\| *Require\ |
\r
367 | | ng | The JSON |
\r
391 +-------------+----+--------------------+
\r
392 | type | st\| *Require\ |
\r
398 | | | ``message_router`` |
\r
400 | | | ``data_router`` |
\r
401 +-------------+----+--------------------+
\r
403 .. message-router-1:
\r
408 Message router publishers are http clients of DMaap message_router.
\r
409 Developers must provide a ``config_key`` because there is dynamic
\r
410 configuration information associated with the feed that the application
\r
411 will need to receive e.g. topic url, username, password. See the page on
\r
412 :doc:`DMaaP connection objects <../dcae-cli/dmaap-connection-objects>` for more details on
\r
413 the configuration information.
\r
415 Example (not tied to the larger example):
\r
422 "config_key": "some-pub-mr",
\r
423 "format": "sandbox.platform.any",
\r
424 "type": "message_router",
\r
434 Data router publishers are http clients that make ``PUT`` requests to
\r
435 data router. Developers must also provide a ``config_key`` because there
\r
436 is dynamic configuration information associated with the feed that the
\r
437 application will need to receive e.g. publish url, username, password.
\r
438 See the page on :doc:`DMaaP connection objects <../dcae-cli/dmaap-connection-objects>` for more details on
\r
439 the configuration information.
\r
441 Example (not tied to the larger example):
\r
448 "config_key": "some-pub-dr",
\r
449 "format": "sandbox.platform.any",
\r
450 "type": "data_router",
\r
458 Refer to this :doc:`Quick Reference <streams-grid>` for a
\r
459 comparison of the Streams ‘Publishes’ and ‘Subscribes’ sections.
\r
464 - The publish / subscribe model is a very flexible communication
\r
465 paradigm, but its many-to-many one-way transport is not appropriate
\r
466 for RPC request / reply interactions, which are often required in a
\r
467 distributed system.
\r
468 - Request / reply is done via a Service, which is defined by a pair of
\r
469 messages: one for the request and one for the reply.
\r
471 Services are split into:
\r
473 +-------------+----+----------+
\r
474 | Property | Ty\| Descript\|
\r
475 | Name | pe | ion |
\r
476 +=============+====+==========+
\r
477 | calls | JS\| *Require\|
\r
490 +-------------+----+----------+
\r
491 | provides | JS\| *Require\|
\r
505 +-------------+----+----------+
\r
510 The JSON ``services/calls`` is for specifying that the component relies
\r
511 on an HTTP(S) service—the component sends that service an HTTP request,
\r
512 and that service responds with an HTTP reply. An example of this is how
\r
513 string matching (SM) depends on the AAI Broker. SM performs a
\r
514 synchronous REST call to the AAI broker, providing it the VMNAME of the
\r
515 VNF, and the AAI Broker responds with additional details about the VNF.
\r
516 This dependency is expressed via ``services/calls``. In contrast, the
\r
517 output of string matching (the alerts it computes) is sent directly to
\r
518 policy as a fire-and-forget interface, so that is an example of a
\r
527 "config_key": "vnf-db",
\r
529 "format": "dcae.vnf.meta",
\r
533 "format": "dcae.vnf.kpi",
\r
540 This describes that ``asimov.component.kpi_anomaly`` will make HTTP
\r
541 calls to a downstream component that accepts requests of data format
\r
542 ``dcae.vnf.meta`` version ``1.0.0`` and is expecting the response to be
\r
543 ``dcae.vnf.kpi`` version ``1.0.0``.
\r
547 +-------------+----+----------+
\r
548 | Property | Ty\| Descript\|
\r
549 | Name | pe | ion |
\r
550 +=============+====+==========+
\r
551 | request | JS\| *Require\|
\r
553 | | ob\| Descript\|
\r
563 +-------------+----+----------+
\r
564 | response | JS\| *Require\|
\r
566 | | ob\| Descript\|
\r
576 +-------------+----+----------+
\r
577 | config_key | st\| *Require\|
\r
579 | | ng | The JSON |
\r
600 +-------------+----+----------+
\r
602 The JSON object schema for both ``request`` and ``response``:
\r
604 +-------------+----+----------+
\r
605 | Property | Ty\| Descript\|
\r
606 | Name | pe | ion |
\r
607 +=============+====+==========+
\r
608 | format | st\| *Require\|
\r
620 +-------------+----+----------+
\r
621 | version | st\| *Require\|
\r
634 +-------------+----+----------+
\r
646 "route": "/score-vnf",
\r
648 "format": "dcae.vnf.meta",
\r
652 "format": "asimov.format.integerClassification",
\r
658 This describes that ``asimov.component.kpi_anomaly`` provides a service
\r
659 interface and it is exposed on the ``/score-vnf`` HTTP endpoint. The
\r
660 endpoint accepts requests that have the data format ``dcae.vnf.meta``
\r
661 version ``1.0.0`` and gives back a response of
\r
662 ``asimov.format.integerClassification`` version ``1.0.0``.
\r
664 ``provides`` Schema for a Docker component:
\r
666 +-------------+----+----------+
\r
667 | Property | Ty\| Descript\|
\r
668 | Name | pe | ion |
\r
669 +=============+====+==========+
\r
670 | request | JS\| *Require\|
\r
672 | | ob\| Descript\|
\r
680 +-------------+----+----------+
\r
681 | response | JS\| *Require\|
\r
683 | | ob\| Descript\|
\r
691 +-------------+----+----------+
\r
692 | route | st\| *Require\|
\r
694 | | ng | The HTTP |
\r
702 +-------------+----+----------+
\r
704 The JSON object schema for both ``request`` and ``response``:
\r
706 +-------------+----+----------+
\r
707 | Property | Ty\| Descript\|
\r
708 | Name | pe | ion |
\r
709 +=============+====+==========+
\r
710 | format | st\| *Require\|
\r
722 +-------------+----+----------+
\r
723 | version | st\| *Require\|
\r
736 +-------------+----+----------+
\r
738 Note, for CDAP, there is a slight variation due to the way CDAP exposes
\r
743 "provides":[ // note this is a list of JSON
\r
747 "service_name":"name CDAP service",
\r
748 "service_endpoint":"greet", // E.g the URL is /services/service_name/methods/service_endpoint
\r
749 "verb":"GET" // GET, PUT, or POST
\r
753 ``provides`` Schema for a CDAP component:
\r
755 +-------------+----+-----------+
\r
756 | Property | Ty\| Descript\ |
\r
757 | Name | pe | ion |
\r
758 +=============+====+===========+
\r
759 | request | JS\| *Require\ |
\r
761 | | ob\| Descript\ |
\r
771 +-------------+----+-----------+
\r
772 | response | JS\| *Require\ |
\r
774 | | ob\| Descript\ |
\r
782 +-------------+----+-----------+
\r
783 | service_nam\| st\| *Require\ |
\r
785 | | ng | The CDAP |
\r
790 +-------------+----+-----------+
\r
791 | service_end | st\| *Require\ |
\r
792 | point | ri\| d*. |
\r
793 | | ng | The CDAP |
\r
802 +-------------+----+-----------+
\r
803 | verb | st\| *Require\ |
\r
808 +-------------+----+-----------+
\r
813 ``parameters`` is where to specify the component’s application
\r
814 configuration parameters that are not connection information.
\r
816 +---------------+------------+----------------------------------+
\r
817 | Property Name | Type | Description |
\r
818 +===============+============+==================================+
\r
819 | parameters | JSON array | Each entry is a parameter object |
\r
820 +---------------+------------+----------------------------------+
\r
822 Parameter object has the following available properties:
\r
824 +--------------+----+----------+------+
\r
825 | Property | Ty\| Descript\| Defa\|
\r
826 | Name | pe | ion | ult |
\r
827 +==============+====+==========+======+
\r
828 | name | st\| *Require\| |
\r
841 +--------------+----+----------+------+
\r
842 | value | an\| *Require\| |
\r
851 +--------------+----+----------+------+
\r
852 | description | st\| *Require\| |
\r
854 | | ng | Human-re\| |
\r
865 +--------------+----+----------+------+
\r
866 | type | st\| The | |
\r
867 | | ri\| required | |
\r
873 +--------------+----+----------+------+
\r
874 | required | bo\| An | true |
\r
875 | | ol\| optional | |
\r
876 | | ea\| key that | |
\r
877 | | n | declares | |
\r
886 +--------------+----+----------+------+
\r
887 | constraints | ar\| The | |
\r
888 | | ra\| optional | |
\r
889 | | y | list of | |
\r
900 +--------------+----+----------+------+
\r
901 | entry_schem\ | st\| The | |
\r
902 | a | ri\| optional | |
\r
903 | | ng | key that | |
\r
928 +--------------+----+----------+------+
\r
929 | designer_ed\ | bo\| An | true |
\r
930 | itable | ol\| optional | |
\r
931 | | ea\| key that | |
\r
932 | | n | declares | |
\r
943 +--------------+----+----------+------+
\r
944 | sourced_at_d\| bo\| An | fals\|
\r
945 | eployment | ol\| optional | e |
\r
946 | | ea\| key that | |
\r
947 | | n | declares | |
\r
959 +--------------+----+----------+------+
\r
960 | policy_edit\ | bo\| An | true |
\r
961 | able | ol\| optional | |
\r
962 | | ea\| key that | |
\r
963 | | n | declares | |
\r
974 +--------------+----+----------+------+
\r
975 | policy_sche\ | ar\| The | |
\r
976 | ma | ra\| optional | |
\r
977 | | y | list of | |
\r
985 +--------------+----+----------+------+
\r
993 "name": "threshold",
\r
995 "description": "Probability threshold to exceed to be anomalous"
\r
999 Many of the parameter properties have been copied from TOSCA model
\r
1000 property definitions and are to be used for service design composition
\r
1001 and policy creation. See `section 3.5.8 *Property
\r
1002 definition* <http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.1/TOSCA-Simple-Profile-YAML-v1.1.html>`__.
\r
1004 The property ``constraints`` is a list of objects where each constraint
\r
1007 +--------------+----+----------+
\r
1008 | Property | Ty\| Descript\|
\r
1009 | Name | pe | ion |
\r
1010 +==============+====+==========+
\r
1011 | equal | | Constrai\|
\r
1025 +--------------+----+----------+
\r
1026 | greater_tha\ | nu\| Constrai\|
\r
1041 +--------------+----+----------+
\r
1042 | greater_or_e\| nu\| Constrai\|
\r
1043 | qual | mb\| ns |
\r
1058 +--------------+----+----------+
\r
1059 | less_than | nu\| Constrai\|
\r
1074 +--------------+----+----------+
\r
1075 | less_or_equ\ | nu\| Constrai\|
\r
1091 +--------------+----+----------+
\r
1092 | valid_value\ | ar\| Constrai\|
\r
1106 +--------------+----+----------+
\r
1107 | length | nu\| Constrai\|
\r
1118 +--------------+----+----------+
\r
1119 | min_length | nu\| Constrai\|
\r
1131 +--------------+----+----------+
\r
1132 | max_length | nu\| Constrai\|
\r
1144 +--------------+----+----------+
\r
1146 ``threshold`` is the configuration parameter and will get set to 0.75
\r
1147 when the configuration gets generated.
\r
1149 The property ``policy_schema`` is a list of objects where each
\r
1150 policy_schema object:
\r
1152 +-------------+----+----------+------+
\r
1153 | Property | Ty\| Descript\| Defa\|
\r
1154 | Name | pe | ion | ult |
\r
1155 +=============+====+==========+======+
\r
1156 | name | st\| *Require\| |
\r
1158 | | ng | paramete\| |
\r
1161 +-------------+----+----------+------+
\r
1162 | value | st\| default | |
\r
1163 | | ri\| value | |
\r
1164 | | ng | for the | |
\r
1165 | | | paramete\| |
\r
1167 +-------------+----+----------+------+
\r
1168 | description | st\| paramete\| |
\r
1170 | | ng | descript\| |
\r
1172 +-------------+----+----------+------+
\r
1173 | type | en\| *Require\| |
\r
1178 | | | paramete\| |
\r
1180 | | | ‘string’ | |
\r
1182 | | | ‘number’ | |
\r
1184 | | | ‘boolean | |
\r
1186 | | | ‘datetim\| |
\r
1189 | | | or ‘map’ | |
\r
1190 +-------------+----+----------+------+
\r
1191 | required | bo\| is | true |
\r
1192 | | ol\| paramete\| |
\r
1194 | | n | required | |
\r
1196 +-------------+----+----------+------+
\r
1197 | constraints | ar\| The | |
\r
1198 | | ra\| optional | |
\r
1199 | | y | list of | |
\r
1200 | | | sequence\| |
\r
1202 | | | constrai\| |
\r
1206 | | | paramete\| |
\r
1210 +-------------+----+----------+------+
\r
1211 | entry_schem\| st\| The | |
\r
1212 | a | ri\| optional | |
\r
1213 | | ng | key that | |
\r
1217 | | | the name | |
\r
1219 | | | Datatype | |
\r
1220 | | | definiti\| |
\r
1225 | | | entry_sc\| |
\r
1229 | | | when the | |
\r
1234 | | | the type | |
\r
1239 | | | a simple | |
\r
1241 | | | (string, | |
\r
1243 | | | bookean, | |
\r
1244 | | | datetime | |
\r
1250 | | | describe | |
\r
1253 +-------------+----+----------+------+
\r
1302 +-------------+----+----------+------+
\r
1340 +-------------+----+----------+------+
\r
1372 +-------------+----+----------+------+
\r
1374 Generated Application Configuration
\r
1375 -----------------------------------
\r
1377 The above example for component ``asimov.component.kpi_anomaly`` will
\r
1378 get transformed into the following application configuration JSON that
\r
1379 is fully resolved and provided at runtime by calling the
\r
1380 ``config binding service``:
\r
1385 "streams_publishes": {
\r
1386 "prediction": ["10.100.1.100:32567"]
\r
1388 "streams_subscribes": {},
\r
1389 "threshold": 0.75,
\r
1390 "services_calls": {
\r
1391 "vnf-db": ["10.100.1.101:32890"]
\r
1400 ``artifacts`` contains a list of artifacts associated with this
\r
1401 component. For Docker, this is the full path (including the registry) to
\r
1402 the Docker image. For CDAP, this is the full path to the CDAP jar.
\r
1404 +---------------+------------+---------------------------------+
\r
1405 | Property Name | Type | Description |
\r
1406 +===============+============+=================================+
\r
1407 | artifacts | JSON array | Each entry is a artifact object |
\r
1408 +---------------+------------+---------------------------------+
\r
1410 ``artifact`` Schema:
\r
1412 +---------------+--------+--------------------------------------------+
\r
1413 | Property Name | Type | Description |
\r
1414 +===============+========+============================================+
\r
1415 | uri | string | *Required*. Uri to the artifact, full path |
\r
1416 +---------------+--------+--------------------------------------------+
\r
1417 | type | string | *Required*. ``docker image`` or ``jar`` |
\r
1418 +---------------+--------+--------------------------------------------+
\r
Code Review / dcaegen2.git / blob