docs/sections/services/dfc/configuration.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.\r
   2 .. http://creativecommons.org/licenses/by/4.0\r
   3 \r
   4 =============================\r
   5 Configuration and Performance\r
   6 =============================\r
   7 The DataFile Collector (DFC) gets fileReady messages from the Message Router (MR) sent from xNFs, via the VES Collector.\r
   8 These messages contains data about files ready to get from the xNF. DFC then collects these files from the xNF and\r
   9 publishes them to the DataRouter (DR) on a feed. Consumers can subscribe to the feed from DR and process the file for\r
  10 its specific purpose. The connection between a file type and the feed it will be published to is the\r
  11 **changeIdentifier**. DFC can handle multiple **changeIdentifier**/feed combinations, see picture below.\r
  12 \r
  13 .. image:: ../../images/DFC_config.png\r
  14 \r
  15 \r
  16 \r
  17 Configuration\r
  18 ^^^^^^^^^^^^^\r
  19 By default, DFC handles the "PM_MEAS_FILES" change identifier and publishes these files on the "bulk_pm_feed" feed.\r
  20 But it can also be configured to handle more/other change identifiers and publish them to more/other feeds. The\r
  21 configuration of DFC is controlled via a blueprint.\r
  22 \r
  23 Blueprint Configuration Explained\r
  24 """""""""""""""""""""""""""""""""\r
  25 \r
  26 For the communication with the Message Router, the user must provide the **host name**, **port**, and **protocol** of\r
  27 the DMaaP Message router.\r
  28 \r
  29 .. code-block:: yaml\r
  30   :emphasize-lines: 2,6,10\r
  31 \r
  32     inputs:\r
  33       dmaap_mr_host:\r
  34         type: string\r
  35         description: dmaap messagerouter host\r
  36         default: message-router.onap.svc.cluster.local\r
  37       dmaap_mr_port:\r
  38         type: integer\r
  39         description: dmaap messagerouter port\r
  40         default: 3904\r
  41       dmaap_mr_protocol:\r
  42         type: string\r
  43         description: dmaap messagerouter protocol\r
  44         default: "http"\r
  45 \r
  46 The user can also specify which version of DFC to use.\r
  47 \r
  48 .. code-block:: yaml\r
  49   :emphasize-lines: 2\r
  50 \r
  51     inputs:\r
  52       tag_version:\r
  53         type: string\r
  54         description: DFC image tag/version\r
  55         default: "nexus3.onap.org:10001/onap/org.onap.dcaegen2.collectors.datafile.datafile-app-server:1.2.0"\r
  56 \r
  57 The user can also enable secure communication with the DMaaP Message Router.\r
  58 \r
  59 .. code-block:: yaml\r
  60   :emphasize-lines: 2\r
  61 \r
  62     inputs:\r
  63       secureEnableCert:\r
  64         type: boolean\r
  65         description: enable certificate based connection with DMaap\r
  66         default: false\r
  67 \r
  68 DFC can handle multiple change identifiers. For each change identifier/feed combination the user must provide the\r
  69 **change identifier**, **feed name**, and **feed location**.\r
  70 \r
  71 **Note!** The **feed name** provided should be used by the consumer/s to set up the subscription to the feed.\r
  72 \r
  73 The **feed name** and **feed location** are defined as inputs for the user to provide.\r
  74 \r
  75 .. code-block:: yaml\r
  76   :emphasize-lines: 2,6\r
  77 \r
  78     inputs:\r
  79       feed0_name:\r
  80         type: string\r
  81         description: The name of the feed the files will be published to. Should be used by the subscriber.\r
  82         default: "bulk_pm_feed"\r
  83       feed0_location:\r
  84         type: string\r
  85         description: The location of the feed.\r
  86         default: "loc00"\r
  87 \r
  88 The **feed name** shall be used in the definition of the feed for the DMaaP plugin under the "**node_templates**"\r
  89 section under a tag for the  internal "**feed identifier**" for the feed (feed0 in the example).\r
  90 \r
  91 .. code-block:: yaml\r
  92   :emphasize-lines: 1,5\r
  93 \r
  94     feed0:\r
  95       type: ccsdk.nodes.Feed\r
  96       properties:\r
  97         feed_name:\r
  98           get_input: feed0_name\r
  99         useExisting: true\r
 100 \r
 101 The **feed location** shall be used under the **streams_publishes** section under a tag for the internal\r
 102 "**feed identifier**" for the feed.\r
 103 \r
 104 .. code-block:: yaml\r
 105   :emphasize-lines: 2,4\r
 106 \r
 107       streams_publishes:\r
 108       - name: feed0\r
 109         location:\r
 110           get_input: feed0_location\r
 111         type: data_router\r
 112 \r
 113 The **change identifier** shall be defined as an item under the **streams_publishes** tag in the "**application_config**"\r
 114 section. Under this tag the internal "**feed identifier**" for the feed shall also be added to get the\r
 115 info about the feed substituted in by CBS (that's what the <<>> tags are for).\r
 116 \r
 117 .. code-block:: yaml\r
 118   :emphasize-lines: 4,5\r
 119 \r
 120       application_config:\r
 121         service_calls: []\r
 122         streams_publishes:\r
 123           PM_MEAS_FILES:\r
 124             dmaap_info: <<feed0>>\r
 125             type: data_router\r
 126 \r
 127 And, lastly, to set up the publication relationship for the feed, the "**feed identifier**" must be added to the\r
 128 "**relationships**" section of the blueprint.\r
 129 \r
 130 .. code-block:: yaml\r
 131   :emphasize-lines: 3\r
 132 \r
 133    relationships:\r
 134     - type: ccsdk.relationships.publish_files\r
 135       target: feed0\r
 136 \r
 137 Sample blueprint configuration\r
 138 """"""""""""""""""""""""""""""\r
 139 \r
 140 The format of the blueprint configuration that drives all behavior of DFC is probably best described using an example.\r
 141 The blueprint below configures DFC to handle the two feeds shown in the picture above.\r
 142 \r
 143 .. code-block:: yaml\r
 144 \r
 145     inputs:\r
 146       dmaap_mr_host:\r
 147         type: string\r
 148         description: dmaap messagerouter host\r
 149         default: message-router.onap.svc.cluster.local\r
 150       dmaap_mr_port:\r
 151         type: integer\r
 152         description: dmaap messagerouter port\r
 153         default: 3904\r
 154       dmaap_mr_protocol:\r
 155         type: string\r
 156         description: dmaap messagerouter protocol\r
 157         default: "http"\r
 158       tag_version:\r
 159         type: string\r
 160         description: DFC image tag/version\r
 161         default: "nexus3.onap.org:10001/onap/org.onap.dcaegen2.collectors.datafile.datafile-app-server:1.2.0"\r
 162       replicas:\r
 163         type: integer\r
 164         description: number of instances\r
 165         default: 1\r
 166       secureEnableCert:\r
 167         type: boolean\r
 168         description: enable certificate based connection with DMaap\r
 169         default: false\r
 170       envs:\r
 171         default: {}\r
 172       feed0_name:\r
 173         type: string\r
 174         description: The name of the feed the files will be published to. Should be used by the subscriber.\r
 175         default: "bulk_pm_feed"\r
 176       feed0_location:\r
 177         type: string\r
 178         description: The location of the feed.\r
 179         default: "loc00"\r
 180       feed1_name:\r
 181         type: string\r
 182         description: The name of the feed the files will be published to. Should be used by the subscriber.\r
 183         default: "log_feed"\r
 184       feed1_location:\r
 185         type: string\r
 186         description: The location of the feed.\r
 187         default: "loc00"\r
 188     node_templates:\r
 189       datafile-collector:\r
 190         type: dcae.nodes.ContainerizedServiceComponentUsingDmaap\r
 191         interfaces:\r
 192           cloudify.interfaces.lifecycle:\r
 193             start:\r
 194               inputs:\r
 195             envs:\r
 196               get_input: envs\r
 197         properties:\r
 198           application_config:\r
 199             service_calls: []\r
 200             dmaap.security.enableDmaapCertAuth: { get_input: secureEnableCert }\r
 201             streams_subscribes:\r
 202               dmaap_subscriber:\r
 203                 dmaap_info:\r
 204                   topic_url:\r
 205                     { concat: [{ get_input: dmaap_mr_protocol },"://",{ get_input: dmaap_mr_host },\r
 206                                ":",{ get_input: dmaap_mr_port },"/events/unauthenticated.VES_NOTIFICATION_OUTPUT/OpenDcae-c12/C12"]}\r
 207             streams_publishes:\r
 208               PM_MEAS_FILES:\r
 209                 dmaap_info: <<feed0>>\r
 210                 type: data_router\r
 211               LOG_FILES:\r
 212                 dmaap_info: <<feed1>>\r
 213                 type: data_router\r
 214           image:\r
 215             get_input: tag_version\r
 216           service_component_type: datafile-collector\r
 217           streams_publishes:\r
 218           - name: feed0\r
 219             location:\r
 220               get_input: feed0_location\r
 221             type: data_router\r
 222           - name: feed1\r
 223             location:\r
 224               get_input: feed1_location\r
 225             type: data_router\r
 226         relationships:\r
 227           - type: ccsdk.relationships.publish_files\r
 228             target: feed0\r
 229           - type: ccsdk.relationships.publish_files\r
 230             target: feed1\r
 231       feed0:\r
 232         type: ccsdk.nodes.Feed\r
 233         properties:\r
 234           feed_name:\r
 235             get_input: feed0_name\r
 236           useExisting: true\r
 237       feed1:\r
 238         type: ccsdk.nodes.Feed\r
 239         properties:\r
 240           feed_name:\r
 241             get_input: feed1_name\r
 242           useExisting: true\r
 243 \r
 244 .. _strict_host_checking_config:\r
 245 \r
 246 Turn On/Off StrictHostChecking\r
 247 ------------------------------\r
 248 **StrictHostChecking** is a SSH connection option which prevents Man in the Middle (MitM) attacks. If it is enabled, client checks HostName and public key provided by server and compares it with keys stored locally. Only if matching entry is found, SSH connection can be established.\r
 249 By default in DataFile Collector this option is enabled (true) and requires to provide known_hosts list to DFC container.\r
 250 \r
 251 **Important: DFC requires public keys in sha-rsa KeyAlgorithm** \r
 252 \r
 253 **Known_hosts file** is a list in following format:\r
 254 \r
 255 .. code-block:: bash\r
 256 \r
 257   <HostName/HostIP> <KeyAlgorithms> <Public Key>\r
 258 \r
 259 e.g: \r
 260 \r
 261 .. code-block:: bash\r
 262 \r
 263   172.17.0.3 ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDRibxPenQC//2hzTuscdQDUA7P3gB9k4E8IgwCJxZM8YrJ2vqHomN8boByubebvo0L8+DWqzAtjy0nvgzsoEme9Y3lLWZ/2g9stlsOurwm+nFmWn/RPnwjqsAGNQjukV8C9D82rPMOYRES6qSGactFw4i8ZWLH8pmuJ3js1jb91HSlwr4zbZZd2XPKHk3nudyh8/Mwf3rndCU5FSnzjpBo55m48nsl2M1Tb6Xj1R0jQc5LWN0fsbrm5m+szsk4ccgHw6Vj9dr0Jh4EaIpNwA68k4LzrWb/N20bW8NzUsyDSQK8oEo1dvsiw8G9/AogBjQu9N4bqKWcrk5DOLCZHiCTSbbvdMWAMHXBdxEt9GZ0V53Fzwm8fI2EmIHdLhI4BWKZajumsfHRnd6UUxxna9ySt6qxVYZTyrPvfOFR3hRxVaxHL3EXplGeHT8fnoj+viai+TeSDdjMNwqU4MrngzrNKNLBHIl705uASpHUaRYQxUfWw/zgKeYlIbH+aGgE+4Q1vnh10Y35pATePRZgBIu+h2KsYBAtrP88LqW562OQ6T7VkfoAYwOjx9WV3/y5qonsStPhhzmJHDF22oBh5E5tZQxRcIlQF+5kHmXnFRUZtWshFnQATBh3yhOzJbh66CXn7aPj5Kl8TuuSN48zuI2lulVVqcv7GmTS0tWNpbxpzw==\r
 264 \r
 265 HostName could also be hashed, e.g:\r
 266 \r
 267 .. code-block:: bash\r
 268 \r
 269   |1|FwSOxXYeJyZMAQM3jREjLSIcxRw=|o/b+CHEeHuED7WZS6sb3Y1IyHjk= ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDRibxPenQC//2hzTuscdQDUA7P3gB9k4E8IgwCJxZM8YrJ2vqHomN8boByubebvo0L8+DWqzAtjy0nvgzsoEme9Y3lLWZ/2g9stlsOurwm+nFmWn/RPnwjqsAGNQjukV8C9D82rPMOYRES6qSGactFw4i8ZWLH8pmuJ3js1jb91HSlwr4zbZZd2XPKHk3nudyh8/Mwf3rndCU5FSnzjpBo55m48nsl2M1Tb6Xj1R0jQc5LWN0fsbrm5m+szsk4ccgHw6Vj9dr0Jh4EaIpNwA68k4LzrWb/N20bW8NzUsyDSQK8oEo1dvsiw8G9/AogBjQu9N4bqKWcrk5DOLCZHiCTSbbvdMWAMHXBdxEt9GZ0V53Fzwm8fI2EmIHdLhI4BWKZajumsfHRnd6UUxxna9ySt6qxVYZTyrPvfOFR3hRxVaxHL3EXplGeHT8fnoj+viai+TeSDdjMNwqU4MrngzrNKNLBHIl705uASpHUaRYQxUfWw/zgKeYlIbH+aGgE+4Q1vnh10Y35pATePRZgBIu+h2KsYBAtrP88LqW562OQ6T7VkfoAYwOjx9WV3/y5qonsStPhhzmJHDF22oBh5E5tZQxRcIlQF+5kHmXnFRUZtWshFnQATBh3yhOzJbh66CXn7aPj5Kl8TuuSN48zuI2lulVVqcv7GmTS0tWNpbxpzw==\r
 270 \r
 271 \r
 272 \r
 273 To provide known_hosts list to DFC, execute following steps:\r
 274 \r
 275 1. Create file called known_hosts with desired entries.\r
 276 \r
 277 2. Mount file using Kubernetes Config Map.\r
 278 \r
 279 .. code-block:: bash\r
 280 \r
 281   kubectl -n <ONAP NAMESPACE> create cm <config map name> --from-file <path to known_hosts file>\r
 282 \r
 283 e.g:\r
 284 \r
 285 .. code-block:: bash\r
 286 \r
 287   kubectl -n onap create cm onap-dcae-dfc-known-hosts --from-file /home/ubuntu/.ssh/known_hosts\r
 288 \r
 289 \r
 290 3. Mount newly created Config Map as Volume to DFC by editing DFC deployment. **DFC deployment contains 3 containers, pay attention to mount the file to the appropriate container.**\r
 291 \r
 292 .. code-block:: yaml\r
 293   \r
 294   ...\r
 295   kind: Deployment\r
 296   metadata:\r
 297   ...\r
 298   spec:\r
 299     ...\r
 300     template:\r
 301       ...\r
 302       spec:\r
 303         containers:\r
 304         - image: <DFC image>\r
 305           ...\r
 306           volumeMounts:\r
 307             ...\r
 308           - mountPath: /home/datafile/.ssh/\r
 309             name: onap-dcae-dfc-known-hosts\r
 310             ...\r
 311         volumes:\r
 312         ...\r
 313         - configMap:\r
 314             name: <config map name, same as in step 1, e.g. onap-dcae-dfc-known-hosts>\r
 315           name: onap-dcae-dfc-known-hosts\r
 316       ...\r
 317 \r
 318 Known_hosts file path can be controlled by Environment Variable *KNOWN_HOSTS_FILE_PATH*. Full (absolute) path has to be provided. Sample deployment with changed known_hosts file path can be seen below.\r
 319 \r
 320 .. code-block:: yaml\r
 321   \r
 322   ...\r
 323   kind: Deployment\r
 324   metadata:\r
 325   ...\r
 326   spec:\r
 327     ...\r
 328     template:\r
 329       ...\r
 330       spec:\r
 331         containers:\r
 332         - image: <DFC image>\r
 333           envs: \r
 334             - name: KNOWN_HOSTS_FILE_PATH\r
 335               value: /home/datafile/.ssh/new/path/<known_hosts file name, e.g. my_custom_keys>\r
 336           ...\r
 337           volumeMounts:\r
 338             ...\r
 339           - mountPath: /home/datafile/.ssh/new/path\r
 340             name: onap-dcae-dfc-known-hosts\r
 341             ...\r
 342         volumes:\r
 343         ...\r
 344         - configMap:\r
 345             name: <config map name, same as in step 1, e.g. onap-dcae-dfc-known-hosts>\r
 346           name: onap-dcae-dfc-known-hosts\r
 347       ...\r
 348 \r
 349 To change mounted known_hosts list, edit existing Config Map or delete and create it again. **The DFC container may refresh changes with a delay.** Pod, nor container restart is NOT required.\r
 350 \r
 351 To edit Config Map execute:\r
 352 \r
 353 .. code-block:: bash\r
 354 \r
 355   kubectl -n <ONAP NAMESPACE> edit cm <config map name>\r
 356 \r
 357 e.g:\r
 358 \r
 359 .. code-block:: bash\r
 360 \r
 361    kubectl -n onap edit cm onap-dcae-dfc-known-hosts\r
 362 \r
 363 To delete and create again Config Map execute: \r
 364 \r
 365 .. code-block:: bash\r
 366 \r
 367   kubectl -n <ONAP NAMESPACE> delete cm <config map name>\r
 368   kubectl -n <ONAP NAMESPACE> create cm <config map name> --from-file <path to known_hosts file>\r
 369 \r
 370 e.g:\r
 371 \r
 372 .. code-block:: bash\r
 373 \r
 374   kubectl -n onap delete cm onap-dcae-dfc-known-hosts\r
 375   kubectl -n onap create cm onap-dcae-dfc-known-hosts --from-file /home/ubuntu/.ssh/known_hosts\r
 376 \r
 377 \r
 378 To turn off StrictHostChecking, set below option to false. It could be changed in DCAE Config Binding Service (CBS).\r
 379 \r
 380 **WARNING: such operation is not recommended as it decreases DFC security and exposes DFC to MitM attacks.**\r
 381 \r
 382 .. code-block:: bash\r
 383 \r
 384   "sftp.security.strictHostKeyChecking": false\r
 385 \r
 386 \r
 387 Performance\r
 388 ^^^^^^^^^^^\r
 389 \r
 390 To see the performance of DFC, see "`Datafile Collector (DFC) performance baseline results`_".\r
 391 \r
 392 .. _Datafile Collector (DFC) performance baseline results: https://wiki.onap.org/display/DW/Datafile+Collector+%28DFC%29+performance+baseline+results\r