diff options
Diffstat (limited to 'platformdoc/docs/components/component-specification')
5 files changed, 779 insertions, 0 deletions
diff --git a/platformdoc/docs/components/component-specification/cdap-specification.md b/platformdoc/docs/components/component-specification/cdap-specification.md new file mode 100644 index 00000000..479cc944 --- /dev/null +++ b/platformdoc/docs/components/component-specification/cdap-specification.md @@ -0,0 +1,163 @@ +# Component specification (CDAP) + +## Overview + +This page contains details specific to CDAP applications. + +The component specification contains the following top-level groups of information: + +* Component [Metadata](#metadata) +* [Parameters](#Parameters): the section for specifying parameters in your AppConfig, AppPreferences, and ProgramPreferences to the Designer and Policy. +* [Interfaces](#interfaces): the connections from this component to other components +* [Auxiliary details](#auxiliary) +* [List of artifacts](#artifacts) + +Note: this page does not talk about [DCAE specific requirements](/components/component-type-cdap.md) that your component must adhere to. Please see that page for discussions about DMaaP, Policy, Metrics, and more. + +## Current Limitations and TODOs + +* Currently we only support CDAP applications that have a stream. +* The integration of DMD is likely to significantly change the [Interfaces](#interfaces) section in this specification, see [DMaaP abstraction](/components/component-type-cdap.md#dmaap-abstraction). + +## Metadata + +See [Metadata](common-specification.md#metadata) + +## Parameters + +There is a `parameters` section in your component specification. This section contains three optional keys: [app_config](#appconfig), [app_preferences](#apppreferences), and [propram_preferences](#prorgram_preferences): +``` +"parameters" : { + "app_config" : [ ...], + "app_preferences" : [ ...], + "program_preferences" : [...] + // any additional keys are ignored +} +``` + +* Each section details the parameters that are a part of each of these CDAP constructs (see below). +* All such parameters will be exposed to the designer and to policy for override. +* These parameters should have default values specified by the component developer where necessary, i.e., parameters that _must_ come from the designer/policy should not have defaults. +* All of these keys are optional because not every CDAP application uses preferences and not every application uses the AppConfig. However, you should specify at least one, or else your application will have no parameters exposed to policy or to the DCAE designer, which means it would be non-configurable. +* Despite the AppConfig being optional to *specify* in the case that you have no parameters in your AppConfig, it is *required for processing* in your application. That is because the DCAE platform will place important information into your AppConfig as discussed below. + +### Parameter +We use the following definition of a _single parameter_, which is used in several places below: +``` + { + "name" : "param name", + "value" : "developer default", + "description" : "tell policy/ops what this does" + } +``` + +### AppConfig + +The `app_config` key refers to the [CDAP AppConfig](http://docs.cask.co/cdap/current/en/reference-manual/http-restful-api/configuration.html). It is expected to be a JSON: +``` +"app_config" : [ // list of JSON + param1, // see Parameter above + ... +] +``` +Unfortunately, at the time of writing, the AppConfig is a Java map of `string:string`, which means you cannot have more complex structures (than string) as any value in your AppConfig. However, there is a way to bypass this constraint: you can pass a JSON by encoding the JSON as a string. E.g., the `json.dumps()` and it's converse `loads` methods in Python: +``` +>>> import json +>>> json.dumps({"foo" : "bar"}) # This is a real JSON +'{"foo": "bar"}' # It is now a string: pass this in as your parameter value +>>> json.loads('{"foo": "bar"}') # Do the equivelent of this in your application +{u'foo': u'bar'} # ...and you'll get back a real JSON +>>> +``` + +The final AppConfig (after the designer and policy override parameter values) is passed into CDAP's AppConfig API when starting your application. + +### AppPreferences + +In addition to the CDAP AppConfig, we support [Application Preferences](http://docs.cask.co/cdap/current/en/reference-manual/http-restful-api/preferences.html#set-preferences). +The format of the `app_preferences` value is the same as the above: +``` +"app_preferences" : [ // list of JSON + param1, // see Parameter above + ... +] +``` + +The final Application Preferences JSON (after the designer and policy override parameter values) is passed into CDAP's Preferences API when starting your application. + +### ProgramPreferences + +Preferences can also be specified [per program](http://docs.cask.co/cdap/current/en/reference-manual/http-restful-api/lifecycle.html#program-lifecycle) in CDAP. This key's value is a list of JSON with the following format: +``` +"program_preferences" : [ // note: this is a list of JSON + { + "program_id" : "program name 1", // the name of this CDAP program + "program_type" : "e.g., flows", // "must be one of flows, mapreduce, schedules, spark, workflows, workers, or services", + "program_pref" : [ // list of JSON + param1, // see Parameter above + ... + ] + }, + // repeat for each program you want to pass a preferences JSON to +] +``` +Each `program_pref` JSON is passed into the CDAP API as the preference for `program_id`. + +## Interfaces +See [Interfaces](common-specification.md#interfaces) + +NOTE: for CDAP, this section is very likely to change when DMD is available. +The _future_ vision, as per [DMaaP intentionally abstracted](/components/component-type-cdap.md#dmaap-abstraction) is that you would publish your data as a series of files on HDFS, and DMD will pick them up and send them to the appropriate DMaaP feeds or directly when needed. + +## Auxiliary + +`auxiliary` contains details about CDAP specific parameters. + +Property Name | Type | Description +------------- | ---- | ----------- +streamname | string | *Required*. +artifact_name | string | +artifact_version | string | the version of your CDAP JAR artifact +namespace | string | the CDAP namespace to deploy into, default is 'default' +programs | array | contains each CDAP entity represented in the artifact +program_type | string | CDAP entity (eg "flows") +program_id | string | name of CDAP entity (eg "WhoFlow") + +Example: + +```json ++"auxiliary": { + "streamname" : "who", + "artifact_name" : "HelloWorld", + "artifact_version" : "3.4.3", + "namespace" : "hw", + "programs" : [ + {"program_type" : "flows", "program_id" : "WhoFlow"}, + {"program_type" : "services", "program_id" : "Greeting"}, + ... + ], +} +``` +The `programs` key is identical to the `program_preferences` key discussed [above](#programpreferences) except: + +* each JSON in the list does not contain `program_pref` +* this is required! You must include all of your programs in this, as it is used to start each program as well as for DCAE to perform periodic healthchecks on your application. Don't forget about your services; they are programs too. + ++ +## Artifacts + +`artifacts` contains a list of artifacts associated with this component. This is where you specify your CDAP jar. + +Property Name | Type | Description +------------- | ---- | ----------- +artifacts | JSON array | Each entry is a artifact object + +Each artifact object has: + +Property Name | Type | Description +------------- | ---- | ----------- +uri | string | *Required*. Uri to the artifact +type | string | *Required*. For CDAP, use `jar` + +This file is uploading using the CLI tool at the same time as your component specification. + diff --git a/platformdoc/docs/components/component-specification/common-specification.md b/platformdoc/docs/components/component-specification/common-specification.md new file mode 100644 index 00000000..77f2a7f0 --- /dev/null +++ b/platformdoc/docs/components/component-specification/common-specification.md @@ -0,0 +1,258 @@ +# Component specification (Common elements) + +This page describes component specification sections that are common (or nearly) to both Docker and CDAP. + +## Component Metadata +Metadata refers to the properties found under the `self` JSON. This group of properties are used to uniquely identify this component specification and identify the component that this specification is used to capture. The metadata section, represented under `self`, is used to uniquely identify your component among all components in the catalog. + +From the specification example above: + +``` +"self": { + "version": "1.0.0", + "name": "asimov.component.kpi_anomaly", + "description": "Classifies VNF KPI data as anomalous", + "component_type": "docker" +}, +``` + +Here is a breakdown of the schema: + +Property Name | Type | Description +------------- | ---- | ----------- +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. The name includes a namespace that is dot-separated. +description | string | Human-readable text blurb describing the component and the components functional purpose. +component_type | string | *Required*. Identify what containerization technology this component uses: `docker` or `cdap`. + +## 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 [data format](/components/data-formats.md). + +### Streams + * The `streams` JSON is for specifying that you produce data that can be consumed by other components, and the streams you expect to subscribe to 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. +* 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 Name | Type | Description +------------- | ---- | ----------- +subscribes | JSON list | *Required*. List of all available stream interfaces that this component has that can be used for subscribing +publishes | JSON list | *Required*. List of all stream interfaces that this component will publish onto + +#### Subscribes + +From the example specification: + +```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 `asimov.component.kpi_anomaly` exposes an HTTP endpoint called `/data` which accepts requests that have the data format of `dcae.vnf.kpi` version `1.0.0`. + +The JSON object schema used in `subscribes`: + +Property Name | Type | Description +------------- | ---- | ----------- +format | string | *Required*. Data format id of the data format that is used by this interface +version | string | *Required*. Data format version of the data format that is used by this interface +route | string | *Required*. The HTTP route that this interface listens on +type | string | *Required*. Type of stream: `http`, `message_router`, `data_router` + +##### Message router + +Message router subscribers are http clients rather than http services and performs a http `GET` call. Thus, message router subscribers description is structured like message router publishers and requires `config_key`: + +```json +"streams": { + "subscribes": [{ + "format": "dcae.some-format", + "version": "1.0.0", + "config_key": "some_format_handle", + "type": "message 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 your subscriber to the provisioned feed. Developers must also provide a `config_key` because there is dynamic configuration information associated with the feed that your application will need e.g. username and password. See the page on [DMaaP connection objects](../dcae-cli/dmaap-connection-objects) for more details on the configuration information. + +Example (not tied to the larger example): + +```json +"streams": { + "subscribes": [{ + "config_key": "some-sub-dr", + "format": "sandbox.platform.any", + "route": "/identity", + "type": "data_router", + "version": "0.1.0" + }], +... +} +``` + +#### Publishes + +From the example specification: + +```json +"streams": { +... + "publishes": [{ + "format": "asimov.format.integerClassification", + "version": "1.0.0", + "config_key": "prediction", + "type": "http" + }] +}, + +``` + +This describes that `asimov.component.kpi_anomaly` publishes by making POST requests to streams that support the data format `asimov.format.integerClassification` version `1.0.0`. + +The JSON object schema used in `publishes`: + +Property Name | Type | Description +------------- | ---- | ----------- +format | string | *Required*. Data format id of the data format that is used by this interface +version | string | *Required*. Data format version of the data format that is used by this interface +config_key | string | *Required*. The JSON key in the generated application configuration that will be used to pass the downstream component connection information. +type | string | *Required*. Type of stream: `http`, `message router` + +##### 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 your application will need to receive e.g. publish url, username, password. See the page on [DMaaP connection objects](../dcae-cli/dmaap-connection-objects) for more details on the configuration information. + +Example (not tied to the larger example): + +```json +"streams": { +... + "publishes": [{ + "config_key": "some-pub-dr", + "format": "sandbox.platform.any", + "type": "data_router", + "version": "0.1.0" + }] +} +``` + +### 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 Name | Type | Description +------------- | ---- | ----------- +calls | JSON list | *Required*. List of all service interfaces that this component will call +provides | JSON list | *Required*. List of all service interfaces that this component exposes and provides + +#### Calls +The JSON `services/calls` is for specifying that your component relies on an HTTP(S) service---your 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`. + +From the example specification: + +```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 `asimov.component.kpi_anomaly` will make HTTP calls to a downstream component that accepts requests of data format `dcae.vnf.meta` version `1.0.0` and is expecting the response to be `dcae.vnf.kpi` version `1.0.0`. + +The JSON object schema used in `calls`: + +Property Name | Type | Description +------------- | ---- | ----------- +request | JSON object | *Required*. Description of the expected request for this downstream interface +response | JSON object | *Required*. Description of the expected response for this downstream interface +config_key | string | *Required*. The JSON key in the generated application configuration that will be used to pass the downstream component connection information. + +The JSON object schema for both `request` and `response`: + +Property Name | Type | Description +------------- | ---- | ----------- +format | string | *Required*. Data format id of the data format that is used by this interface +version | string | *Required*. Data format version of the data format that is used by this interface + +#### Provides + +From the example specification: + +```json +"services": { +... + "provides": [{ + "route": "/score-vnf", + "request": { + "format": "dcae.vnf.meta", + "version": "1.0.0" + }, + "response": { + "format": "asimov.format.integerClassification", + "version": "1.0.0" + } + }] +}, +``` + +This describes that `asimov.component.kpi_anomaly` provides a service interface and it is exposed on the `/score-vnf` HTTP endpoint. The endpoint accepts requests that have the data format `dcae.vnf.meta` version `1.0.0` and gives back a response of `asimov.format.integerClassification` version `1.0.0`. + +The JSON object schema used in `provides`: + +Property Name | Type | Description +------------- | ---- | ----------- +request | JSON object | *Required*. Description of the expected request for this interface +response | JSON object | *Required*. Description of the expected response for this interface +route | string | *Required*. The HTTP route that this interface listens on + +The JSON object schema for both `request` and `response`: + +Property Name | Type | Description +------------- | ---- | ----------- +format | string | *Required*. Data format id of the data format that is used by this interface +version | string | *Required*. Data format version of the data format that is used by this interface + +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 + } + ] +``` diff --git a/platformdoc/docs/components/component-specification/docker-specification.md b/platformdoc/docs/components/component-specification/docker-specification.md new file mode 100644 index 00000000..2bff6c47 --- /dev/null +++ b/platformdoc/docs/components/component-specification/docker-specification.md @@ -0,0 +1,246 @@ +# Component specification (Docker) + +This page contains details specific to Dockerized applications. + +The component specification contains the following top-level groups of information: + +* [Component metadata](#metadata) +* [Component interfaces](#interfaces) including the associated [data formats](/components/data-formats.md) +* [Configuration parameters](#configuration-parameters) +* [Auxiliary details](#auxilary) +* [List of artifacts](#artifacts) + +## Metadata + +See [Metadata](common-specification.md#metadata) + +## Interfaces + +See [Interfaces](common-specification.md#interfaces) + +## Configuration parameters + +`parameters` is where to specify the component's application configuration parameters that are not connection information. + +Property Name | Type | Description +------------- | ---- | ----------- +parameters | JSON array | Each entry is a parameter object + +Parameter object has the following available properties: + +Property Name | Type | Description | Default +------------- | ---- | ----------- | ------- +name | string | *Required*. The property name that will be used as the key in the generated config | +value | any | *Required*. The default value for the given parameter | +description | string | *Required*. Human-readable text describing the parameter like what its for | +type | string | The required data type for the parameter | +required | boolean | An optional key that declares a parameter as required (true) or not (false) | true +constraints | array | The optional list of sequenced constraint clauses for the parameter | +entry_schema | string | The optional key that is used to declare the name of the Datatype definition for entries of set types such as the TOSCA list or map | +designer_editable | boolean | An optional key that declares a parameter to be editable by designer (true) or not (false) | true +policy_editable | boolean | An optional key that declares a parameter to be editable by policy (true) or not (false) | true +policy_schema | array | The optional list of schema definitions used for policy | + +Many of the parameter properties have been copied from TOSCA model property definitions and are to be used for service design composition and policy creation. See [section 3.5.8 *Property definition*](http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.1/TOSCA-Simple-Profile-YAML-v1.1.html). + +The property `constraints` is a list of objects where each constraint object: + +Property Name | Type | Description +------------- | ---- | ----------- +equal | | Constrains a property or parameter to a value equal to (‘=’) the value declared +greater_than | number | Constrains a property or parameter to a value greater than (‘>’) the value declared +greater_or_equal | number | Constrains a property or parameter to a value greater than or equal to (‘>=’) the value declared +less_than | number | Constrains a property or parameter to a value less than (‘<’) the value declared +less_or_equal | number | Constrains a property or parameter to a value less than or equal to (‘<=’) the value declared +valid_values | array | Constrains a property or parameter to a value that is in the list of declared values +length | number | Constrains the property or parameter to a value of a given length +min_length | number | Constrains the property or parameter to a value to a minimum length +max_length | number | Constrains the property or parameter to a value to a maximum length + +From the example specification: + +```json +"parameters": [ + { + "name": "threshold", + "value": 0.75, + "description": "Probability threshold to exceed to be anomalous" + } +] +``` + +`threshold` is the configuration parameter and will get set to 0.75 when the configuration gets generated. + +## Auxiliary + +`auxilary` contains Docker specific details like health check and port mapping information. + +Property Name | Type | Description +------------- | ---- | ----------- +healthcheck | JSON object | *Required*. Health check definition details +ports | JSON array | each array item maps a container port to the host port. See example below. + +### Health check definition + +The platform uses Consul to perform periodic health check calls. Consul provides different types of [check definitions](https://www.consul.io/docs/agent/checks.html). The platform currently supports http and docker health checks. + +#### http + +Property Name | Type | Description +------------- | ---- | ----------- +type | string | *Required*. `http` +interval | string | Interval duration in seconds i.e. `15s` +timeout | string | Timeout in seconds i.e. `1s` +endpoint | string | *Required*. GET endpoint provided by the component for Consul to call to check health + +Example: + +```json +"auxilary": { + "healthcheck": { + "type": "http", + "interval": "15s", + "timeout": "1s", + "endpoint": "/my-health" + } +} +``` + +#### docker + +Property Name | Type | Description +------------- | ---- | ----------- +type | string | *Required*. `docker` +interval | string | Interval duration in seconds i.e. `15s` +timeout | string | Timeout in seconds i.e. `1s` +script | string | *Required*. Full path of script that exists in the Docker container to be executed + +Consul will use the [Docker exec API](https://docs.docker.com/engine/api/v1.29/#tag/Exec) to periodically call your script in your container. It will examine the script result to identify whether your component is healthy. Your component is considered healthy when the script returns `0` otherwise your component is considered not healthy. + +Example: + +```json +"auxilary": { + "healthcheck": { + "type": "docker", + "script": "/app/resources/check_health.py", + "timeout": "30s", + "interval": "180s" + } +} +``` + +### Ports example + +Example: + +```json +"auxilary": { + "ports": ["8080:8000"] +} +``` + +In the example above, container port 8080 maps to host port 8000. + +## Artifacts + +`artifacts` contains a list of artifacts associated with this component. For Docker, this would be where you specify your Docker image full path including registry. + +Property Name | Type | Description +------------- | ---- | ----------- +artifacts | JSON array | Each entry is a artifact object + +Each artifact object has: + +Property Name | Type | Description +------------- | ---- | ----------- +uri | string | *Required*. Uri to the artifact +type | string | *Required*. `docker image` or `jar` + +## Example +Here is a full example of a component spec: + +```json +{ + "self": { + "version": "1.0.0", + "name": "asimov.component.kpi_anomaly", + "description": "Classifies VNF KPI data as anomalous", + "component_type": "docker" + }, + "streams": { + "subscribes": [{ + "format": "dcae.vnf.kpi", + "version": "1.0.0", + "route": "/data", + "type": "http" + }], + "publishes": [{ + "format": "asimov.format.integerClassification", + "version": "1.0.0", + "config_key": "prediction", + "type": "http" + }] + }, + "services": { + "calls": [{ + "config_key": "vnf-db", + "request": { + "format": "dcae.vnf.meta", + "version": "1.0.0" + }, + "response": { + "format": "dcae.vnf.kpi", + "version": "1.0.0" + } + }], + "provides": [{ + "route": "/score-vnf", + "request": { + "format": "dcae.vnf.meta", + "version": "1.0.0" + }, + "response": { + "format": "asimov.format.integerClassification", + "version": "1.0.0" + } + }] + }, + "parameters": [ + { + "name": "threshold", + "value": 0.75, + "description": "Probability threshold to exceed to be anomalous" + } + ], + "auxilary": { + "healthcheck": { + "type": "http", + "interval": "15s", + "timeout": "1s", + "endpoint": "/my-health" + } + }, + "artifacts": [{ + "uri": "YOUR_NEXUS_DOCKER_REGISTRY/kpi_anomaly:1.0.0", + "type": "docker image" + }] +} +``` + +## Generate application configuration + +The above example `asimov.component.kpi_anomaly` will get transformed into the following application configuration JSON that is fully resolved and provided at runtime by calling the config binding service: + +```json +{ + "streams_publishes": { + "prediction": ["10.100.1.100:32567"] + }, + "streams_subscribes": {}, + "threshold": 0.75, + "services_calls": { + "vnf-db": ["10.100.1.101:32890"] + } +} +``` diff --git a/platformdoc/docs/components/component-specification/generated-configuration.md b/platformdoc/docs/components/component-specification/generated-configuration.md new file mode 100644 index 00000000..258358de --- /dev/null +++ b/platformdoc/docs/components/component-specification/generated-configuration.md @@ -0,0 +1,91 @@ +# Generated configuration + +The DCAE platform relies on the component specification to generate the component's application configuration JSON at deployment time. The component developer should expect to use this configuration JSON in their application to provision themselves. + +Pro-tip: As you build your component specification, you can use the [dcae-cli `dev` command](../dcae-cli/walkthrough/#dev) to view what the resulting application configuration will look like. + +## Streams and services + +For both Docker and CDAP, when your component is deployed, any `streams` and `services/calls` you specified will be injected into your configuration under the following well known structure. +Your component is required to parse this information if you have any connectivity to DMaaP or are calling another DCAE component. + +More details about the DMaaP connection objects are found [here](../dcae-cli/dmaap-connection-objects/). + +This is best served with an example. + +The following component spec snippet (from String Matching): +``` +"streams":{ + "subscribes": [{ + "format": "VES_specification", + "version": "4.27.2", + "type": "message_router", + "config_key" : "mr_input" + }], + "publishes": [{ + "format": "VES_specification", + "version": "4.27.2", + "config_key": "mr_output", + "type": "message_router" + }] + }, + "services":{ + "calls": [{ + "config_key" : "aai_broker_handle", + "verb": "GET", + "request": { + "format": "get_with_query_params", + "version": "1.0.0" + }, + "response": { + "format": "aai_broker_response", + "version": "3.0.0" + } + }], + "provides": [] + }, +``` + +Will turn into the following top level keys in your configuration (for CDAP, this will be under AppConfig) + +``` + "streams_publishes":{ + "mr_output":{ // notice the config key above + "aaf_password":"XXX", + "type":"message_router", + "dmaap_info":{ + "client_role": null, + "client_id": null, + "location": null, + "topic_url":"XXX" + }, + "aaf_username":"XXX" + } + }, + "streams_subscribes":{ + "mr_input":{ // notice the config key above + "aaf_password":"XXX", + "type":"message_router", + "dmaap_info":{ + "client_role": null, + "client_id": null, + "location": null, + "topic_url":"XXX" + }, + "aaf_username":"XXX" + } + }, + "services_calls":{ + "aai_broker_handle":[ // notice the config key above + "SOME_IP:32768" // based on deployment time, just an example + ] + } +``` +These keys will always be populated regardless of whether they are empty. So the minimal you will get, in the case of a component that provides an HTTP service and does not call any services and has no streams, is: +``` + "streams_publishes":{}, + "streams_subscribes":{}, + "services_calls":{} +``` + +Thus your component should expect these well-known top level keys. diff --git a/platformdoc/docs/components/component-specification/start-here.md b/platformdoc/docs/components/component-specification/start-here.md new file mode 100644 index 00000000..3816dd06 --- /dev/null +++ b/platformdoc/docs/components/component-specification/start-here.md @@ -0,0 +1,21 @@ +# Component specification + +Every component that onboards onto the DCAE platform requires a component specification. The component specification is a JSON artifact that fully describes your components. The format of the component specification is standardized for CDAP applications and Dockerized applications and is validated using [a JSON schema](ONAP URL TBD). + +The component specification is used by: + +* Design - TOSCA models are generated from the component specification so that your component can be used by designers to compose new DCAE services in SDC. +* Policy - TOSCA models are generated from the component specification so that operations can create policy models used to dynamically configure your component. +* Runtime platform - Your component's application configuration (JSON) is generated from the component specification and will be provided to your component at runtime. + +## dcae-cli + +Use the [`dcae-cli`](../dcae-cli/quickstart) tool to manage your component specification and to test your components with it. + +The dcae-cli can also be used to view component specifications that have already been added and published. Please check out the [shared catalog](../dcae-cli/walkthrough/#shared-catalog) for examples for both Docker and CDAP. + +## Next + +If you are building a CDAP application, review the [component specification details for CDAP](cdap-specification.md). + +If you are building a Dockerized application, review the [component specification details for Docker](docker-specification.md). |