diff options
Diffstat (limited to 'docs/sections/design-components/component-specification')
8 files changed, 3452 insertions, 0 deletions
diff --git a/docs/sections/design-components/component-specification/component-json-schema.rst b/docs/sections/design-components/component-specification/component-json-schema.rst new file mode 100644 index 00000000..18139598 --- /dev/null +++ b/docs/sections/design-components/component-specification/component-json-schema.rst @@ -0,0 +1,933 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +.. _dcae-component-schema: + +Component JSON Schema Definition +================================ + +The schema file used for DCAE onboarding is maintained in `gerrit <https://git.onap.org/dcaegen2/platform/plain/mod/component-json-schemas/component-specification/dcae-cli-v2/component-spec-schema.json>`__ +The same is provided below for documentation reference. + + +:: + + { + "$schema": "http://json-schema.org/draft-04/schema#", + "title": "Component specification schema", + "type": "object", + "properties": { + "self": { + "type": "object", + "properties": { + "version": { + "$ref": "#/definitions/version" + }, + "description": { + "type": "string" + }, + "component_type": { + "type": "string", + "enum": [ + "docker", + "cdap" + ] + }, + "name": { + "$ref": "#/definitions/name" + } + }, + "required": [ + "version", + "name", + "description", + "component_type" + ] + }, + "streams": { + "type": "object", + "properties": { + "publishes": { + "type": "array", + "uniqueItems": true, + "items": { + "oneOf": [ + { "$ref": "#/definitions/publisher_http" }, + { "$ref": "#/definitions/publisher_message_router" }, + { "$ref": "#/definitions/publisher_data_router" } + ] + } + }, + "subscribes": { + "type": "array", + "uniqueItems": true, + "items": { + "oneOf": [ + { "$ref": "#/definitions/subscriber_http" }, + { "$ref": "#/definitions/subscriber_message_router" }, + { "$ref": "#/definitions/subscriber_data_router" } + ] + } + } + }, + "required": [ + "publishes", + "subscribes" + ] + }, + "services": { + "type": "object", + "properties": { + "calls": { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/definitions/caller" + } + }, + "provides": { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/definitions/provider" + } + } + }, + "required": [ + "calls", + "provides" + ] + }, + "parameters" : { + "anyOf" : [ + {"$ref": "#/definitions/docker-parameters"}, + {"$ref": "#/definitions/cdap-parameters"} + ] + }, + "auxilary": { + "oneOf" : [ + {"$ref": "#/definitions/auxilary_cdap"}, + {"$ref": "#/definitions/auxilary_docker"} + ] + }, + "artifacts": { + "type": "array", + "description": "List of component artifacts", + "items": { + "$ref": "#/definitions/artifact" + } + }, + "policy_info": { + "type": "object", + "properties": { + "policy": + { + "type": "array", + "items": + { + "type": "object", + "properties": + { + "node_label": + { + "type": "string" + }, + "policy_id": + { + "type": "string" + }, + "policy_model_id": + { + "type": "string" + } + }, + "required": ["node_label", "policy_model_id"] + } + } + }, + "additionalProperties": false + } + }, + "required": [ + "self", + "streams", + "services", + "parameters", + "auxilary", + "artifacts" + ], + "additionalProperties": false, + "definitions": { + "cdap-parameters": { + "description" : "There are three seperate ways to pass parameters to CDAP: app config, app preferences, program preferences. These are all treated as optional.", + "type": "object", + "properties" : { + "program_preferences": { + "description" : "A list of {program_id, program_type, program_preference} objects where program_preference is an object passed into program_id of type program_type", + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/definitions/program_preference" + } + }, + "app_preferences" : { + "description" : "Parameters Passed down to the CDAP preference API", + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/definitions/parameter" + } + }, + "app_config" : { + "description" : "Parameters Passed down to the CDAP App Config", + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/definitions/parameter" + } + } + } + }, + "program_preference": { + "type": "object", + "properties": { + "program_type": { + "$ref": "#/definitions/program_type" + }, + "program_id": { + "type": "string" + }, + "program_pref":{ + "description" : "Parameters that the CDAP developer wants pushed to this program's preferences API. Optional", + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/definitions/parameter" + } + } + }, + "required": ["program_type", "program_id", "program_pref"] + }, + "program_type": { + "type": "string", + "enum": ["flows","mapreduce","schedules","spark","workflows","workers","services"] + }, + "docker-parameters": { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/definitions/parameter" + } + }, + "parameter": { + "oneOf": [ + {"$ref": "#/definitions/parameter-list"}, + {"$ref": "#/definitions/parameter-other"} + ] + }, + "parameter-list": { + "properties": { + "name": { + "type": "string" + }, + "value": { + "description": "Default value for the parameter" + }, + "description": { + "description": "Description for the parameter.", + "type": "string" + }, + "type": { + "description": "Only valid type is list, the entry_schema is required - which contains the type of the list element. All properties set for the parameter apply to all elements in the list at this time", + "type": "string", + "enum": ["list"] + }, + "required": { + "description": "An optional key that declares a parameter as required (true) or not (false). Default is true.", + "type": "boolean", + "default": true + }, + "constraints": { + "description": "The optional list of sequenced constraint clauses for the parameter.", + "type": "array", + "items": { + "$ref": "#/definitions/parameter-constraints" + } + }, + "entry_schema": { + "description": "The optional property used to declare the name of the Datatype definition for entries of certain types. entry_schema must be defined when the type is list. This is the only type it is currently supported for.", + "type": "object", + "uniqueItems": true, + "items": {"$ref": "#/definitions/list-parameter"} + }, + "designer_editable": { + "description": "A required property that declares a parameter as editable by designer in SDC Tool (true) or not (false).", + "type": "boolean" + }, + "sourced_at_deployment": { + "description": "A required property that declares that a parameter is assigned at deployment time (true) or not (false).", + "type": "boolean" + }, + "policy_editable": { + "description": "A required property that declares a parameter as editable by DevOps in Policy UI (true) or not (false).", + "type": "boolean" + }, + "policy_group": { + "description": "An optional property used to group policy_editable parameters into groups. Each group will become it's own policy model. Any parameters without this property will be grouped together to form their own policy model", + "type": "string" + }, + "policy_schema" :{ + "type": "array", + "uniqueItems": true, + "items": {"$ref": "#/definitions/policy_schema_parameter"} + } + }, + "required": [ + "name", + "value", + "description", + "designer_editable", + "policy_editable", + "sourced_at_deployment", + "entry_schema" + ], + "additionalProperties": false, + "dependencies": { + "policy_schema": ["policy_editable"] + } + }, + "parameter-other": { + "properties": { + "name": { + "type": "string" + }, + "value": { + "description": "Default value for the parameter" + }, + "description": { + "description": "Description for the parameter.", + "type": "string" + }, + "type": { + "description": "The required data type for the parameter.", + "type": "string", + "enum": [ "string", "number", "boolean", "datetime" ] + }, + "required": { + "description": "An optional key that declares a parameter as required (true) or not (false). Default is true.", + "type": "boolean", + "default": true + }, + "constraints": { + "description": "The optional list of sequenced constraint clauses for the parameter.", + "type": "array", + "items": { + "$ref": "#/definitions/parameter-constraints" + } + }, + "designer_editable": { + "description": "A required property that declares a parameter as editable by designer in SDC Tool (true) or not (false).", + "type": "boolean" + }, + "sourced_at_deployment": { + "description": "A required property that declares that a parameter is assigned at deployment time (true) or not (false).", + "type": "boolean" + }, + "policy_editable": { + "description": "A required property that declares a parameter as editable in Policy UI (true) or not (false).", + "type": "boolean" + }, + "policy_group": { + "description": "An optional property used to group policy_editable parameters into groups. Each group will become it's own policy model. Any parameters without this property will be grouped together to form their own policy model", + "type": "string" + }, + "policy_schema" :{ + "description": "An optional property used to define policy_editable parameters as lists or maps", + "type": "array", + "uniqueItems": true, + "items": {"$ref": "#/definitions/policy_schema_parameter"} + } + }, + "required": [ + "name", + "value", + "description", + "designer_editable", + "sourced_at_deployment", + "policy_editable" + ], + "additionalProperties": false, + "dependencies": { + "policy_schema": ["policy_editable"] + } + }, + "list-parameter": { + "type": "object", + "properties": { + "type": { + "description": "The required data type for each parameter in the list.", + "type": "string", + "enum": ["string", "number"] + } + }, + "required": [ + "type" + ], + "additionalProperties": false + }, + "policy_schema_parameter": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "value": { + "description": "Default value for the parameter" + }, + "description": { + "description": "Description for the parameter.", + "type": "string" + }, + "type": { + "description": "The required data type for the parameter.", + "type": "string", + "enum": [ "string", "number", "boolean", "datetime", "list", "map" ] + }, + "required": { + "description": "An optional key that declares a parameter as required (true) or not (false). Default is true.", + "type": "boolean", + "default": true + }, + "constraints": { + "description": "The optional list of sequenced constraint clauses for the parameter.", + "type": "array", + "items": { + "$ref": "#/definitions/parameter-constraints" + } + }, + "entry_schema": { + "description": "The optional key that is used to declare the name of the Datatype definition for entries of 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, boolean, datetime), follow with a simple string to describe the entry type. If the type is list and the entry type is a map, follow with an array to describe the keys for the entry map. If the type is list and the entry type is also list, this is not currently supported here. If the type is map, then follow with an array to describe the keys for this map. ", + "type": "array", "uniqueItems": true, "items": {"$ref": "#/definitions/policy_schema_parameter"} + } + }, + "required": [ + "name", + "type" + ], + "additionalProperties": false + }, + "parameter-constraints": { + "type": "object", + "additionalProperties": false, + "properties": { + "equal": { + "description": "Constrains a property or parameter to a value equal to (‘=’) the value declared." + }, + "greater_than": { + "description": "Constrains a property or parameter to a value greater than (‘>’) the value declared.", + "type": "number" + }, + "greater_or_equal": { + "description": "Constrains a property or parameter to a value greater than or equal to (‘>=’) the value declared.", + "type": "number" + }, + "less_than": { + "description": "Constrains a property or parameter to a value less than (‘<’) the value declared.", + "type": "number" + }, + "less_or_equal": { + "description": "Constrains a property or parameter to a value less than or equal to (‘<=’) the value declared.", + "type": "number" + }, + "valid_values": { + "description": "Constrains a property or parameter to a value that is in the list of declared values.", + "type": "array" + }, + "length": { + "description": "Constrains the property or parameter to a value of a given length.", + "type": "number" + }, + "min_length": { + "description": "Constrains the property or parameter to a value to a minimum length.", + "type": "number" + }, + "max_length": { + "description": "Constrains the property or parameter to a value to a maximum length.", + "type": "number" + } + } + }, + "stream_message_router": { + "type": "object", + "properties": { + "format": { + "$ref": "#/definitions/name" + }, + "version": { + "$ref": "#/definitions/version" + }, + "config_key": { + "type": "string" + }, + "type": { + "description": "Type of stream to be used", + "type": "string", + "enum": [ + "message router", "message_router" + ] + } + }, + "required": [ + "format", + "version", + "config_key", + "type" + ] + }, + "publisher_http": { + "type": "object", + "properties": { + "format": { + "$ref": "#/definitions/name" + }, + "version": { + "$ref": "#/definitions/version" + }, + "config_key": { + "type": "string" + }, + "type": { + "description": "Type of stream to be used", + "type": "string", + "enum": [ + "http", + "https" + ] + } + }, + "required": [ + "format", + "version", + "config_key", + "type" + ] + }, + "publisher_message_router": { + "$ref": "#/definitions/stream_message_router" + }, + "publisher_data_router": { + "type": "object", + "properties": { + "format": { + "$ref": "#/definitions/name" + }, + "version": { + "$ref": "#/definitions/version" + }, + "config_key": { + "type": "string" + }, + "type": { + "description": "Type of stream to be used", + "type": "string", + "enum": [ + "data router", "data_router" + ] + } + }, + "required": [ + "format", + "version", + "config_key", + "type" + ] + }, + "subscriber_http": { + "type": "object", + "properties": { + "format": { + "$ref": "#/definitions/name" + }, + "version": { + "$ref": "#/definitions/version" + }, + "route": { + "type": "string" + }, + "type": { + "description": "Type of stream to be used", + "type": "string", + "enum": [ + "http", + "https" + ] + } + }, + "required": [ + "format", + "version", + "route", + "type" + ] + }, + "subscriber_message_router": { + "$ref": "#/definitions/stream_message_router" + }, + "subscriber_data_router": { + "type": "object", + "properties": { + "format": { + "$ref": "#/definitions/name" + }, + "version": { + "$ref": "#/definitions/version" + }, + "route": { + "type": "string" + }, + "type": { + "description": "Type of stream to be used", + "type": "string", + "enum": [ + "data router", "data_router" + ] + }, + "config_key": { + "description": "Data router subscribers require config info to setup their endpoints to handle requests. For example, needs username and password", + "type": "string" + } + }, + "required": [ + "format", + "version", + "route", + "type", + "config_key" + ] + }, + "provider" : { + "oneOf" : [ + {"$ref": "#/definitions/docker-provider"}, + {"$ref": "#/definitions/cdap-provider"} + ] + }, + "cdap-provider" : { + "type": "object", + "properties" : { + "request": { + "$ref": "#/definitions/formatPair" + }, + "response": { + "$ref": "#/definitions/formatPair" + }, + "service_name" : { + "type" : "string" + }, + "service_endpoint" : { + "type" : "string" + }, + "verb" : { + "type": "string", + "enum": ["GET", "PUT", "POST", "DELETE"] + } + }, + "required" : [ + "request", + "response", + "service_name", + "service_endpoint", + "verb" + ] + }, + "docker-provider": { + "type": "object", + "properties": { + "request": { + "$ref": "#/definitions/formatPair" + }, + "response": { + "$ref": "#/definitions/formatPair" + }, + "route": { + "type": "string" + }, + "verb": { + "type": "string", + "enum": ["GET", "PUT", "POST", "DELETE"] + } + }, + "required": [ + "request", + "response", + "route" + ] + }, + "caller": { + "type": "object", + "properties": { + "request": { + "$ref": "#/definitions/formatPair" + }, + "response": { + "$ref": "#/definitions/formatPair" + }, + "config_key": { + "type": "string" + } + }, + "required": [ + "request", + "response", + "config_key" + ] + }, + "formatPair": { + "type": "object", + "properties": { + "format": { + "$ref": "#/definitions/name" + }, + "version": { + "$ref": "#/definitions/version" + } + } + }, + "name": { + "type": "string" + }, + "version": { + "type": "string", + "pattern": "^(\\d+\\.)(\\d+\\.)(\\*|\\d+)$" + }, + "artifact": { + "type": "object", + "description": "Component artifact object", + "properties": { + "uri": { + "type": "string", + "description": "Uri to artifact" + }, + "type": { + "type": "string", + "enum": ["jar", "docker image"] + } + }, + "required": ["uri", "type"] + }, + + "auxilary_cdap": { + "title": "cdap component specification schema", + "type": "object", + "properties": { + "streamname": { + "type": "string" + }, + "artifact_name" : { + "type": "string" + }, + "artifact_version" : { + "type": "string", + "pattern": "^(\\d+\\.)(\\d+\\.)(\\*|\\d+)$" + }, + "namespace":{ + "type": "string", + "description" : "optional" + }, + "programs": { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/definitions/cdap_program" + } + } + }, + "required": [ + "streamname", + "programs", + "artifact_name", + "artifact_version" + ] + }, + "cdap_program_type": { + "type": "string", + "enum": ["flows","mapreduce","schedules","spark","workflows","workers","services"] + }, + "cdap_program": { + "type": "object", + "properties": { + "program_type": { + "$ref": "#/definitions/cdap_program_type" + }, + "program_id": { + "type": "string" + } + }, + "required": ["program_type", "program_id"] + }, + + "auxilary_docker": { + "title": "Docker component specification schema", + "type": "object", + "properties": { + "healthcheck": { + "description": "Define the health check that Consul should perfom for this component", + "type": "object", + "oneOf": [ + { "$ref": "#/definitions/docker_healthcheck_http" }, + { "$ref": "#/definitions/docker_healthcheck_script" } + ] + }, + "ports": { + "description": "Port mapping to be used for Docker containers. Each entry is of the format <container port>:<host port>.", + "type": "array", + "items": { + "type": "string" + } + }, + "log_info": { + "description": "Component specific details for logging", + "type": "object", + "properties": { + "log_directory": { + "description": "The path in the container where the component writes its logs. If the component is following the EELF requirements, this would be the directory where the four EELF files are being written. (Other logs can be placed in the directory--if their names in '.log', they'll also be sent into ELK.)", + "type": "string" + }, + "alternate_fb_path": { + "description": "By default, the log volume is mounted at /var/log/onap/<component_type> in the sidecar container's file system. 'alternate_fb_path' allows overriding the default. Will affect how the log data can be found in the ELK system.", + "type": "string" + } + }, + "additionalProperties": false + }, + "tls_info": { + "description": "Component information to use tls certificates", + "type": "object", + "properties": { + "cert_directory": { + "description": "The path in the container where the component certificates will be placed by the init container", + "type": "string" + }, + "use_tls": { + "description": "Boolean flag to determine if the application is using tls certificates", + "type": "boolean" + } + }, + "required": [ + "cert_directory","use_tls" + ], + "additionalProperties": false + }, + "databases": { + "description": "The databases the application is connecting to using the pgaas", + "type": "object", + "additionalProperties": { + "type": "string", + "enum": [ + "postgres" + ] + } + }, + "policy": { + "properties": { + "trigger_type": { + "description": "Only value of docker is supported at this time.", + "type": "string", + "enum": ["docker"] + }, + "script_path": { + "description": "Script command that will be executed for policy reconfiguration", + "type": "string" + } + }, + "required": [ + "trigger_type","script_path" + ], + "additionalProperties": false + }, + "volumes": { + "description": "Volume mapping to be used for Docker containers. Each entry is of the format below", + "type": "array", + "items": { + "type": "object", + "properties": { + "host":{ + "type":"object", + "path": {"type": "string"} + }, + "container":{ + "type":"object", + "bind": { "type": "string"}, + "mode": { "type": "string"} + } + } + } + } + }, + "required": [ + "healthcheck" + ], + "additionalProperties": false + }, + "docker_healthcheck_http": { + "properties": { + "type": { + "description": "Consul health check type", + "type": "string", + "enum": [ + "http", + "https" + ] + }, + "interval": { + "description": "Interval duration in seconds i.e. 10s", + "default": "15s", + "type": "string" + }, + "timeout": { + "description": "Timeout in seconds i.e. 10s", + "default": "1s", + "type": "string" + }, + "endpoint": { + "description": "Relative endpoint used by Consul to check health by making periodic HTTP GET calls", + "type": "string" + } + }, + "required": [ + "type", + "endpoint" + ] + }, + "docker_healthcheck_script": { + "properties": { + "type": { + "description": "Consul health check type", + "type": "string", + "enum": [ + "script", + "docker" + ] + }, + "interval": { + "description": "Interval duration in seconds i.e. 10s", + "default": "15s", + "type": "string" + }, + "timeout": { + "description": "Timeout in seconds i.e. 10s", + "default": "1s", + "type": "string" + }, + "script": { + "description": "Script command that will be executed by Consul to check health", + "type": "string" + } + }, + "required": [ + "type", + "script" + ] + } + } + } + diff --git a/docs/sections/design-components/component-specification/component-type-docker.rst b/docs/sections/design-components/component-specification/component-type-docker.rst new file mode 100755 index 00000000..70412c0f --- /dev/null +++ b/docs/sections/design-components/component-specification/component-type-docker.rst @@ -0,0 +1,1437 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+
+.. _component_specification:
+
+What is Component Specification?
+================================
+
+This page will discuss categories defined in :any:`component specification schema <dcae-component-schema>` and their usage.
+
+
+Meta Schema Definition
+----------------------
+
+
+The “Meta Schema” implementation defines how component specification
+JSON schemas can be written to define user input. It is itself a JSON
+schema (thus it is a “meta schema”). It requires the name of the
+component entry, component type (either ‘cdap’ or ‘docker’) and a
+description under “self” object. The meta schema version must be
+specified as the value of the “version” key. Then the input schema
+itself is described.
+
+There are four types of schema descriptions objects - jsonschema for
+inline standard JSON Schema definitions of JSON inputs, delimitedschema
+for delimited data input using a JSON description defined by AT&T,
+unstructured for unstructured text, and reference that allows a pointer
+to another artifact for a schema. The reference allows for XML and Protocol Buffer schema,
+but can be used as a pointer to JSON, Delimited Format, and Unstructured
+schemas as well.
+
+.. _metadata:
+
+Component Metadata
+------------------
+
+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.
+
+Example:
+
+::
+
+ "self": {
+ "version": "1.0.0",
+ "name": "yourapp.component.kpi_anomaly",
+ "description": "Classifies VNF KPI data as anomalous",
+ "component_type": "docker"
+ },
+
+``self`` Schema:
+
++-------------+--------+----------------+
+| Property | Type | Description |
+| Name | | |
++=============+========+================+
+| version | string | *Required*. |
+| | | Semantic |
+| | | version |
+| | | for this |
+| | | specification |
++-------------+--------+----------------+
+| name | string | *Required*. |
+| | | Full |
+| | | name of |
+| | | this |
+| | | component |
+| | | which is |
+| | | also |
+| | | used as |
+| | | this |
+| | | component's |
+| | | catalog |
+| | | id. |
++-------------+--------+----------------+
+| description | string | *Required* |
+| | | Human-readable |
+| | | text |
+| | | describing |
+| | | the |
+| | | component |
+| | | and the |
+| | | components |
+| | | functional |
+| | | purpose. |
++-------------+--------+----------------+
+| component_t\| string | *Required* |
+| ype | | Identify |
+| | | what |
+| | | containe\ |
+| | | rization |
+| | | technolo\ |
+| | | gy |
+| | | this |
+| | | componen\ |
+| | | t |
+| | | uses: |
+| | | *docker* |
+| | | or |
+| | | *cdap*. |
+| | | |
++-------------+--------+----------------+
+
+.. _interfaces:
+
+Interfaces
+----------
+
+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 :any:`data
+format <data-formats>`.
+
+Streams
+~~~~~~~
+
+- 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.
+- 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.
+- Streams have anonymous publish/subscribe semantics, which decouples
+ the production of information from its consumption. Like the component
+ specification, the data format specification is represented/validated against this
+ `Data Format json schema <https://gerrit.onap.org/r/gitweb?p=dcaegen2/platform/cli.git;a=blob;f=component-json-schemas/data-format/dcae-cli-v1/data-format-schema.json;h=be1568291300305c7adb9a8d244d39f9e6ddadbd;hb=HEAD>`__
+- In general, components are not aware of who they are communicating
+ with.
+- Instead, components that are interested in data, subscribe to the
+ relevant stream; components that generate data publish to the
+ relevant stream.
+- There can be multiple publishers and subscribers to a stream. Streams
+ are intended for unidirectional, streaming communication.
+
+Streams interfaces that implement an HTTP endpoint must support POST.
+
+Streams are split into:
+
++-------------+----+----------+
+| Property | Ty\| Descript\|
+| Name | pe | ion |
++=============+====+==========+
+| subscribes | JS\| *Require\|
+| | ON | d*. |
+| | li\| List of |
+| | st | all |
+| | | availabl\|
+| | | e |
+| | | stream |
+| | | interfac\|
+| | | es |
+| | | that |
+| | | this |
+| | | componen\|
+| | | t |
+| | | has that |
+| | | can be |
+| | | used for |
+| | | subscrib\|
+| | | ing |
++-------------+----+----------+
+| publishes | JS\| *Require\|
+| | ON | d*. |
+| | li\| List of |
+| | st | all |
+| | | stream |
+| | | interfac\|
+| | | es |
+| | | that |
+| | | this |
+| | | componen\|
+| | | t |
+| | | will |
+| | | publish |
+| | | onto |
++-------------+----+----------+
+
+Subscribes
+^^^^^^^^^^
+
+Example:
+
+.. code:: json
+
+ "streams": {
+ "subscribes": [{
+ "format": "dcae.vnf.kpi",
+ "version": "1.0.0",
+ "route": "/data", // for CDAP this value is not used
+ "type": "http"
+ }],
+ ...
+ }
+
+This describes that ``yourapp.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``.
+
+``subscribes`` Schema:
+
++-------------+----+--------------------+
+| Property | Ty\| Descript\ |
+| Name | pe | ion |
++=============+====+====================+
+| format | st\| *Require\ |
+| | ri\| d*. |
+| | ng | Data |
+| | | format |
+| | | id of |
+| | | the data |
+| | | format |
+| | | that is |
+| | | used by |
+| | | this |
+| | | interfac\ |
+| | | e |
++-------------+----+--------------------+
+| version | st\| *Require\ |
+| | ri\| d*. |
+| | ng | Data |
+| | | format |
+| | | version |
+| | | of the |
+| | | data |
+| | | format |
+| | | that is |
+| | | used by |
+| | | this |
+| | | interfac\ |
+| | | e |
++-------------+----+--------------------+
+| route | st\| *Require\ |
+| | ri\| d |
+| | ng | for HTTP |
+| | | and data |
+| | | router*. |
+| | | The HTTP |
+| | | route |
+| | | that |
+| | | this |
+| | | interfac\ |
+| | | e |
+| | | listens |
+| | | on |
++-------------+----+--------------------+
+| config_key | st\| *Require\ |
+| | ri\| d \ |
+| | ng | for \ |
+| | | message_router\ |
+| | | and data \ |
+| | | router*. |
+| | | The HTTP |
+| | | route |
+| | | that |
+| | | this |
+| | | interfac\ |
+| | | e |
+| | | listens |
+| | | on |
++-------------+----+--------------------+
+| type | st\| *Require\ |
+| | ri\| d*. |
+| | ng | Type of |
+| | | stream: |
+| | | ``http`` |
+| | | , |
+| | | ``message_router`` |
+| | | , |
+| | | ``data_router`` |
++-------------+----+--------------------+
+
+.. _message-router:
+
+Message router
+''''''''''''''
+
+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``:
+
+.. code:: json
+
+ "streams": {
+ "subscribes": [{
+ "format": "dcae.some-format",
+ "version": "1.0.0",
+ "config_key": "some_format_handle",
+ "type": "message router"
+ }],
+ ...
+ }
+
+
+.. _data-router:
+
+Data router
+'''''''''''
+
+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 :any:`DMaaP connection objects <dmaap-data-router>` for more details on
+the configuration information.
+
+Example (not tied to the larger example):
+
+.. code:: json
+
+ "streams": {
+ "subscribes": [{
+ "config_key": "some-sub-dr",
+ "format": "sandbox.platform.any",
+ "route": "/identity",
+ "type": "data_router",
+ "version": "0.1.0"
+ }],
+ ...
+ }
+
+Publishes
+^^^^^^^^^
+
+Example:
+
+.. code:: json
+
+ "streams": {
+ ...
+ "publishes": [{
+ "format": "yourapp.format.integerClassification",
+ "version": "1.0.0",
+ "config_key": "prediction",
+ "type": "http"
+ }]
+ },
+
+This describes that ``yourapp.component.kpi_anomaly`` publishes by making
+POST requests to streams that support the data format
+``yourapp.format.integerClassification`` version ``1.0.0``.
+
+``publishes`` Schema:
+
++-------------+----+--------------------+
+| Property | Ty\| Descript\ |
+| Name | pe | ion |
++=============+====+====================+
+| format | st\| *Require\ |
+| | ri\| d*. |
+| | ng | Data |
+| | | format |
+| | | id of |
+| | | the data |
+| | | format |
+| | | that is |
+| | | used by |
+| | | this |
+| | | interfac\ |
+| | | e |
++-------------+----+--------------------+
+| version | st\| *Require\ |
+| | ri\| d*. |
+| | ng | Data |
+| | | format |
+| | | version |
+| | | of the |
+| | | data |
+| | | format |
+| | | that is |
+| | | used by |
+| | | this |
+| | | interfac\ |
+| | | e |
++-------------+----+--------------------+
+| config_key | st\| *Require\ |
+| | ri\| d*. |
+| | ng | The JSON |
+| | | key in |
+| | | the |
+| | | generate\ |
+| | | d |
+| | | applicat |
+| | | ion |
+| | | configur\ |
+| | | ation |
+| | | that |
+| | | will be |
+| | | used to |
+| | | pass the |
+| | | downstre\ |
+| | | am |
+| | | componen\ |
+| | | t’s |
+| | | (the |
+| | | subscrib\ |
+| | | er’s) |
+| | | connecti\ |
+| | | on |
+| | | informat\ |
+| | | ion. |
++-------------+----+--------------------+
+| type | st\| *Require\ |
+| | ri\| d*. |
+| | ng | Type of |
+| | | stream: |
+| | | ``http`` |
+| | | , |
+| | | ``message_router`` |
+| | | , |
+| | | ``data_router`` |
++-------------+----+--------------------+
+
+.. message-router-1:
+
+Message router
+''''''''''''''
+
+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
+needs to receive e.g. topic url, username, password. See the page on
+:any:`DMaaP connection objects <dmaap-message-router>` for more details on
+the configuration information.
+
+Example (not tied to the larger example):
+
+.. code:: json
+
+ "streams": {
+ ...
+ "publishes": [{
+ "config_key": "some-pub-mr",
+ "format": "sandbox.platform.any",
+ "type": "message_router",
+ "version": "0.1.0"
+ }]
+ }
+
+.. data-router-1:
+
+Data router
+'''''''''''
+
+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 :any:`DMaaP connection objects <dmaap-data-router>` for more details on
+the configuration information.
+
+Example (not tied to the larger example):
+
+.. code:: json
+
+ "streams": {
+ ...
+ "publishes": [{
+ "config_key": "some-pub-dr",
+ "format": "sandbox.platform.any",
+ "type": "data_router",
+ "version": "0.1.0"
+ }]
+ }
+
+Quick Reference
+^^^^^^^^^^^^^^^
+
+Refer to this :doc:`Quick Reference <streams-grid>` for a
+comparison of the Streams ‘Publishes’ and ‘Subscribes’ sections.
+
+Services
+~~~~~~~~
+
+- The publish / subscribe model is a very flexible communication
+ paradigm, but its many-to-many one-way transport is not appropriate
+ for RPC request / reply interactions, which are often required in a
+ distributed system.
+- Request / reply is done via a Service, which is defined by a pair of
+ messages: one for the request and one for the reply.
+
+Services are split into:
+
++-------------+----+----------+
+| Property | Ty\| Descript\|
+| Name | pe | ion |
++=============+====+==========+
+| calls | JS\| *Require\|
+| | ON | d*. |
+| | li\| List of |
+| | st | all |
+| | | service |
+| | | interfac\|
+| | | es |
+| | | that |
+| | | this |
+| | | componen\|
+| | | t |
+| | | will |
+| | | call |
++-------------+----+----------+
+| provides | JS\| *Require\|
+| | ON | d*. |
+| | li\| List of |
+| | st | all |
+| | | service |
+| | | interfac\|
+| | | es |
+| | | that |
+| | | this |
+| | | componen\|
+| | | t |
+| | | exposes |
+| | | and |
+| | | provides |
++-------------+----+----------+
+
+Calls
+^^^^^
+
+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. 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``.
+
+Example:
+
+.. code:: json
+
+ "services": {
+ "calls": [{
+ "config_key": "vnf-db",
+ "request": {
+ "format": "dcae.vnf.meta",
+ "version": "1.0.0"
+ },
+ "response": {
+ "format": "dcae.vnf.kpi",
+ "version": "1.0.0"
+ }
+ }],
+ ...
+ }
+
+This describes that ``yourapp.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``.
+
+``calls`` Schema:
+
++-------------+----+----------+
+| Property | Ty\| Descript\|
+| Name | pe | ion |
++=============+====+==========+
+| request | JS\| *Require\|
+| | ON | d*. |
+| | ob\| Descript\|
+| | je\| ion |
+| | ct | of the |
+| | | expected |
+| | | request |
+| | | for this |
+| | | downstre\|
+| | | am |
+| | | interfac\|
+| | | e |
++-------------+----+----------+
+| response | JS\| *Require\|
+| | ON | d*. |
+| | ob\| Descript\|
+| | je\| ion |
+| | ct | of the |
+| | | expected |
+| | | response |
+| | | for this |
+| | | downstre\|
+| | | am |
+| | | interfac\|
+| | | e |
++-------------+----+----------+
+| config_key | st\| *Require\|
+| | ri\| d*. |
+| | ng | The JSON |
+| | | key in |
+| | | the |
+| | | generate\|
+| | | d |
+| | | applicat |
+| | | ion |
+| | | configur\|
+| | | ation |
+| | | that |
+| | | will be |
+| | | used to |
+| | | pass the |
+| | | downstre\|
+| | | am |
+| | | componen |
+| | | t |
+| | | connecti\|
+| | | on |
+| | | informat\|
+| | | ion. |
++-------------+----+----------+
+
+The JSON object schema for both ``request`` and ``response``:
+
++-------------+----+----------+
+| Property | Ty\| Descript\|
+| Name | pe | ion |
++=============+====+==========+
+| format | st\| *Require\|
+| | ri\| d*. |
+| | ng | Data |
+| | | format |
+| | | id of |
+| | | the data |
+| | | format |
+| | | that is |
+| | | used by |
+| | | this |
+| | | interfac\|
+| | | e |
++-------------+----+----------+
+| version | st\| *Require\|
+| | ri\| d*. |
+| | ng | Data |
+| | | format |
+| | | version |
+| | | of the |
+| | | data |
+| | | format |
+| | | that is |
+| | | used by |
+| | | this |
+| | | interfac\|
+| | | e |
++-------------+----+----------+
+
+Provides
+^^^^^^^^
+
+Example:
+
+.. code:: json
+
+ "services": {
+ ...
+ "provides": [{
+ "route": "/score-vnf",
+ "request": {
+ "format": "dcae.vnf.meta",
+ "version": "1.0.0"
+ },
+ "response": {
+ "format": "yourapp.format.integerClassification",
+ "version": "1.0.0"
+ }
+ }]
+ },
+
+This describes that ``yourapp.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
+``yourapp.format.integerClassification`` version ``1.0.0``.
+
+``provides`` Schema for a Docker component:
+
++-------------+----+----------+
+| Property | Ty\| Descript\|
+| Name | pe | ion |
++=============+====+==========+
+| request | JS\| *Require\|
+| | ON | d*. |
+| | ob\| Descript\|
+| | je\| ion |
+| | ct | of the |
+| | | expected |
+| | | request |
+| | | for this |
+| | | interfac\|
+| | | e |
++-------------+----+----------+
+| response | JS\| *Require\|
+| | ON | d*. |
+| | ob\| Descript\|
+| | je\| ion |
+| | ct | of the |
+| | | expected |
+| | | response |
+| | | for this |
+| | | interfac\|
+| | | e |
++-------------+----+----------+
+| route | st\| *Require\|
+| | ri\| d*. |
+| | ng | The HTTP |
+| | | route |
+| | | that |
+| | | this |
+| | | interfac\|
+| | | e |
+| | | listens |
+| | | on |
++-------------+----+----------+
+
+The JSON object schema for both ``request`` and ``response``:
+
++-------------+----+----------+
+| Property | Ty\| Descript\|
+| Name | pe | ion |
++=============+====+==========+
+| format | st\| *Require\|
+| | ri\| d*. |
+| | ng | Data |
+| | | format |
+| | | id of |
+| | | the data |
+| | | format |
+| | | that is |
+| | | used by |
+| | | this |
+| | | interfac\|
+| | | e |
++-------------+----+----------+
+| version | st\| *Require\|
+| | ri\| d*. |
+| | ng | Data |
+| | | format |
+| | | version |
+| | | of the |
+| | | data |
+| | | format |
+| | | that is |
+| | | used by |
+| | | this |
+| | | interfac\|
+| | | e |
++-------------+----+----------+
+
+Note, for CDAP, there is a slight variation due to the way CDAP exposes
+services:
+
+::
+
+ "provides":[ // note this is a list of JSON
+ {
+ "request":{ ...},
+ "response":{ ...},
+ "service_name":"name CDAP service",
+ "service_endpoint":"greet", // E.g the URL is /services/service_name/methods/service_endpoint
+ "verb":"GET" // GET, PUT, or POST
+ }
+ ]
+
+``provides`` Schema for a CDAP component:
+
++-------------+----+-----------+
+| Property | Ty\| Descript\ |
+| Name | pe | ion |
++=============+====+===========+
+| request | JS\| *Require\ |
+| | ON | d*. |
+| | ob\| Descript\ |
+| | je\| ion |
+| | ct | of the |
+| | | expected |
+| | | request |
+| | | data |
+| | | format |
+| | | for this |
+| | | interfac\ |
+| | | e |
++-------------+----+-----------+
+| response | JS\| *Require\ |
+| | ON | d*. |
+| | ob\| Descript\ |
+| | je\| ion |
+| | ct | of the |
+| | | expected |
+| | | response |
+| | | for this |
+| | | interfac\ |
+| | | e |
++-------------+----+-----------+
+| service_nam\| st\| *Require\ |
+| e | ri\| d*. |
+| | ng | The CDAP |
+| | | service |
+| | | name (eg |
+| | | “Greetin\ |
+| | | g”) |
++-------------+----+-----------+
+| service_end | st\| *Require\ |
+| point | ri\| d*. |
+| | ng | The CDAP |
+| | | service |
+| | | endpoint |
+| | | for this |
+| | | service_n\|
+| | | ame |
+| | | (eg |
+| | | “/greet” |
+| | | ) |
++-------------+----+-----------+
+| verb | st\| *Require\ |
+| | ri\| d*. |
+| | ng | ‘GET’, |
+| | | ‘PUT’ or |
+| | | ‘POST’ |
++-------------+----+-----------+
+
+.. _common-specification-parameters:
+
+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 | Ty\| Descript\| Defa\|
+| Name | pe | ion | ult |
++==============+====+==========+======+
+| name | st\| *Require\| |
+| | ri\| d*. | |
+| | ng | The | |
+| | | property | |
+| | | name | |
+| | | that | |
+| | | will be | |
+| | | used as | |
+| | | the key | |
+| | | in the | |
+| | | generate\| |
+| | | d | |
+| | | config | |
++--------------+----+----------+------+
+| value | an\| *Require\| |
+| | y | d*. | |
+| | | The | |
+| | | default | |
+| | | value | |
+| | | for the | |
+| | | given | |
+| | | paramete\| |
+| | | r | |
++--------------+----+----------+------+
+| description | st\| *Require\| |
+| | ri\| d*. | |
+| | ng | Human-re\| |
+| | | adable | |
+| | | text | |
+| | | describi\| |
+| | | ng | |
+| | | the | |
+| | | paramete\| |
+| | | r | |
+| | | like | |
+| | | what its | |
+| | | for | |
++--------------+----+----------+------+
+| type | st\| The | |
+| | ri\| required | |
+| | ng | data | |
+| | | type for | |
+| | | the | |
+| | | paramete\| |
+| | | r | |
++--------------+----+----------+------+
+| required | bo\| An | true |
+| | ol\| optional | |
+| | ea\| key that | |
+| | n | declares | |
+| | | a | |
+| | | paramete\| |
+| | | r | |
+| | | as | |
+| | | required | |
+| | | (true) | |
+| | | or not | |
+| | | (false) | |
++--------------+----+----------+------+
+| constraints | ar\| The | |
+| | ra\| optional | |
+| | y | list of | |
+| | | sequence | |
+| | | d | |
+| | | constrai\| |
+| | | nt | |
+| | | clauses | |
+| | | for the | |
+| | | paramete\| |
+| | | r. | |
+| | | See | |
+| | | below | |
++--------------+----+----------+------+
+| entry_schem\ | st\| The | |
+| a | ri\| optional | |
+| | ng | key that | |
+| | | is used | |
+| | | to | |
+| | | declare | |
+| | | the name | |
+| | | of the | |
+| | | Datatype | |
+| | | definiti\| |
+| | | on | |
+| | | for | |
+| | | entries | |
+| | | of set | |
+| | | types | |
+| | | such as | |
+| | | the | |
+| | | TOSCA | |
+| | | ‘list’ | |
+| | | or | |
+| | | ‘map’. | |
+| | | Only 1 | |
+| | | level is | |
+| | | supporte\| |
+| | | d | |
+| | | at this | |
+| | | time | |
++--------------+----+----------+------+
+| designer_ed\ | bo\| An | |
+| itable | ol\| optional | |
+| | ea\| key that | |
+| | n | declares | |
+| | | a | |
+| | | paramete\| |
+| | | r | |
+| | | to be | |
+| | | editable | |
+| | | by | |
+| | | designer | |
+| | | (true) | |
+| | | or not | |
+| | | (false) | |
++--------------+----+----------+------+
+| sourced_at_d\| bo\| An | |
+| eployment | ol\| optional | |
+| | ea\| key that | |
+| | n | declares | |
+| | | a | |
+| | | paramete\| |
+| | | r’s | |
+| | | value to | |
+| | | be | |
+| | | assigned | |
+| | | at | |
+| | | deployme\| |
+| | | nt | |
+| | | time | |
+| | | (true) | |
++--------------+----+----------+------+
+| policy_edit\ | bo\| An | |
+| able | ol\| optional | |
+| | ea\| key that | |
+| | n | declares | |
+| | | a | |
+| | | paramete\| |
+| | | r | |
+| | | to be | |
+| | | editable | |
+| | | by | |
+| | | policy | |
+| | | (true) | |
+| | | or not | |
+| | | (false) | |
++--------------+----+----------+------+
+| policy_sche\ | ar\| The | |
+| ma | ra\| optional | |
+| | y | list of | |
+| | | schema | |
+| | | definiti\| |
+| | | ons | |
+| | | used for | |
+| | | policy. | |
+| | | See | |
+| | | below | |
++--------------+----+----------+------+
+
+Example:
+
+.. code:: json
+
+ "parameters": [
+ {
+ "name": "threshold",
+ "value": 0.75,
+ "description": "Probability threshold to exceed to be anomalous"
+ }
+ ]
+
+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 | Ty\| Descript\|
+| Name | pe | ion |
++==============+====+==========+
+| equal | | Constrai\|
+| | | ns |
+| | | a |
+| | | property |
+| | | or |
+| | | paramete\|
+| | | r |
+| | | to a |
+| | | value |
+| | | equal to |
+| | | (‘=’) |
+| | | the |
+| | | value |
+| | | declared |
++--------------+----+----------+
+| greater_tha\ | nu\| Constrai\|
+| n | mb\| ns |
+| | er | a |
+| | | property |
+| | | or |
+| | | paramete |
+| | | r |
+| | | to a |
+| | | value |
+| | | greater |
+| | | than |
+| | | (‘>’) |
+| | | the |
+| | | value |
+| | | declared |
++--------------+----+----------+
+| greater_or_e\| nu\| Constrai\|
+| qual | mb\| ns |
+| | er | a |
+| | | property |
+| | | or |
+| | | paramete\|
+| | | r |
+| | | to a |
+| | | value |
+| | | greater |
+| | | than or |
+| | | equal to |
+| | | (‘>=’) |
+| | | the |
+| | | value |
+| | | declared |
++--------------+----+----------+
+| less_than | nu\| Constrai\|
+| | mb\| ns |
+| | er | a |
+| | | property |
+| | | or |
+| | | paramete\|
+| | | r |
+| | | to a |
+| | | value |
+| | | less |
+| | | than |
+| | | (‘<’) |
+| | | the |
+| | | value |
+| | | declared |
++--------------+----+----------+
+| less_or_equ\ | nu\| Constrai\|
+| al | mb\| ns |
+| | er | a |
+| | | property |
+| | | or |
+| | | paramete\|
+| | | r |
+| | | to a |
+| | | value |
+| | | less |
+| | | than or |
+| | | equal to |
+| | | (‘<=’) |
+| | | the |
+| | | value |
+| | | declared |
++--------------+----+----------+
+| valid_value\ | ar\| Constrai\|
+| s | ra\| ns |
+| | y | a |
+| | | property |
+| | | or |
+| | | paramete\|
+| | | r |
+| | | to a |
+| | | value |
+| | | that is |
+| | | in the |
+| | | list of |
+| | | declared |
+| | | values |
++--------------+----+----------+
+| length | nu\| Constrai\|
+| | mb\| ns |
+| | er | the |
+| | | property |
+| | | or |
+| | | paramete\|
+| | | r |
+| | | to a |
+| | | value of |
+| | | a given |
+| | | length |
++--------------+----+----------+
+| min_length | nu\| Constrai\|
+| | mb\| ns |
+| | er | the |
+| | | property |
+| | | or |
+| | | paramete\|
+| | | r |
+| | | to a |
+| | | value to |
+| | | a |
+| | | minimum |
+| | | length |
++--------------+----+----------+
+| max_length | nu\| Constrai\|
+| | mb\| ns |
+| | er | the |
+| | | property |
+| | | or |
+| | | paramete\|
+| | | r |
+| | | to a |
+| | | value to |
+| | | a |
+| | | maximum |
+| | | length |
++--------------+----+----------+
+
+``threshold`` is the configuration parameter and will get set to 0.75
+when the configuration gets generated.
+
+The property ``policy_schema`` is a list of objects where each
+policy_schema object:
+
++-------------+----+----------+------+
+| Property | Ty\| Descript\| Defa\|
+| Name | pe | ion | ult |
++=============+====+==========+======+
+| name | st\| *Require\| |
+| | ri\| d*. | |
+| | ng | paramete\| |
+| | | r | |
+| | | name | |
++-------------+----+----------+------+
+| value | st\| default | |
+| | ri\| value | |
+| | ng | for the | |
+| | | paramete\| |
+| | | r | |
++-------------+----+----------+------+
+| description | st\| paramete\| |
+| | ri\| r | |
+| | ng | descript\| |
+| | | ion | |
++-------------+----+----------+------+
+| type | en\| *Require\| |
+| | um | d*. | |
+| | | data | |
+| | | type of | |
+| | | the | |
+| | | paramete\| |
+| | | r, | |
+| | | ‘string’ | |
+| | | , | |
+| | | ‘number’ | |
+| | | , | |
+| | | ‘boolean | |
+| | | ’, | |
+| | | ‘datetim\| |
+| | | e’, | |
+| | | ‘list’, | |
+| | | or ‘map’ | |
++-------------+----+----------+------+
+| required | bo\| is | true |
+| | ol\| paramete\| |
+| | ea\| r | |
+| | n | required | |
+| | | or not? | |
++-------------+----+----------+------+
+| constraints | ar\| The | |
+| | ra\| optional | |
+| | y | list of | |
+| | | sequence\| |
+| | | d | |
+| | | constrai\| |
+| | | nt | |
+| | | clauses | |
+| | | for the | |
+| | | paramete\| |
+| | | r. | |
+| | | See | |
+| | | above | |
++-------------+----+----------+------+
+| entry_schem\| st\| The | |
+| a | ri\| optional | |
+| | ng | key that | |
+| | | is used | |
+| | | to | |
+| | | declare | |
+| | | the name | |
+| | | of the | |
+| | | Datatype | |
+| | | definiti\| |
+| | | on | |
+| | | for | |
+| | | certain | |
+| | | types. | |
+| | | entry_sc\| |
+| | | hema | |
+| | | 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 | |
++-------------+----+----------+------+
+| | If | | |
+| | th\| | |
+| | e | | |
+| | ty\| | |
+| | pe | | |
+| | is | | |
+| | li\| | |
+| | st | | |
+| | an\| | |
+| | d | | |
+| | th\| | |
+| | e | | |
+| | en\| | |
+| | tr\| | |
+| | y | | |
+| | ty\| | |
+| | pe | | |
+| | is | | |
+| | a | | |
+| | ma\| | |
+| | p, | | |
+| | fo\| | |
+| | ll\| | |
+| | ow | | |
+| | wi\| | |
+| | th | | |
+| | an | | |
+| | ar\| | |
+| | ra\| | |
+| | y | | |
+| | to | | |
+| | de\| | |
+| | sc\| | |
+| | ri\| | |
+| | be | | |
+| | th\| | |
+| | e | | |
+| | ke\| | |
+| | ys | | |
+| | fo\| | |
+| | r | | |
+| | th\| | |
+| | e | | |
+| | en\| | |
+| | tr\| | |
+| | y | | |
+| | ma\| | |
+| | p | | |
++-------------+----+----------+------+
+| | If | | |
+| | th\| | |
+| | e | | |
+| | ty\| | |
+| | pe | | |
+| | is | | |
+| | li\| | |
+| | st | | |
+| | an\| | |
+| | d | | |
+| | th\| | |
+| | e | | |
+| | en\| | |
+| | tr\| | |
+| | y | | |
+| | ty\| | |
+| | pe | | |
+| | is | | |
+| | a | | |
+| | li\| | |
+| | st | | |
+| | , | | |
+| | th\| | |
+| | at | | |
+| | is | | |
+| | no\| | |
+| | t | | |
+| | cu\| | |
+| | rr\| | |
+| | en\| | |
+| | tl\| | |
+| | y | | |
+| | su\| | |
+| | pp\| | |
+| | or\| | |
+| | te\| | |
+| | d \| | |
++-------------+----+----------+------+
+| | If | | |
+| | th\| | |
+| | e | | |
+| | ty\| | |
+| | pe | | |
+| | is | | |
+| | ma\| | |
+| | p, | | |
+| | fo\| | |
+| | ll\| | |
+| | ow | | |
+| | wi\| | |
+| | th | | |
+| | an | | |
+| | ar\| | |
+| | ay | | |
+| | to | | |
+| | de\| | |
+| | sc\| | |
+| | ri\| | |
+| | be | | |
+| | th\| | |
+| | e | | |
+| | ke\| | |
+| | ys | | |
+| | fo\| | |
+| | r | | |
+| | th\| | |
+| | e | | |
+| | ma\| | |
+| | p | | |
++-------------+----+----------+------+
+
+
+.. _artifacts:
+
+Artifacts
+---------
+
+``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.
+
++---------------+------------+---------------------------------+
+| Property Name | Type | Description |
++===============+============+=================================+
+| artifacts | JSON array | Each entry is a artifact object |
++---------------+------------+---------------------------------+
+
+``artifact`` Schema:
+
++---------------+--------+--------------------------------------------+
+| Property Name | Type | Description |
++===============+========+============================================+
+| uri | string | *Required*. Uri to the artifact, full path |
++---------------+--------+--------------------------------------------+
+| type | string | *Required*. ``docker image`` or ``jar`` |
++---------------+--------+--------------------------------------------+
+
+.. _auxilary:
+
+Auxilary
+--------
+
+
+Health check
+~~~~~~~~~~~~
+
+Component developers are required to provide a way for the platform to
+periodically check the health of their running components. The
+details of the definition used by your component is to be provided
+through the :any:`Docker auxiliary specification <docker-auxiliary-details>`.
+
+
diff --git a/docs/sections/design-components/component-specification/configuration-grid.rst b/docs/sections/design-components/component-specification/configuration-grid.rst new file mode 100755 index 00000000..3efb9850 --- /dev/null +++ b/docs/sections/design-components/component-specification/configuration-grid.rst @@ -0,0 +1,118 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Configuration Quick Reference
+=============================
+
+Default Values
+^^^^^^^^^^^^^^
+
+The component developer can provide default values for any ``parameter``
+in the component specification. These defaults will be passed to the
+component in its generated configuration.
+
+Overridden/Entered Values
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Depending on the other properties set for the parameter, the default
+value can be overridden at ‘design-time’, ‘deploy-time’ or once the
+microservice is running (‘run-time’).
+
++--------+--------+--------+--------+------------+
+| | Design\| CLAMP | Policy | Deploy-Time|
+| | -Time | Input | Input | Input |
+| | Input | | | |
+| | | | | |
++========+========+========+========+============+
+| Descri\| Applie\| Applie\| (not | Applies to |
+| ption | s | s | yet | manually |
+| | to | to | suppor\| deployed |
+| | self-s\| compon\| ted) | services |
+| | ervice | ents | | |
+| | compon\| deploy\| | |
+| | ents | ed | | |
+| | | by | | |
+| | | CLAMP | | |
++--------+--------+--------+--------+------------+
+| Input | Servic\| CLAMP | Operat\| DevOps |
+| provid\| e | | ions | |
+| ed | Designe| | | |
+| by | r | | | |
++--------+--------+--------+--------+------------+
+| How it | In the | In the | In the | In the DCAE|
+| is | SDC/MOD| CLAMP | POLICY | Dashboard |
+| provid\| UI | UI | GUI | (or Jenkins|
+| ed | | | | job) |
++--------+--------+--------+--------+------------+
+| Compon\| ‘desig\| None. | ‘polic\| ‘sourced\ |
+| ent | ner-ed\| Develo\| y_edit\| _at_deploy\|
+| Specif\| itable\| per | able’ | ment’ must |
+| icatio\| ’ | provid\| must | be set to |
+| n | set to | es | be set | ‘true’ |
+| Detail\| ‘true’ | CLAMP | to | |
+| s | | an | ‘true’ | |
+| | | email | and | |
+| | | with | ‘polic\| |
+| | | parame\| y_sche\| |
+| | | ters | ma’ | |
+| | | to be | must | |
+| | | suppor\| be | |
+| | | ted | provid\| |
+| | | | ed | |
+| | | | | |
+| | | | | |
++--------+--------+--------+--------+------------+
+| Additi\| | | For | |
+| onal | | | Docker | |
+| Info | | | only: | |
+| for | | | In the | |
+| Compon\| | | auxili\| |
+| ent | | | ary | |
+| Develo\| | | sectio\| |
+| per | | | n: | |
+| | | | {“poli\| |
+| | | | cy”: | |
+| | | | {“trig\| |
+| | | | ger_ty\| |
+| | | | pe”: | |
+| | | | “polic\| |
+| | | | y”,“sc\| |
+| | | | ript_p\| |
+| | | | ath”: | |
+| | | | “/opt/\| |
+| | | | app/re\| |
+| | | | config\| |
+| | | | ure.sh | |
+| | | | ”} | |
+| | | | } | |
+| | | | Script | |
+| | | | interf\| |
+| | | | ace | |
+| | | | would | |
+| | | | then | |
+| | | | be | |
+| | | | “/opt/\| |
+| | | | app/re\| |
+| | | | config\| |
+| | | | ure.sh | |
+| | | | ” | |
+| | | | $trigg\| |
+| | | | er_typ\| |
+| | | | e | |
+| | | | $updat\| |
+| | | | ed_pol\| |
+| | | | icy" | |
+| | | | where | |
+| | | | $updat\| |
+| | | | ed_pol\| |
+| | | | icy | |
+| | | | is | |
+| | | | json | |
+| | | | provid\| |
+| | | | ed | |
+| | | | by the | |
+| | | | Policy | |
+| | | | Handle\| |
+| | | | r. | |
++--------+--------+--------+--------+------------+
+
diff --git a/docs/sections/design-components/component-specification/data-formats.rst b/docs/sections/design-components/component-specification/data-formats.rst new file mode 100755 index 00000000..42194fa3 --- /dev/null +++ b/docs/sections/design-components/component-specification/data-formats.rst @@ -0,0 +1,235 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _data-formats:
+
+
+Data Formats
+============
+
+Data formats are descriptions of data; they are the data contract
+between your component and other components. When the components are
+‘composed’ into services in the Design tool, they can only be matched with
+components that have compatible data formats. Data formats will be
+onboarded to Design tool and assigned a UUID at that time. This UUID is then
+used to ensure compatibility amoung components. (If component X outputs
+data format ‘DF-Y’, and another component Z specifies ‘DF-Y’ as its
+input data format, then X is said to be ``composable`` with component
+Z).
+
+Since data formats will be shared across components, the onboarding
+catalog should be checked first to see if the desired data format is
+available before creating one. The vision is to have a repository of
+shared data formats that developers and teams can re-use and also
+provide them the means to extend and create new custom data formats. A
+data format is referenced by its data format id and version number.
+
+JSON schema
+-----------
+
+ The data format specification is represented (and validated) against
+ this `Data Format json schema <https://git.onap.org/dcaegen2/platform/plain/mod/component-json-schemas/data-format/dcae-cli-v1/data-format-schema.json>`__
+ and described below:
+
+Meta Schema Definition
+~~~~~~~~~~~~~~~~~~~~~~
+
+The “Meta Schema” implementation defines how data format JSON schemas
+can be written to define user input. It is itself a JSON schema (thus it
+is a “meta schema”). It requires the name of the data format entry, the
+data format entry version and allows a description under “self” object.
+The meta schema version must be specified as the value of the
+“dataformatversion” key. Then the input schema itself is described as
+one of the four types listed below:
+
++------------------+---------------------------------------------------+
+| Type | Description |
++==================+===================================================+
+| jsonschema | inline standard JSON Schema definitions of JSON |
+| | inputs |
++------------------+---------------------------------------------------+
+| delimitedschema | delimited data input using a JSON description and |
+| | defined delimiter |
++------------------+---------------------------------------------------+
+| unstructured | unstructured text, and reference that allows a |
+| | pointer to another artifact for a schema. |
++------------------+---------------------------------------------------+
+| reference | allows for XML and Protocol Buffers schema, |
+| | but can be used to reference other JSON, |
+| | delimitedschema and unstructured schemas as well. |
++------------------+---------------------------------------------------+
+
+
+Example Schemas
+---------------
+
+By reference example - Common Event Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+First the full JSON schema description of the Common Event Format would
+be loaded with a name of “Common Event Format” and the current version
+of “25.0.0”.
+
+Then the data format description is loaded by this schema:
+
+::
+
+ {
+ "self": {
+ "name": "Common Event Format Definition",
+ "version": "25.0.0",
+ "description": "Common Event Format Definition"
+
+ },
+ "dataformatversion": "1.0.0",
+ "reference": {
+ "name": "Common Event Format",
+ "format": "JSON",
+ "version": "25.0.0"
+ }
+ }
+
+
+
+Simple JSON Example
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+::
+
+ {
+ "self": {
+ "name": "Simple JSON Example",
+ "version": "1.0.0",
+ "description": "An example of unnested JSON schema for Input and output"
+
+ },
+ "dataformatversion": "1.0.0",
+ "jsonschema": {
+ "$schema": "http://json-schema.org/draft-04/schema#",
+ "type": "object",
+ "properties": {
+ "raw-text": {
+ "type": "string"
+ }
+ },
+ "required": ["raw-text"],
+ "additionalProperties": false
+ }
+ }
+
+Nested JSON Example
+~~~~~~~~~~~~~~~~~~~
+
+::
+
+ {
+ "self": {
+ "name": "Nested JSON Example",
+ "version": "1.0.0",
+ "description": "An example of nested JSON schema for Input and output"
+
+ },
+ "dataformatversion": "1.0.0",
+ "jsonschema": {
+ "$schema": "http://json-schema.org/draft-04/schema#",
+ "properties": {
+ "numFound": {
+ "type": "integer"
+ },
+ "start": {
+ "type": "integer"
+ },
+ "engagements": {
+ "type": "array",
+ "items": {
+ "properties": {
+ "engagementID": {
+ "type": "string",
+ "transcript": {
+ "type": "array",
+ "items": {
+ "type": {
+ "type": "string"
+ },
+ "content": {
+ "type": "string"
+ },
+ "senderName": {
+ "type": "string"
+ },
+ "iso": {
+ "type": "string"
+ },
+ "timestamp": {
+ "type": "integer"
+ },
+ "senderId": {
+ "type": "string"
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "additionalProperties": false
+ }
+ }
+
+Unstructured Example
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ {
+ "self": {
+ "name": "Unstructured Text Example",
+ "version": "25.0.0",
+ "description": "An example of a unstructured text used for both input and output for "
+
+ },
+ "dataformatversion": "1.0.0",
+ "unstructured": {
+ "encoding": "UTF-8"
+ }
+ }
+
+
+An example of a delimited schema
+--------------------------------
+
+::
+
+ {
+ "self": {
+ "name": "Delimited Format Example",
+ "version": "1.0.0",
+ "description": "Delimited format example just for testing"
+
+ },
+ "dataformatversion": "1.0.0",
+ "delimitedschema": {
+ "delimiter": "|",
+ "fields": [{
+ "name": "field1",
+ "description": "test field1",
+ "fieldtype": "string"
+ }, {
+ "name": "field2",
+ "description": "test field2",
+ "fieldtype": "boolean"
+ }]
+ }
+ }
+
+Note: The referenced data format (in this case, a schema named “Common
+Event Format” with version of “25.0.0”) must already exist in the
+onboarding catalog.
+
+Working with Data Formats
+-------------------------
+
+Data Formats can be validated using `schema <https://git.onap.org/dcaegen2/platform/plain/mod/component-json-schemas/data-format/dcae-cli-v1/data-format-schema.json>`__
+Once validated, the dataformat can be onboarded using :doc:`DCAE-MOD <../DCAE-MOD/DCAE-MOD-User-Guide>`
\ No newline at end of file diff --git a/docs/sections/design-components/component-specification/dmaap-connection-objects.rst b/docs/sections/design-components/component-specification/dmaap-connection-objects.rst new file mode 100755 index 00000000..da368abf --- /dev/null +++ b/docs/sections/design-components/component-specification/dmaap-connection-objects.rst @@ -0,0 +1,218 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _dmaap-connection-objects:
+
+DMaaP connection objects
+========================
+
+DMaaP Connection objects are generated by the DCAE Platform at runtime
+and passed to the component in its application_configuration
+
+.. _dmaap-message-router:
+
+Message Router
+--------------
+
+Publishers and subscribers have the same generated
+``Dmaap Connection Object`` structure. Here’s an example for any given
+config-key: (This is what will be in application_configuration)
+
+.. code:: json
+
+ {
+ "type": "message_router",
+ "aaf_username": "some-user",
+ "aaf_password": "some-password",
+ "dmaap_info": {
+ "client_role": "com.dcae.member",
+ "client_id": "1500462518108",
+ "location": "mtc00",
+ "topic_url": "https://we-are-message-router.us:3905/events/some-topic"
+ }
+ }
+
+At the top-level:
+
++--------------------------------+---------+---------------------------+
+| Property Name | Type | Description |
++================================+=========+===========================+
+| type | string | *Required as input*. Must |
+| | | be ``message_router`` for |
+| | | message router topics |
++--------------------------------+---------+---------------------------+
+| aaf_username | string | AAF username message |
+| | | router clients use to |
+| | | authenticate with secure |
+| | | topics |
++--------------------------------+---------+---------------------------+
+| aaf_password | string | AAF password message |
+| | | router clients use to |
+| | | authenticate with secure |
+| | | topics |
++--------------------------------+---------+---------------------------+
+| dmaap_info | JSON | *Required as input*. |
+| | object | Contains the topic |
+| | | connection details |
++--------------------------------+---------+---------------------------+
+
+The ``dmaap_info`` object contains:
+
++--------------------------------+---------+---------------------------+
+| Property Name | Type | Description |
++================================+=========+===========================+
+| client_role | string | AAF client role that’s |
+| | | requesting publish or |
+| | | subscribe access to the |
+| | | topic |
++--------------------------------+---------+---------------------------+
+| client_id | string | Client id for given AAF |
+| | | client |
++--------------------------------+---------+---------------------------+
+| location | string | DCAE location for the |
+| | | publisher or subscriber, |
+| | | used to set up routing |
++--------------------------------+---------+---------------------------+
+| topic_url | string | *Required as input*. URL |
+| | | for accessing the topic |
+| | | to publish or receive |
+| | | events |
++--------------------------------+---------+---------------------------+
+
+
+
+.. _dmaap-data-router:
+
+Data Router
+-----------
+
+Publisher
+~~~~~~~~~
+
+Here’s an example of what the generated ``Dmaap Connection Object`` for
+Data Router Publisher looks like: (This is what will be in
+application_configuration)
+
+.. code:: json
+
+ {
+ "type": "data_router",
+ "dmaap_info": {
+ "location": "mtc00",
+ "publish_url": "https://we-are-data-router.us/feed/xyz",
+ "log_url": "https://we-are-data-router.us/feed/xyz/logs",
+ "username": "some-user",
+ "password": "some-password",
+ "publisher_id": "123456"
+ }
+ }
+
+At the top-level:
+
++--------------------------------+---------+---------------------------+
+| Property Name | Type | Description |
++================================+=========+===========================+
+| type | string | *Required as input*. Must |
+| | | be ``data_router`` for |
+| | | data router feeds |
++--------------------------------+---------+---------------------------+
+| dmaap_info | JSON | *Required as input*. |
+| | object | Contains the feed |
+| | | connection details |
++--------------------------------+---------+---------------------------+
+
+The ``dmaap_info`` object contains:
+
++--------------------------------+---------+---------------------------+
+| Property Name | Type | Description |
++================================+=========+===========================+
+| location | string | DCAE location for the |
+| | | publisher, used to set up |
+| | | routing |
++--------------------------------+---------+---------------------------+
+| publish_url | string | *Required as input*. URL |
+| | | to which the publisher |
+| | | makes Data Router publish |
+| | | requests |
++--------------------------------+---------+---------------------------+
+| log_url | string | URL from which log data |
+| | | for the feed can be |
+| | | obtained |
++--------------------------------+---------+---------------------------+
+| username | string | Username the publisher |
+| | | uses to authenticate to |
+| | | Data Router |
++--------------------------------+---------+---------------------------+
+| password | string | Password the publisher |
+| | | uses to authenticate to |
+| | | Data Router |
++--------------------------------+---------+---------------------------+
+| publisher_id | string | Publisher id in Data |
+| | | Router |
++--------------------------------+---------+---------------------------+
+
+
+Subscriber
+~~~~~~~~~~
+
+Here’s an example of what the generated ``Dmaap Connection Object`` for
+a Data Router Subscriber looks like: (This is what will be passed in
+application_configuration)
+
+.. code:: json
+
+ {
+ "type": "data_router",
+ "dmaap_info": {
+ "location": "mtc00",
+ "delivery_url": "https://my-subscriber-app.dcae:8080/target-path",
+ "username": "some-user",
+ "password": "some-password",
+ "subscriber_id": "789012"
+ }
+ }
+
+At the top-level:
+
++--------------------------------+---------+---------------------------+
+| Property Name | Type | Description |
++================================+=========+===========================+
+| type | string | *Required as input*. Must |
+| | | be ``data_router`` for |
+| | | data router feeds |
++--------------------------------+---------+---------------------------+
+| dmaap_info | JSON | *Required as input*. |
+| | object | Contains the feed |
+| | | connection details |
++--------------------------------+---------+---------------------------+
+
+The ``dmaap_info`` object contains:
+
++--------------------------------+---------+---------------------------+
+| Property Name | Type | Description |
++================================+=========+===========================+
+| location | string | DCAE location for the |
+| | | subscriber, used to set |
+| | | up routing |
++--------------------------------+---------+---------------------------+
+| delivery_url | string | URL to which the Data |
+| | | Router should deliver |
+| | | files |
++--------------------------------+---------+---------------------------+
+| username | string | Username Data Router uses |
+| | | to authenticate to the |
+| | | subscriber when |
+| | | delivering files |
++--------------------------------+---------+---------------------------+
+| password | string | Password Data Router uses |
+| | | to authenticate to the |
+| | | subscriber when |
+| | | delivering files |
++--------------------------------+---------+---------------------------+
+| subscriber_id | string | Subscriber id in Data |
+| | | Router |
++--------------------------------+---------+---------------------------+
+
+
+
+
diff --git a/docs/sections/design-components/component-specification/docker-specification.rst b/docs/sections/design-components/component-specification/docker-specification.rst new file mode 100755 index 00000000..6dd4f927 --- /dev/null +++ b/docs/sections/design-components/component-specification/docker-specification.rst @@ -0,0 +1,347 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _docker-requirements:
+
+Component Spec Requirements
+===========================
+
+The component specification contains the following groups of
+information.
+
+- :any:`Metadata <metadata>`
+- :any:`Interfaces <interfaces>` including the
+ associated :any:`Data Formats <data-formats>`
+- :any:`Parameters <common-specification-parameters>`
+- :any:`Auxiliary Details <docker-auxiliary-details>`
+- :any:`List of Artifacts <artifacts>`
+
+.. _docker-auxiliary-details:
+
+Auxiliary Details
+-----------------
+
+``auxiliary`` contains Docker specific details like health check, port
+mapping, volume mapping and policy reconfiguration script details.
+
+
++--------------------------------+---------+---------------------------+
+| Name | Type | Description |
++================================+=========+===========================+
+| healthcheck | JSON | *Required*. Health check |
+| | object | definition details |
++--------------------------------+---------+---------------------------+
+| ports | JSON | each array item maps a |
+| | array | container port to the |
+| | | host port. See example |
+| | | below. |
++--------------------------------+---------+---------------------------+
+| volume | JSON | each array item contains |
+| | array | a host and container |
+| | | object. See example |
+| | | below. |
++--------------------------------+---------+---------------------------+
+| policy | JSON | *Required*. Policy |
+| | array | reconfiguration script |
+| | | details |
++--------------------------------+---------+---------------------------+
+
+Health Check Definition
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The platform currently supports http and docker script based health checks.
+
+When choosing a value for interval, consider that too frequent
+healthchecks will put unnecessary load on the platform. If there is a
+problematic resource, then more frequent healthchecks are warranted (eg
+15s or 60s), but as stability increases, so can these values, (eg
+300s).
+
+When choosing a value for timeout, consider that too small a number will
+result in increasing timeout failures, and too large a number will
+result in a delay in the notification of the resource problem. A
+suggestion is to start with 5s and work from there.
+
+http
+^^^^
+
++--------------------------------+---------+---------------------------+
+| Property Name | Type | Description |
++================================+=========+===========================+
+| type | string | *Required*. ``http`` |
++--------------------------------+---------+---------------------------+
+| interval | string | Interval duration in |
+| | | seconds i.e. ``60s`` |
++--------------------------------+---------+---------------------------+
+| timeout | string | Timeout in seconds i.e. |
+| | | ``5s`` |
++--------------------------------+---------+---------------------------+
+| endpoint | string | *Required*. GET endpoint |
+| | | provided by the component |
+| | | for checking health |
++--------------------------------+---------+---------------------------+
+
+Example:
+
+.. code:: json
+
+ "auxilary": {
+ "healthcheck": {
+ "type": "http",
+ "interval": "15s",
+ "timeout": "1s",
+ "endpoint": "/my-health"
+ }
+ }
+
+docker script example
+^^^^^^^^^^^^^^^^^^^^^
+
++--------------------------------+---------+---------------------------+
+| 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 |
++--------------------------------+---------+---------------------------+
+
+During deployment, the K8S plugin maps the healthcheck defined into
+into a Kubernetes readiness probe.
+
+Kubernetes execs the script in the container (using the `docker exec API
+ <https://docs.docker.com/engine/api/v1.29/#tag/Exec>`__ ).
+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:
+
+.. code:: json
+
+ "auxilary": {
+ "healthcheck": {
+ "type": "docker",
+ "script": "/app/resources/check_health.py",
+ "timeout": "30s",
+ "interval": "180s"
+ }
+ }
+
+Ports
+~~~~~
+
+This method of exposing/mapping a local port to a host port is NOT
+RECOMMENDED because of the possibility of port conflicts. If multiple
+instances of a docker container will be running, there definitely will
+be port conflicts. Use at your own risk. (The preferred way to expose a
+port is to do so in the Dockerfile as described
+:any:`here <dcae-cli-docker-ports>`).
+
+.. code:: json
+
+ "auxilary": {
+ "ports": ["8080:8000"]
+ }
+
+In the example above, container port 8080 maps to host port 8000.
+
+Volume Mapping
+~~~~~~~~~~~~~~
+
+.. code:: json
+
+ "auxilary": {
+ "volumes": [
+ {
+ "container": {
+ "bind": "/tmp/docker.sock",
+ "mode": "ro"
+ },
+ "host": {
+ "path": "/var/run/docker.sock"
+ }
+ }
+ ]
+ }
+
+At the top-level:
+
++---------------+-------+-------------------------------------+
+| Property Name | Type | Description |
++===============+=======+=====================================+
+| volumes | array | Contains container and host objects |
++---------------+-------+-------------------------------------+
+
+The ``container`` object contains:
+
+
++-----------------------+-----------------------+-------------------------------+
+| Property Name | Type | Description |
++=======================+=======================+===============================+
+| bind | string | path to the container |
+| | | volume |
++-----------------------+-----------------------+-------------------------------+
+| mode | string | ro - indicates |
+| | | read-only volume |
++-----------------------+-----------------------+-------------------------------+
+| | | w - indicates that |
+| | | the contain can write |
+| | | into the bind mount |
++-----------------------+-----------------------+-------------------------------+
+
+The ``host`` object contains:
+
++---------------+--------+-------------------------+
+| Property Name | Type | Description |
++===============+========+=========================+
+| path | string | path to the host volume |
++---------------+--------+-------------------------+
+
+Here’s an example of the minimal JSON that must be provided as an input:
+
+.. code:: json
+
+ "auxilary": {
+ "volumes": [
+ {
+ "container": {
+ "bind": "/tmp/docker.sock"
+ },
+ "host": {
+ "path": "/var/run/docker.sock"
+ }
+ }
+ ]
+ }
+
+In the example above, the container volume “/tmp/docker.sock” maps to
+host volume “/var/run/docker.sock”.
+
+
+Policy
+~~~~~~~
+
+Policy changes made in the Policy UI will be provided to the Docker
+component by triggering a script that is defined here.
+
++--------------------------------+---------+---------------------------+
+| Property Name | Type | Description |
++================================+=========+===========================+
+| reconfigure_type | string | *Required*. Current value |
+| | | supported is ``policy`` |
++--------------------------------+---------+---------------------------+
+| script_path | string | *Required*. Current value |
+| | | for ‘policy’ |
+| | | reconfigure_type must be |
+| | | “/opt/app/reconfigure.sh” |
++--------------------------------+---------+---------------------------+
+
+Example:
+
+.. code:: json
+
+ "auxilary": {
+ "policy": {
+ "reconfigure_type": "policy",
+ "script_path": "/opt/app/reconfigure.sh"
+ }
+ }
+
+The docker script interface is as follows: \`/opt/app/reconfigure.sh
+$reconfigure_type {“updated policies”: , “application config”: }
+
++---------------------+--------------+----------------------------------------+
+| Name | Type | Description |
++=====================+==============+========================================+
+| reconfigure_type | string | policy |
++---------------------+--------------+----------------------------------------+
+| updated_policies | json | TBD |
++---------------------+--------------+----------------------------------------+
+| updated_appl_config | json | complete generated app_config, not |
+| | | fully-resolved, but ``policy-enabled`` |
+| | | parameters have been updated. In order |
+| | | to get the complete updated |
+| | | app_config, the component would have |
+| | | to call ``config-binding-service``. |
++---------------------+--------------+----------------------------------------+
+
+Docker Component Spec - Complete Example
+----------------------------------------
+
+.. code:: json
+
+ {
+ "self": {
+ "version": "1.0.0",
+ "name": "yourapp.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": "yourapp.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": "yourapp.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": "fake.nexus.att.com/dcae/kpi_anomaly:1.0.0",
+ "type": "docker image"
+ }]
+ }
diff --git a/docs/sections/design-components/component-specification/index-component-specification.rst b/docs/sections/design-components/component-specification/index-component-specification.rst new file mode 100644 index 00000000..76ef2129 --- /dev/null +++ b/docs/sections/design-components/component-specification/index-component-specification.rst @@ -0,0 +1,15 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Component Specification +======================= + +.. toctree:: + :maxdepth: 1 + + ./component-type-docker.rst + ./component-json-schema.rst + ./docker-specification.rst + ./dmaap-connection-objects.rst + ./streams-grid.rst + ./configuration-grid.rst
\ No newline at end of file diff --git a/docs/sections/design-components/component-specification/streams-grid.rst b/docs/sections/design-components/component-specification/streams-grid.rst new file mode 100755 index 00000000..6105e9e1 --- /dev/null +++ b/docs/sections/design-components/component-specification/streams-grid.rst @@ -0,0 +1,149 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _streams-grid:
+
+Streams Formatting Quick Reference
+==================================
+
+Each of the following tables represents an example of a publisher and
+its subscriber, which are of course, different components. This focuses
+on the fields that are ‘different’ for each of these TYPEs, to
+illustrate the relationship between ``config_key``, dmaap connection
+object, and the generated configuration. Some notes on specific
+properties:
+
+- ``config_key`` is an arbitrary string, chosen by the component
+ developer. It is returned in the generated configuration where it
+ contains specific values for the target connection
+- ``format``, ``version``, and ``type`` properties in the subscriber
+ would match these properties in the publisher
+- ``aaf_username`` and ``aaf_password`` may be different between the
+ publisher and the subscriber
+
+Using http
+~~~~~~~~~~
+
+*Publishing Component*
+^^^^^^^^^^^^^^^^^^^^^^
+
++-----------------------------+----------------------------------------+
+| component \ | runtime platform generated config |
+| spec | |
++=============================+========================================+
+| "streams":{ | "streams_publishes":{ |
+| "publishes":[{ | "prediction":"10.100.1.100:32567/data" |
+| "config_key":"prediction", | |
+| "format":"some-format", | |
+| "type":"http", | |
+| "version":"0.1.0" } | |
+| ]} | |
++-----------------------------+----------------------------------------+
+
+*Subscribing Component*
+^^^^^^^^^^^^^^^^^^^^^^^
+
++-----------------------------+----------------------------------------+
+| component | runtime platform generated config |
+| spec | |
++=============================+========================================+
+| “streams”:{ | "N/A" |
+| "subscribes":[{ | |
+| "route":"/data", | |
+| "format":"some-format", | |
+| "type":"http" | |
+| "version":"0.1.0" } | |
+| ]} | |
++-----------------------------+----------------------------------------+
+
+Using Message Router
+~~~~~~~~~~~~~~~~~~~~
+
+.. publishing-component-1:
+
+*Publishing Component*
+^^^^^^^^^^^^^^^^^^^^^^
+
+Note: When deploying, this component should be deployed first so satisfy
+downstream dependencies. Refer to the –force option in component ‘run’
+command for more information.
+
++---------------+------------------------+-----------------------------------------------------------------------------+
+| component \ | Dmaap Connection \ | runtime platform generated \ |
+| spec | Object | config |
++===============+========================+=============================================================================+
+| “streams”:{ | { “dmaap_info”: | “streams_publishes”:{ |
+| “config_k\| {} \ *Note: For \ | “aaf_username”:“pub-user”, |
+| ey”:“mr_out\ | message router, this \ | “type”:“message_router”, |
+| put”, “t\ | object is identical \ | “topic_url”:"https://we-are-message-router.us:3905/events/some-topic"\ |
+| ype”:“messag\ | for the publisher and \| "streams_subscribes":{...} |
+| e_router”, | the subscriber* | |
+| }]} | | |
++---------------+------------------------+-----------------------------------------------------------------------------+
+
+*Subscribing Component*
+^^^^^^^^^^^^^^^^^^^^^^^
+
++---------------+------------------------+-----------------------------------------------------------------------------+
+| component \ | Dmaap Connection \ | runtime platform generated \ |
+| spec | Object | config |
++===============+========================+=============================================================================+
+| “streams”:{ | { “dmaap_info”: | “streams_publishes”:{…}, |
+| “config_k\| {} \ *Note: For \ | “streams_subscribes”:{ |
+| ey”:“mr_inp\ | message router, this \ | “aaf_username”:“sub-user”, |
+| ut”, “ty\ | object is identical \ | “type”:“message_router”, |
+| pe”:“message\ | for the publisher and \| “topic_url”:“https://we-are-message-router.us:3905/events/some-topic" |
+| _router”, | the subscriber* | |
+| }]} | | |
++---------------+------------------------+-----------------------------------------------------------------------------+
+
+Using Data Router
+~~~~~~~~~~~~~~~~~
+
+.. publishing-component-2:
+
+*Publishing Component*
+^^^^^^^^^^^^^^^^^^^^^^
+
++---------------+-----------------------------------------------+-----------------------------------------------+
+| component spec| Dmaap Connection Object | runtime platform generated config |
++===============+===============================================+===============================================+
+| “streams”:{ | { “dmaap_info”: { | streams_publishes“:{ ”typ\ |
+| “config_key: | “location”: | e“:”data_router“, "location":"mtc00" |
+| “dr_output" | “mtc00”, | , |
+| , "type": | “publish_url”: | "publish_url“: |
+| “data_r\ | "https://we-are-data-router.us/feed/xyz"\ | "http://we-are-data-router.us/feed/xyz" |
+| outer”, }] | , | , |
+| } | “log_url”:\ | "log_url“:\ |
+| | \ | ”https://we-are-data-router.us/feed/xyz/logs" |
+| | "https://we-are-data-router.us/feed/xyz/logs"\| , |
+| | , | ”username“:”pub-user“, |
+| | “username”: | ”publisher_id“:”123456\ |
+| | “pub-user”, | “}}, |
+| | “password”: | ”streams_subscribes“:{ |
+| | “pub-password”, | … } |
+| | “publisher_id”: | |
+| | “123456”}} | |
++---------------+-----------------------------------------------+-----------------------------------------------+
+
+.. subscribing-component-1:
+
+*Subscribing Component*
+^^^^^^^^^^^^^^^^^^^^^^^
+
++---------------+---------------------------------------------------+---------------------------------------------------------------------------+
+| component \ | Dmaap Connection \ | runtime platform generated \ |
+| spec | Object | config |
++===============+===================================================+===========================================================================+
+| “streams”:{ | { “dmaap_info”: | “streams_publishes”:{ … }, |
+| “config_k\| { “location”: | “streams_subscribes”:{ |
+| ey”:“dr_inp\ | “mtc00”, | “type”:“data_router”, |
+| ut”, “ty\ | “delivery_url”: | “location”:“mtc00”, |
+| pe”:“data_ro\ | "https://my-subscriber-app.dcae:8080/target-path"\| “delivery_url”:"https://my-subscriber-app.dcae:8080/target-path"\|
+| uter”, | \ | \ |
+| “route”: | , | , |
+| “/target-pat\ | “password”: | \ |
+| h”} | “sub-password”, | “username”:“sub-user”, |
+| | “subscriber_id”: | |
+| | “789012”}} | “subscriber_id”:“789012”}} |
++---------------+---------------------------------------------------+---------------------------------------------------------------------------+
|