diff options
Diffstat (limited to 'docs/resourcedefinition/resourcesource.rst')
| -rw-r--r-- | docs/resourcedefinition/resourcesource.rst | 421 |
1 files changed, 421 insertions, 0 deletions
diff --git a/docs/resourcedefinition/resourcesource.rst b/docs/resourcedefinition/resourcesource.rst new file mode 100644 index 000000000..4b7c8c73e --- /dev/null +++ b/docs/resourcedefinition/resourcesource.rst @@ -0,0 +1,421 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2019 IBM. + +Resource Source +--------------- +.. toctree:: + :maxdepth: 4 + +Input: +====== +Expects the value to be provided as input to the request. + +.. code-block:: json + :linenos: + + { + "source-input" : + { + "description": "This is Input Resource Source Node Type", + "version": "1.0.0", + "properties": {}, + "derived_from": "tosca.nodes.ResourceSource" + } + } + +Default: +======== +Expects the value to be defaulted in the model itself. + +.. code-block:: json + :linenos: + + { + "source-default" : + { + "description": "This is Default Resource Source Node Type", + "version": "1.0.0", + "properties": {}, + "derived_from": "tosca.nodes.ResourceSource" + } + } + +Sql: +==== + +Expects the SQL query to be modeled; that SQL query can be parameterized, and the parameters be other resources resolved through other means. If that's the case, this data dictionary definition will have to define key-dependencies along with input-key-mapping. + +CDS is currently deployed along the side of SDNC, hence the primary database connection provided by the framework is to SDNC database. + +|image0| + +.. |image0| image:: media/sqltable.JPG + :width: 400pt + +.. code-block:: json + :linenos: + + { + "description": "This is Database Resource Source Node Type", + "version": "1.0.0", + "properties": { + "type": { + "required": true, + "type": "string", + "constraints": [ + { + "valid_values": [ + "SQL" + ] + } + ] + }, + "endpoint-selector": { + "required": false, + "type": "string" + }, + "query": { + "required": true, + "type": "string" + }, + "input-key-mapping": { + "required": false, + "type": "map", + "entry_schema": { + "type": "string" + } + }, + "output-key-mapping": { + "required": false, + "type": "map", + "entry_schema": { + "type": "string" + } + }, + "key-dependencies": { + "required": true, + "type": "list", + "entry_schema": { + "type": "string" + } + } + }, + "derived_from": "tosca.nodes.ResourceSource" + } + +Connection to a specific database can be expressed through the endpoint-selector property, which refers to a macro defining the information about the database the connect to. Understand TOSCA Macro in the context of CDS. + +.. code-block:: json + :linenos: + + { + "dsl_definitions": { + "dynamic-db-source": { + "type": "maria-db", + "url": "jdbc:mysql://localhost:3306/sdnctl", + "username": "<username>", + "password": "<password>" + } + } + } + +Rest: +===== + +Expects the URI along with the VERB and the payload, if needed. + +CDS is currently deployed along the side of SDNC, hence the default rest connection provided by the framework is to SDNC MDSAL. + +|image1| + +.. |image1| image:: media/optional.JPG + :width: 400pt + +.. code-block:: json + :linenos: + + { + "description": "This is Rest Resource Source Node Type", + "version": "1.0.0", + "properties": { + "type": { + "required": false, + "type": "string", + "default": "JSON", + "constraints": [ + { + "valid_values": [ + "JSON" + ] + } + ] + }, + "verb": { + "required": false, + "type": "string", + "default": "GET", + "constraints": [ + { + "valid_values": [ + "GET", "POST", "DELETE", "PUT" + ] + } + ] + }, + "payload": { + "required": false, + "type": "string", + "default": "" + }, + "endpoint-selector": { + "required": false, + "type": "string" + }, + "url-path": { + "required": true, + "type": "string" + }, + "path": { + "required": true, + "type": "string" + }, + "expression-type": { + "required": false, + "type": "string", + "default": "JSON_PATH", + "constraints": [ + { + "valid_values": [ + "JSON_PATH", + "JSON_POINTER" + ] + } + ] + }, + "input-key-mapping": { + "required": false, + "type": "map", + "entry_schema": { + "type": "string" + } + }, + "output-key-mapping": { + "required": false, + "type": "map", + "entry_schema": { + "type": "string" + } + }, + "key-dependencies": { + "required": true, + "type": "list", + "entry_schema": { + "type": "string" + } + } + }, + "derived_from": "tosca.nodes.ResourceSource" + } + +Connection to a specific REST system can be expressed through the endpoint-selector property, which refers to a macro defining the information about the REST system the connect to. Understand TOSCA Macro in the context of CDS. + +Few ways are available to authenticate to the REST system: + * token-auth + * basic-auth + * ssl-basic-auth + +token-auth: +~~~~~~~~~~~ + +.. code-block:: json + :linenos: + + { + "dsl_definitions": { + "dynamic-rest-source": { + "type" : "token-auth", + "url" : "http://localhost:32778", + "token" : "<token>" + } + } + } + +basic-auth: +~~~~~~~~~~~ + +.. code-block:: json + :linenos: + + { + "dsl_definitions": { + "dynamic-rest-source": { + "type" : "basic-auth", + "url" : "http://localhost:32778", + "username" : "<username>", + "password": "<password>" + } + } + } + +ssl-basic-auth: +~~~~~~~~~~~~~~~ + +.. code-block:: json + :linenos: + + { + "dsl_definitions": { + "dynamic-rest-source": { + "type" : "ssl-basic-auth", + "url" : "http://localhost:32778", + "keyStoreInstance": "JKS or PKCS12", + "sslTrust": "trusture", + "sslTrustPassword": "<password>", + "sslKey": "keystore", + "sslKeyPassword": "<password>" + } + } + } + +Capability: +=========== + +Expects a script to be provided. + +|image2| + +.. |image2| image:: media/capabilitytable.JPG + :width: 400pt + +.. code-block:: json + :linenos: + + { + "description": "This is Component Resource Source Node Type", + "version": "1.0.0", + "properties": { + "script-type": { + "required": true, + "type": "string", + "default": "kotlin", + "constraints": [ + { + "valid_values": [ + "kotlin", + "jython" + ] + } + ] + }, + "script-class-reference": { + "description": "Capability reference name for internal and kotlin, for jython script file path", + "required": true, + "type": "string" + }, + "instance-dependencies": { + "required": false, + "description": "Instance dependency Names to Inject to Kotlin / Jython Script.", + "type": "list", + "entry_schema": { + "type": "string" + } + }, + "key-dependencies": { + "description": "Resource Resolution dependency dictionary names.", + "required": true, + "type": "list", + "entry_schema": { + "type": "string" + } + } + }, + "derived_from": "tosca.nodes.ResourceSource" + } + +Complex Type: +============= + +Value will be resolved through REST., and output will be a complex type. + +Modeling reference: Modeling Concepts#rest + +In this example, we're making a POST request to an IPAM system with no payload. + +Some ingredients are required to perform the query, in this case, $prefixId. Hence It is provided as an input-key-mapping and defined as a key-dependencies. Please refer to the modeling guideline for more in depth understanding. + +As part of this request, the expected response will be as below. + +.. code-block:: json + :linenos: + + { + "id": 4, + "address": "192.168.10.2/32", + "vrf": null, + "tenant": null, + "status": 1, + "role": null, + "interface": null, + "description": "", + "nat_inside": null, + "created": "2018-08-30", + "last_updated": "2018-08-30T14:59:05.277820Z" + } + +What is of interest is the address and id fields. For the process to return these two values, we need to create a custom data-type, as bellow + +.. code-block:: json + :linenos: + + { + "version": "1.0.0", + "description": "This is Netbox IP Data Type", + "properties": { + "address": { + "required": true, + "type": "string" + }, + "id": { + "required": true, + "type": "integer" + } + }, + "derived_from": "tosca.datatypes.Root" + } + +The type of the data dictionary will be dt-netbox-ip. + +To tell the resolution framework what is of interest in the response, the output-key-mapping section is used. The process will map the output-key-mapping to the defined data-type. + +.. code-block:: json + + { + "tags" : "oam-local-ipv4-address", + "name" : "create_netbox_ip", + "property" : { + "description" : "netbox ip", + "type" : "dt-netbox-ip" + }, + "updated-by" : "adetalhouet", + "sources" : { + "config-data" : { + "type" : "source-rest", + "properties" : { + "type" : "JSON", + "verb" : "POST", + "endpoint-selector" : "ipam-1", + "url-path" : "/api/ipam/prefixes/$prefixId/available-ips/", + "path" : "", + "input-key-mapping" : { + "prefixId" : "prefix-id" + }, + "output-key-mapping" : { + "address" : "address", + "id" : "id" + }, + "key-dependencies" : [ "prefix-id" ] + } + } + } + }
\ No newline at end of file |