aboutsummaryrefslogtreecommitdiffstats
path: root/docs/resourcedefinition
diff options
context:
space:
mode:
authorSingal, Kapil (ks220y) <ks220y@att.com>2020-09-24 12:47:56 -0400
committerSingal, Kapil (ks220y) <ks220y@att.com>2020-09-24 18:07:12 -0400
commitf1aafc40ad8f15b61faa3631e5a56fcf7c34bf49 (patch)
tree27b4a52b99472d4781814751f4c46343b82960a5 /docs/resourcedefinition
parent2b0442d1d2e721c4bf762bb2a3e75bc7606f9fcf (diff)
Refactoring Docs
Issue-ID: CCSDK-2846 Signed-off-by: Singal, Kapil (ks220y) <ks220y@att.com> Change-Id: I34e469deb914fc4e452159a2c3419270f8eb97bc
Diffstat (limited to 'docs/resourcedefinition')
-rw-r--r--docs/resourcedefinition/index.rst107
-rw-r--r--docs/resourcedefinition/media/capabilitytable.JPGbin0 -> 57448 bytes
-rw-r--r--docs/resourcedefinition/media/mandatory.JPGbin0 -> 48105 bytes
-rw-r--r--docs/resourcedefinition/media/optional.JPGbin0 -> 79730 bytes
-rw-r--r--docs/resourcedefinition/media/sqltable.JPGbin0 -> 36259 bytes
-rw-r--r--docs/resourcedefinition/resourcesource.rst421
6 files changed, 528 insertions, 0 deletions
diff --git a/docs/resourcedefinition/index.rst b/docs/resourcedefinition/index.rst
new file mode 100644
index 000000000..a91d5999f
--- /dev/null
+++ b/docs/resourcedefinition/index.rst
@@ -0,0 +1,107 @@
+.. 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 Definition
+-------------------
+.. toctree::
+ :maxdepth: 2
+
+Introduction:
+=============
+A Resource definition models the how a specific resource can be resolved.
+
+A resource is a variable/parameter in the context of the service. It can be anything, but it should not be confused with SDC or Openstack resources.
+
+A Resource definition can have multiple sources to handle resolution in different ways. The main goal of Resource definition is to define re-usable entity that could be shared.
+
+Creation of Resource definition is a standalone activity, separated from the blueprint design.
+
+As part of modelling a Resource definition entry, the following generic information should be provided:
+
+|image0|
+
+
+Below are properties that all the resource source have will have
+
+The modeling does allow for data translation between external capability and CDS for both input and output key mapping.
+
+|image1|
+
+
+Example:
+========
+
+vf-module-model-customization-uuid and vf-module-label are two data dictionaries. A SQL table, VF_MODULE_MODEL, exist to correlate them.
+
+Here is how input-key-mapping, output-key-mapping and key-dependencies can be used:
+
+.. 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"
+ }
+
+
+Resource source:
+================
+
+Defines the contract to resolve a resource.
+
+A resource source is modeled, following TOSCA_ node type definition and derives from the Resource_ source.
+
+Also please click below for resource source available details
+
+.. toctree::
+ :maxdepth: 4
+
+ resourcesource
+
+.. _TOSCA: http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.0/csprd01/TOSCA-Simple-Profile-YAML-v1.0-csprd01.html#DEFN_ENTITY_NODE_TYPE
+.. _Resource: https://wiki.onap.org/display/DW/Modeling+Concepts#ModelingConcepts-NodeResourceSource
+
+
+.. |image0| image:: media/mandatory.JPG
+ :width: 400pt
+
+.. |image1| image:: media/optional.JPG
+ :width: 400pt \ No newline at end of file
diff --git a/docs/resourcedefinition/media/capabilitytable.JPG b/docs/resourcedefinition/media/capabilitytable.JPG
new file mode 100644
index 000000000..7db4715ea
--- /dev/null
+++ b/docs/resourcedefinition/media/capabilitytable.JPG
Binary files differ
diff --git a/docs/resourcedefinition/media/mandatory.JPG b/docs/resourcedefinition/media/mandatory.JPG
new file mode 100644
index 000000000..074d20076
--- /dev/null
+++ b/docs/resourcedefinition/media/mandatory.JPG
Binary files differ
diff --git a/docs/resourcedefinition/media/optional.JPG b/docs/resourcedefinition/media/optional.JPG
new file mode 100644
index 000000000..a27502a75
--- /dev/null
+++ b/docs/resourcedefinition/media/optional.JPG
Binary files differ
diff --git a/docs/resourcedefinition/media/sqltable.JPG b/docs/resourcedefinition/media/sqltable.JPG
new file mode 100644
index 000000000..15d246743
--- /dev/null
+++ b/docs/resourcedefinition/media/sqltable.JPG
Binary files differ
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