docs/platform/plugins/dmaap.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4
   5 Cloudify DMaaP Plugin
   6 =====================
   7
   8 Cloudify plugin for creating and managing DMaaP Data Router feeds and
   9 subscriptions and DMaaP Message Router topics. The plugin uses the DMaaP
  10 Bus Controller API.
  11
  12 Plugin Support for DMaaP Data Router
  13 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  14
  15 Plugin Types for DMaaP Data Router
  16 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  17
  18 The Cloudify type definitions for DMaaP Data Router nodes and
  19 relationships are defined in ```dmaap.yaml`` <./dmaap.yaml>`__.
  20
  21 There are four node types for DMaaP Data Router:
  22
  23 -  ``ccsdk.nodes.Feed``: This type represents a feed that does not yet
  24    exist and that should be created when the install workflow is run
  25    against a blueprint that contains a node of this type.
  26
  27 +------------------------+----------+-------------+---------------------------------------------------------------------------------------------+
  28 | Property               | Type     | Required?   | Description                                                                                 |
  29 +========================+==========+=============+=============================================================================================+
  30 | feed\_name             | string   | no          | a name that identifies the feed (plugin will generate if absent)                            |
  31 +------------------------+----------+-------------+---------------------------------------------------------------------------------------------+
  32 | feed\_version          | string   | no          | version number for the feed (feed\_name + feed\_version uniquely identify the feed in DR)   |
  33 +------------------------+----------+-------------+---------------------------------------------------------------------------------------------+
  34 | feed\_description      | string   | no          | human-readable description of the feed                                                      |
  35 +------------------------+----------+-------------+---------------------------------------------------------------------------------------------+
  36 | aspr\_classification   | string   | no          | AT&T ASPR classification of the feed                                                        |
  37 +------------------------+----------+-------------+---------------------------------------------------------------------------------------------+
  38
  39 -  ``ccsdk.nodes.ExistingFeed``: This type represents a feed that
  40    already exists. Nodes of this type are placed in a blueprint so that
  41    other nodes in the blueprint can be set up as publishers or
  42    subscribers to the feed. The table below shows the properties that a
  43    node of this type may have.
  44
  45 +------------+----------+-------------+---------------------------------------------------------------+
  46 | Property   | Type     | Required?   | Description                                                   |
  47 +============+==========+=============+===============================================================+
  48 | feed\_id   | string   | yes         | Feed identifier assigned by DMaaP when the feed was created   |
  49 +------------+----------+-------------+---------------------------------------------------------------+
  50
  51 -  ``ccsdk.nodes.ExternalTargetFeed``: This type represents a feed
  52    created in an external DMaaP environment (i.e., an environment that
  53    the plugin cannot access to make provisioning requests, such as a
  54    shared corporate system). Nodes of this type are placed in a
  55    blueprint so that other feed nodes of type ``ccsdk.nodes.Feed`` or
  56    ``ccsdk.nodes.ExistingFeed`` can be set up to "bridge" to external
  57    feeds by publishing data to the external feeds. The table below shows
  58    the properties that a node of this type may have.
  59
  60 +------------+----------+-------------+----------------------------------------------------------------+
  61 | Property   | Type     | Required?   | Description                                                    |
  62 +============+==========+=============+================================================================+
  63 | url        | string   | yes         | The publish URL of the external feed.                          |
  64 +------------+----------+-------------+----------------------------------------------------------------+
  65 | username   | string   | yes         | The username to be used when delivering to the external feed   |
  66 +------------+----------+-------------+----------------------------------------------------------------+
  67 | userpw     | string   | yes         | The password to be used when delivering to the external feed   |
  68 +------------+----------+-------------+----------------------------------------------------------------+
  69
  70 *Note: These properties are usually obtained by manually creating a feed
  71 in the external DMaaP DR system and then creating a publisher for that
  72 feed.*
  73
  74 -  ``ccsdk.nodes.ExternalSourceFeed``: This type represents a feed
  75    created in an external DMaaP environment (i.e., an environment that
  76    the plugin cannot access to makes provisioning requests, such as a
  77    shared corporate system). Nodes of this type are place in a blueprint
  78    so that they can be set up to "bridge" to other feed nodes of type
  79    ``ccsdk.nodes.Feed`` or ``ccsdk.nodes.ExistingFeed``. This type has
  80    no node properties, but when a bridge is set up, the url, username,
  81    and password are attached to the node as runtime\_properties, using
  82    the name of the target feed node as the top-level key.
  83
  84 There are five relationship types for DMaaP Data Router:
  85
  86 -  ``ccsdk.relationships.publish_files``, used to indicate that the
  87    relationship's source node sends is a publisher to the Data Router
  88    feed represented by the relationship's target node.
  89 -  ``ccsdk.relationships.subscribe_to_files``, used to indicate that the
  90    relationship's source node is a subscriber to the Data Router feed
  91    represented by the relationship's target node.
  92 -  ``ccsdk.relationships.bridges_to``, used to indicate that the
  93    relationship's source node (a ``ccsdk.nodes.Feed`` or
  94    ``ccsdk.nodes.ExistingFeed``) should be set up to forward data
  95    ("bridge") to the relationship's target feed (another
  96    ``ccsdk.nodes.Feed`` or ``ccsdk.nodes.ExistingFeed``).
  97 -  ``ccsdk.relationships.bridges_to_external``, used to indicate that
  98    the relationship's source node (a ``ccsdk.nodes.Feed`` or
  99    ``ccsdk.nodes.ExistingFeed``) should be set up to forward data
 100    ("bridge") to the relationship's target node (a feed in an external
 101    DMaaP system, represented by a ``ccsdk.nodes.ExternalTargetFeed``
 102    node).
 103 -  ``ccsdk.relationships.bridges_from_external_to_internal``, used to
 104    indicate the the relationship's source node (a feed in an external
 105    DMaaP system, represented by a ``ccsdk.nodes.ExternalSourceFeed``
 106    node) should be set up to forward date ("bridge") to the
 107    relationship's target node (an internal ONAP feed, represented by a
 108    ``ccsdk.nodes.Feed`` or ``ccsdk.nodes.ExistingFeed`` node).
 109
 110 The plugin code implements the lifecycle operations needed to create and
 111 delete feeds and to add and remove publishers and subscribers. It also
 112 implements the operations needed to set up bridging between feeds.
 113
 114 Interaction with Other Plugins
 115 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 116
 117 When creating a new feed or processing a reference to an existing feed,
 118 the plugin operates independently of other plugins.
 119
 120 When processing a ``ccsdk.relationships.publish_files`` relationship or
 121 a ``ccsdk.relationships.subscribe_to_files`` relationship, this plugin
 122 needs to obtain data from the source node and, in the case of
 123 ``publish_files``, provide data to the source node. Certain conventions
 124 are therefore needed for passing data between this plugin and the
 125 plugins responsible for the source nodes in these relationships. In
 126 Cloudify, the mechanism for sharing data among plugins is the
 127 ``ctx.instance.runtime_properties`` dictionary associated with each
 128 node.
 129
 130 A given source node may have relationships with several feeds. For
 131 example, an ONAP DCAE data collector might publish two different types
 132 of data to two different feeds. An ONAP DCAE analytics module might
 133 subscribe to one feed to get input for its processing and publish its
 134 results to a different feed. When this DMaaP plugin and the plugin for
 135 the source node exchange information, they need to do in a way that lets
 136 them distinguish among different feeds. We do this through a simple
 137 convention: for each source node to feed relationship, the source node
 138 plugin will create a property in the source node's
 139 ``runtime_properties`` dictionary. The name of the property will be the
 140 same as the name of the target node of the relationship. For instance,
 141 if a node has a ``publishes_files`` relationship with a target node
 142 named ``feed00``, then the plugin that's responsible for managing the
 143 source node with create an entry in the source node's
 144 ``runtime_properties`` dictionary named ``feed00``. This entry itself
 145 will be a dictionary.
 146
 147 The content of this data exchange dictionary depends on whether the
 148 source node is a publisher (i.e., the relationship is ``publish_files``)
 149 or a subscriber (i.e., the relationship is ``subscribe_to_files``).
 150
 151 For the ``publish_files`` relationship, the data exchange dictionary has
 152 the following properties:
 153
 154 +----------------+----------------------+--------------------------------------------------------------------------------------------------+
 155 | Property       | Set by               | Description                                                                                      |
 156 +================+======================+==================================================================================================+
 157 | location       | source node plugin   | the DMaaP location for the publisher, used to set up routing                                     |
 158 +----------------+----------------------+--------------------------------------------------------------------------------------------------+
 159 | publish\_url   | DMaaP plugin         | the URL to which the publisher makes Data Router publish requests                                |
 160 +----------------+----------------------+--------------------------------------------------------------------------------------------------+
 161 | log\_url       | DMaaP plugin         | the URL from which log data for the feed can be obtained                                         |
 162 +----------------+----------------------+--------------------------------------------------------------------------------------------------+
 163 | username       | DMaaP plugin         | the username (generated by the DMaaP plugin) the publisher uses to authenticate to Data Router   |
 164 +----------------+----------------------+--------------------------------------------------------------------------------------------------+
 165 | password       | DMaaP plugin         | the password (generated by the DMaaP plugin) the publisher uses to authenticate to Data Router   |
 166 +----------------+----------------------+--------------------------------------------------------------------------------------------------+
 167
 168 For the ``subscribe_to_files`` relationship, the data exchange
 169 dictionary has the following properties:
 170
 171 +-----------------+----------------------+-----------------------------------------------------------------------------------------+
 172 | Property        | Set by               | Description                                                                             |
 173 +=================+======================+=========================================================================================+
 174 | location        | source node plugin   | the DMaaP location for the subscriber, used to set up routing                           |
 175 +-----------------+----------------------+-----------------------------------------------------------------------------------------+
 176 | delivery\_url   | source node plugin   | the URL to which the Data Router should deliver files                                   |
 177 +-----------------+----------------------+-----------------------------------------------------------------------------------------+
 178 | username        | source node plugin   | the username Data Router uses to authenticate to the subscriber when delivering files   |
 179 +-----------------+----------------------+-----------------------------------------------------------------------------------------+
 180 | password        | source node plugin   | the username Data Router uses to authenticate to the subscriber when delivering file    |
 181 +-----------------+----------------------+-----------------------------------------------------------------------------------------+
 182
 183 Plugin Support for DMaaP Message Router
 184 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 185
 186 Plugin Types for DMaaP Message Router
 187 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 188
 189 The Cloudify type definitions for DMaaP Message Router nodes and
 190 relationships are defined in ```dmaap.yaml`` <./dmaap.yaml>`__.
 191
 192 There are two node types for DMaaP Message Router:
 193
 194 -  ``ccsdk.nodes.Topic``: This type represents a topic that does not yet
 195    exist and that should be created when the install workflow is run
 196    against a blueprint that contains a node of this type.
 197
 198 +----------------------+-----------+-------------+-----------------------------------------------------------------------------+
 199 | Property             | Type      | Required?   | Description                                                                 |
 200 +======================+===========+=============+=============================================================================+
 201 | topic\_name          | string    | no          | a name that uniquely identifies the feed (plugin will generate if absent)   |
 202 +----------------------+-----------+-------------+-----------------------------------------------------------------------------+
 203 | topic\_description   | string    | no          | human-readable description of the feed                                      |
 204 +----------------------+-----------+-------------+-----------------------------------------------------------------------------+
 205 | txenable             | boolean   | no          | flag indicating whether transactions are enabled for this topic             |
 206 +----------------------+-----------+-------------+-----------------------------------------------------------------------------+
 207 | replication\_case    | string    | no          | type of replication required for the topic (defaults to no replication)     |
 208 +----------------------+-----------+-------------+-----------------------------------------------------------------------------+
 209 | global\_mr\_url      | string    | no          | Global MR host name for replication to a global MR instance                 |
 210 +----------------------+-----------+-------------+-----------------------------------------------------------------------------+
 211
 212 Note: In order to set up topics, a user should be familiar with message
 213 router and how it is configured, and this README is not the place to
 214 explain the details of message router. Here are a couple of pieces of
 215 information that might be helpful. Currently, the allowed values for
 216 ``replication_case`` are:
 217
 218 -  ``REPLICATION_NONE``
 219 -  ``REPLICATION_EDGE_TO_CENTRAL``
 220 -  ``REPLICATION_EDGE_TO_CENTRAL_TO_GLOBAL``
 221 -  ``REPLICATION_CENTRAL_TO_EDGE``
 222 -  ``REPLICATION_CENTRAL_TO_GLOBAL``
 223 -  ``REPLICATION_GLOBAL_TO_CENTRAL``
 224 -  ``REPLICATION_GLOBAL_TO_CENTRAL_TO_EDGE``
 225
 226 The ``global_mr_url`` is actually a host name, not a full URL. It points
 227 to a host in a global message router cluster. (A 'global' message router
 228 cluster is one that's not part of ONAP.)
 229
 230 -  ``ccsdk.nodes.ExistingTopic``: This type represents a topic that
 231    already exists. Nodes of this type are placed in a blueprint so that
 232    other nodes in the blueprint can be set up as publishers or
 233    subscribers to the topic. The table below shows the properties that a
 234    node of this type may have.
 235
 236 +------------+----------+-------------+--------------------------------------------+
 237 | Property   | Type     | Required?   | Description                                |
 238 +============+==========+=============+============================================+
 239 | fqtn       | string   | yes         | fully-qualified topic name for the topic   |
 240 +------------+----------+-------------+--------------------------------------------+
 241
 242 Interaction with Other Plugins
 243 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 244
 245 When creating a new topic or processing a reference to an existing
 246 topic, the plugin operates independently of other plugins.
 247
 248 When processing a ``ccsdk.relationships.publish_events`` relationship or
 249 a ``ccsdk.relationships.subscribe_to_events`` relationship, this plugin
 250 needs to obtain data from and provide data to the source node. Certain
 251 conventions are therefore needed for passing data between this plugin
 252 and the plugins responsible for the source nodes in these relationships.
 253 In Cloudify, the mechanism for sharing data among plugins is the
 254 ``ctx.instance.runtime_properties`` dictionary associated with each
 255 node.
 256
 257 A given source node may have relationships with several topics. For
 258 example, an ONAP DCAE analytics module might subscribe to one topic to
 259 get input for its processing and publish its results to a different
 260 topic. When this DMaaP plugin and the plugin for the source node
 261 exchange information, they need to do in a way that lets them
 262 distinguish among different feeds. We do this through a simple
 263 convention: for each source node to topic relationship, the source node
 264 plugin will create a property in the source node's
 265 ``runtime_properties`` dictionary. The name of the property will be the
 266 same as the name of the target node of the relationship. For instance,
 267 if a node has a ``publishes_events`` relationship with a target node
 268 named ``topic00``, then the plugin that's responsible for managing the
 269 source node with create an entry in the source node's
 270 ``runtime_properties`` dictionary named ``topic00``. This entry itself
 271 will be a dictionary.
 272
 273 For both types of relationship, the data exchange dictionary has the
 274 following properties:
 275
 276 +----------------+----------------------+----------------------------------------------------------------------------------+
 277 | Property       | Set by               | Description                                                                      |
 278 +================+======================+==================================================================================+
 279 | location       | source node plugin   | the DMaaP location for the publisher or subscriber, used to set up routing       |
 280 +----------------+----------------------+----------------------------------------------------------------------------------+
 281 | client\_role   | source node plugin   | the AAF client role that's requesting publish or subscribe access to the topic   |
 282 +----------------+----------------------+----------------------------------------------------------------------------------+
 283 | topic\_url     | DMaaP plugin         | the URL for accessing the topic to publish or receive events                     |
 284 +----------------+----------------------+----------------------------------------------------------------------------------+
 285
 286 Interaction with Consul configuration store
 287 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 288
 289 In addition to storing the results of DMaaP Data Router and DMaaP
 290 Message Router provisioning operations in ``runtime_properties``, the
 291 DMaaP plugin also stores these results into the ONAP configuration
 292 store, which resides in a `Consul key-value
 293 store <https://www.consul.io/>`__. This allows DMaaP clients (components
 294 that act as publishers, subscribers, or both) to retrieve their DMaaP
 295 configuration information from Consul, rather than having the plugin
 296 that deploys the client directly configure the client using data in
 297 ``runtime_properties``.
 298
 299 The ``runtime_properties`` for a client must contain a property called
 300 ``service_component_name``. If this property is not present, the plugin
 301 will raise a NonRecoverableError and cause the installation to fail.
 302
 303 If ``service_component_name`` is present, then the plugin will use a
 304 Consul key consisting of the value of ``service_component_name``
 305 prepended to the fixed string ``:dmaap``. For example, if the
 306 ``service_component_name`` is ``client123``, the plugin will use
 307 ``client123:dmaap`` as the key for storing DMaaP information into
 308 Consul. Information for all of the feeds and topics for a client are
 309 stored under the same key.
 310
 311 The value stored is a nested JSON object. At the top level of the object
 312 are properties representing each topic or feed for which the component
 313 is a publisher or subscriber. The name of the property is the node name
 314 of the target feed or topic. The value of the property is another JSON
 315 object that corresponds to the dictionary that the plugin created in
 316 ``runtime_properties`` corresponding to the target feed or topic. Note
 317 that the information in Consul includes all of the properties for the
 318 feed or topic, those set by the source node plugin as well as those set
 319 by the DMaaP plugin.
 320
 321 Examples:
 322
 323 Data Router publisher, target feed ``feed00``:
 324
 325 ::
 326
 327     {
 328       "feed00": {
 329         "username": "rC9QR51I",
 330         "log_url": "https://dmaap.example.com/feedlog/972",
 331         "publish_url": "https://dmaap.example.com/publish/972",
 332         "location": "loc00",
 333         "password": "QOQeUh5KLR",
 334         "publisher_id": "972.360gm"
 335       }
 336     }
 337
 338 Data Router subscriber, target feed ``feed01``:
 339
 340 ::
 341
 342     {
 343       "feed01": {
 344         "username": "drdeliver",
 345         "password": "1loveDataR0uter",
 346         "location": "loc00",
 347         "delivery_url": "https://example.com/whatever",
 348         "subscriber_id": "1550"
 349       }
 350     }
 351
 352 Message Router publisher to ``topic00``, subscriber to ``topic01``. Note
 353 how each topic appears as a top-level property in the object.
 354
 355 ::
 356
 357     {
 358       "topic00": {
 359         "topic_url": "https://dmaap.example.com:3905/events/org.onap.ccsdk.dmaap.FTL2.outboundx",
 360         "client_role": "org.onap.ccsdk.member",
 361         "location": "loc00",
 362         "client_id": "1494621774522"
 363       },
 364       "topic01": {
 365         "topic_url": "https://dmaap.example.com:3905/events/org.onap.ccsdk.dmaap.FTL2.inboundx",
 366         "client_role": "org.onap.ccsdk.member",
 367         "location": "loc00",
 368         "client_id": "1494621778627"
 369       }
 370     }
 371
 372 Packaging and installing
 373 ~~~~~~~~~~~~~~~~~~~~~~~~
 374
 375 The DMaaP plugin is meant to be used as a `Cloudify managed
 376 plugin <http://docs.getcloudify.org/3.4.0/plugins/using-plugins/>`__.
 377 Managed plugins are packaged using
 378 ```wagon`` <https://github.com/cloudify-cosmo/wagon>`__.
 379
 380 To package this plugin, executing the following command in the top-level
 381 directory of this plugin, from a Python environment in which ``wagon``
 382 has been installed:
 383
 384 ::
 385
 386     wagon create -s . -r -o /path/to/directory/for/wagon/output
 387
 388 Once the wagon file is built, it can be uploaded to a Cloudify Manager
 389 host using the ``cfy plugins upload`` command described in the
 390 documentation above.
 391
 392 Managed plugins can also be loaded at the time a Cloudify Manager host
 393 is installed, via the installation blueprint and inputs file. We expect
 394 that this plugin will be loaded at Cloudify Manager installation time,
 395 and that ``cfy plugins upload`` will be used only for delivering patches
 396 between releases.
 397
 398 Configuration
 399 ~~~~~~~~~~~~~
 400
 401 The plugin needs to be configured with certain parameters needed to
 402 access the DMaaP Bus Controller. In keeping with the ONAP architecture,
 403 this information is stored in Consul.
 404
 405 The plugin finds the address and port of the DMaaP Bus Controller using
 406 the Consul service discovery facility. The plugin expects the Bus
 407 Controller to be registered under the name ``dmaap_bus_controller``.
 408
 409 Additional parameters come from the ``dmaap`` key in the Cloudify
 410 Manager's Consul configuration, which is stored in the Consul KV store
 411 under the key name 'cloudify\_manager'. The table below lists the
 412 properties in the configuration:
 413
 414 +----------------+----------+-------------+--------------+---------------------------------------------------------------------------------------------+
 415 | Property       | Type     | Required?   | Default      | Description                                                                                 |
 416 +================+==========+=============+==============+=============================================================================================+
 417 | ``username``   | string   | Yes         | (none)       | The username for logging into DMaaP Bus Controller                                          |
 418 +----------------+----------+-------------+--------------+---------------------------------------------------------------------------------------------+
 419 | ``password``   | string   | Yes         | (none)       | The password for logging into DMaaP Bus Controller                                          |
 420 +----------------+----------+-------------+--------------+---------------------------------------------------------------------------------------------+
 421 | ``owner``      | string   | Yes         | (none)       | The name to be used as the owner for entities created by the plugin                         |
 422 +----------------+----------+-------------+--------------+---------------------------------------------------------------------------------------------+
 423 | ``protocol``   | string   | No          | ``https``    | The protocol (URL scheme) used to access the DMaaP bus controller (``http`` or ``https``)   |
 424 +----------------+----------+-------------+--------------+---------------------------------------------------------------------------------------------+
 425 | ``path``       | string   | No          | ``webapi``   | The path to the root of the DMaaP Bus Controller API endpoint                               |
 426 +----------------+----------+-------------+--------------+---------------------------------------------------------------------------------------------+
 427
 428 Here is an example of a Cloudify Manager configuration object showing
 429 only the ``dmaap`` key:
 430
 431 ::
 432
 433     {
 434       "dmaap": {
 435         "username": "dmaap.client@ccsdkorch.onap.org",
 436         "password": "guessmeifyoucan"
 437         "owner": "ccsdkorc"
 438       },
 439
 440       (other configuration here)
 441
 442     }
 443