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