dmaap/README.md

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