docs/resourcedefinition/resourcesource.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright (C) 2019 IBM.
   4
   5 Resource Source
   6 ---------------
   7 .. toctree::
   8    :maxdepth: 4
   9
  10 Input:
  11 ======
  12 Expects the value to be provided as input to the request.
  13
  14 .. code-block:: json
  15    :linenos:
  16
  17    {
  18      "source-input" :
  19      {
  20        "description": "This is Input Resource Source Node Type",
  21        "version": "1.0.0",
  22        "properties": {},
  23        "derived_from": "tosca.nodes.ResourceSource"
  24      }
  25    }
  26
  27 Default:
  28 ========
  29 Expects the value to be defaulted in the model itself.
  30
  31 .. code-block:: json
  32    :linenos:
  33
  34    {
  35      "source-default" :
  36      {
  37        "description": "This is Default Resource Source Node Type",
  38        "version": "1.0.0",
  39        "properties": {},
  40        "derived_from": "tosca.nodes.ResourceSource"
  41      }
  42    }
  43
  44 Sql:
  45 ====
  46
  47 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.
  48
  49 CDS is currently deployed along the side of SDNC, hence the primary database connection provided by the framework is to SDNC database.
  50
  51 |image0|
  52
  53 .. |image0| image:: media/sqltable.JPG
  54    :width: 400pt
  55
  56 .. code-block:: json
  57    :linenos:
  58
  59    {
  60       "description": "This is Database Resource Source Node Type",
  61       "version": "1.0.0",
  62       "properties": {
  63         "type": {
  64           "required": true,
  65           "type": "string",
  66           "constraints": [
  67             {
  68               "valid_values": [
  69                 "SQL"
  70               ]
  71             }
  72           ]
  73         },
  74         "endpoint-selector": {
  75           "required": false,
  76           "type": "string"
  77         },
  78         "query": {
  79           "required": true,
  80           "type": "string"
  81         },
  82         "input-key-mapping": {
  83           "required": false,
  84           "type": "map",
  85           "entry_schema": {
  86             "type": "string"
  87           }
  88         },
  89         "output-key-mapping": {
  90           "required": false,
  91           "type": "map",
  92           "entry_schema": {
  93             "type": "string"
  94           }
  95         },
  96         "key-dependencies": {
  97           "required": true,
  98           "type": "list",
  99           "entry_schema": {
 100             "type": "string"
 101           }
 102         }
 103       },
 104       "derived_from": "tosca.nodes.ResourceSource"
 105    }
 106
 107 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.
 108
 109 .. code-block:: json
 110    :linenos:
 111
 112    {
 113      "dsl_definitions": {
 114        "dynamic-db-source": {
 115          "type": "maria-db",
 116          "url": "jdbc:mysql://localhost:3306/sdnctl",
 117          "username": "<username>",
 118          "password": "<password>"
 119        }
 120      }
 121    }
 122
 123 Rest:
 124 =====
 125
 126 Expects the URI along with the VERB and the payload, if needed.
 127
 128 CDS is currently deployed along the side of SDNC, hence the default rest connection provided by the framework is to SDNC MDSAL.
 129
 130 |image1|
 131
 132 .. |image1| image:: media/optional.JPG
 133    :width: 400pt
 134
 135 .. code-block:: json
 136    :linenos:
 137
 138    {
 139       "description": "This is Rest Resource Source Node Type",
 140       "version": "1.0.0",
 141       "properties": {
 142         "type": {
 143           "required": false,
 144           "type": "string",
 145           "default": "JSON",
 146           "constraints": [
 147             {
 148               "valid_values": [
 149                 "JSON"
 150               ]
 151             }
 152           ]
 153         },
 154         "verb": {
 155           "required": false,
 156           "type": "string",
 157           "default": "GET",
 158           "constraints": [
 159             {
 160               "valid_values": [
 161                 "GET", "POST", "DELETE", "PUT"
 162               ]
 163             }
 164           ]
 165         },
 166         "payload": {
 167           "required": false,
 168           "type": "string",
 169           "default": ""
 170         },
 171         "endpoint-selector": {
 172           "required": false,
 173           "type": "string"
 174         },
 175         "url-path": {
 176           "required": true,
 177           "type": "string"
 178         },
 179         "path": {
 180           "required": true,
 181           "type": "string"
 182         },
 183         "expression-type": {
 184           "required": false,
 185           "type": "string",
 186           "default": "JSON_PATH",
 187           "constraints": [
 188             {
 189               "valid_values": [
 190                 "JSON_PATH",
 191                 "JSON_POINTER"
 192               ]
 193             }
 194           ]
 195         },
 196         "input-key-mapping": {
 197           "required": false,
 198           "type": "map",
 199           "entry_schema": {
 200             "type": "string"
 201           }
 202         },
 203         "output-key-mapping": {
 204           "required": false,
 205           "type": "map",
 206           "entry_schema": {
 207             "type": "string"
 208           }
 209         },
 210         "key-dependencies": {
 211           "required": true,
 212           "type": "list",
 213           "entry_schema": {
 214             "type": "string"
 215           }
 216         }
 217       },
 218       "derived_from": "tosca.nodes.ResourceSource"
 219    }
 220
 221 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.
 222
 223 Few ways are available to authenticate to the REST system:
 224     * token-auth
 225     * basic-auth
 226     * ssl-basic-auth
 227
 228 token-auth:
 229 ~~~~~~~~~~~
 230
 231 .. code-block:: json
 232    :linenos:
 233
 234    {
 235      "dsl_definitions": {
 236        "dynamic-rest-source": {
 237          "type" : "token-auth",
 238          "url" : "http://localhost:32778",
 239          "token" : "<token>"
 240        }
 241      }
 242    }
 243
 244 basic-auth:
 245 ~~~~~~~~~~~
 246
 247 .. code-block:: json
 248    :linenos:
 249
 250    {
 251      "dsl_definitions": {
 252        "dynamic-rest-source": {
 253          "type" : "basic-auth",
 254          "url" : "http://localhost:32778",
 255          "username" : "<username>",
 256          "password": "<password>"
 257        }
 258      }
 259    }
 260
 261 ssl-basic-auth:
 262 ~~~~~~~~~~~~~~~
 263
 264 .. code-block:: json
 265    :linenos:
 266
 267    {
 268      "dsl_definitions": {
 269        "dynamic-rest-source": {
 270          "type" : "ssl-basic-auth",
 271          "url" : "http://localhost:32778",
 272          "keyStoreInstance": "JKS or PKCS12",
 273          "sslTrust": "trusture",
 274          "sslTrustPassword": "<password>",
 275          "sslKey": "keystore",
 276          "sslKeyPassword": "<password>"
 277        }
 278      }
 279    }
 280
 281 Capability:
 282 ===========
 283
 284 Expects a script to be provided.
 285
 286 |image2|
 287
 288 .. |image2| image:: media/capabilitytable.JPG
 289    :width: 400pt
 290
 291 .. code-block:: json
 292    :linenos:
 293
 294    {
 295       "description": "This is Component Resource Source Node Type",
 296       "version": "1.0.0",
 297       "properties": {
 298         "script-type": {
 299           "required": true,
 300           "type": "string",
 301           "default": "kotlin",
 302           "constraints": [
 303             {
 304               "valid_values": [
 305                 "kotlin",
 306                 "jython"
 307               ]
 308             }
 309           ]
 310         },
 311         "script-class-reference": {
 312           "description": "Capability reference name for internal and kotlin, for jython script file path",
 313           "required": true,
 314           "type": "string"
 315         },
 316         "instance-dependencies": {
 317           "required": false,
 318           "description": "Instance dependency Names to Inject to Kotlin / Jython Script.",
 319           "type": "list",
 320           "entry_schema": {
 321             "type": "string"
 322           }
 323         },
 324         "key-dependencies": {
 325           "description": "Resource Resolution dependency dictionary names.",
 326           "required": true,
 327           "type": "list",
 328           "entry_schema": {
 329             "type": "string"
 330           }
 331         }
 332       },
 333       "derived_from": "tosca.nodes.ResourceSource"
 334    }
 335
 336 Complex Type:
 337 =============
 338
 339 Value will be resolved through REST., and output will be a complex type.
 340
 341 Modeling reference: Modeling Concepts#rest
 342
 343 In this example, we're making a POST request to an IPAM system with no payload.
 344
 345 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.
 346
 347 As part of this request, the expected response will be as below.
 348
 349 .. code-block:: json
 350    :linenos:
 351
 352    {
 353       "id": 4,
 354       "address": "192.168.10.2/32",
 355       "vrf": null,
 356       "tenant": null,
 357       "status": 1,
 358       "role": null,
 359       "interface": null,
 360       "description": "",
 361       "nat_inside": null,
 362       "created": "2018-08-30",
 363       "last_updated": "2018-08-30T14:59:05.277820Z"
 364    }
 365
 366 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
 367
 368 .. code-block:: json
 369    :linenos:
 370
 371    {
 372      "version": "1.0.0",
 373      "description": "This is Netbox IP Data Type",
 374      "properties": {
 375        "address": {
 376          "required": true,
 377          "type": "string"
 378        },
 379        "id": {
 380          "required": true,
 381          "type": "integer"
 382        }
 383      },
 384      "derived_from": "tosca.datatypes.Root"
 385    }
 386
 387 The type of the data dictionary will be dt-netbox-ip.
 388
 389 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.
 390
 391 .. code-block:: json
 392
 393   {
 394     "tags" : "oam-local-ipv4-address",
 395     "name" : "create_netbox_ip",
 396     "property" : {
 397       "description" : "netbox ip",
 398       "type" : "dt-netbox-ip"
 399     },
 400     "updated-by" : "adetalhouet",
 401     "sources" : {
 402       "config-data" : {
 403         "type" : "source-rest",
 404         "properties" : {
 405           "type" : "JSON",
 406           "verb" : "POST",
 407           "endpoint-selector" : "ipam-1",
 408           "url-path" : "/api/ipam/prefixes/$prefixId/available-ips/",
 409           "path" : "",
 410           "input-key-mapping" : {
 411             "prefixId" : "prefix-id"
 412           },
 413           "output-key-mapping" : {
 414             "address" : "address",
 415             "id" : "id"
 416           },
 417           "key-dependencies" : [ "prefix-id" ]
 418         }
 419       }
 420     }
 421   }