docs/usecases/pnf-simulator.rst

   1 .. This work is a derivative of https://wiki.onap.org/display/DW/PNF+Simulator+Day-N+config-assign+and+config-deploy+use+case
   2 .. This work is licensed under a Creative Commons Attribution 4.0
   3 .. International License. http://creativecommons.org/licenses/by/4.0
   4 .. Copyright (C) 2020 Deutsche Telekom AG.
   5
   6 PNF Simulator Day-N config-assign/deploy
   7 ========================================
   8
   9 Overview
  10 ~~~~~~~~~~
  11
  12 This use case shows in a very simple way how the day-n configuration is assigned and deployed to a PNF through CDS.
  13 A Netconf server (docker image `sysrepo/sysrepo-netopeer2`) is used for simulating the PNF.
  14
  15 This use case (POC) solely requires a running CDS and the PNF Simulator running on a VM (Ubuntu is used by the author).
  16 No other module of ONAP is needed.
  17
  18 There are different ways to run CDS and the PNF simulator. This guide will show
  19 different possible options to allow the greatest possible flexibility.
  20
  21 Run CDS (Blueprint Processor)
  22 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  23
  24 CDS can be run in Kubernetes (Minikube, Microk8s) or in an IDE. You can choose your favorite option.
  25 Just the blueprint processor of CDS is needed. If you have desktop access it is recommended to run CDS in an IDE since
  26 it is easy and enables debugging.
  27
  28 * CDS in Microk8s: https://wiki.onap.org/display/DW/Running+CDS+on+Microk8s (RDT link to be added)
  29 * CDS in Minikube: https://wiki.onap.org/display/DW/Running+CDS+in+minikube (RDT link to be added)
  30 * CDS in an IDE:  https://docs.onap.org/projects/onap-ccsdk-cds/en/latest/userguide/running-bp-processor-in-ide.html
  31
  32 Run PNF Simulator and install module
  33 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  34
  35 There are many different ways to run a Netconf Server to simulate the PNF, in this guide `sysrepo/sysrepo-netopeer2`
  36 docker image is commonly used. The easiest way is to run the out-of-the-box docker container without any
  37 other configuration, modules or scripts. In the ONAP community there are other workflows existing for running the
  38 PNF Simulator. These workflows are also using `sysrepo/sysrepo-netopeer2` docker image. These workflow are also linked
  39 here but they are not tested by the author of this guide.
  40
  41 .. tabs::
  42
  43    .. tab:: sysrepo/sysrepo-netopeer2 (latest)
  44
  45       Download and run docker container with ``docker run -d --name netopeer2 -p 830:830 -p 6513:6513 sysrepo/sysrepo-netopeer2:latest``
  46
  47       Enter the container with ``docker exec -it netopeer2 bin/bash``
  48
  49       Browse to the target location where all YANG modules exist: ``cd /etc/sysrepo/yang``
  50
  51       Create a simple mock YANG model for a packet generator (:file:`pg.yang`).
  52
  53       .. code-block:: sh
  54          :caption: **pg.yang**
  55
  56          module sample-plugin {
  57
  58             yang-version 1;
  59             namespace "urn:opendaylight:params:xml:ns:yang:sample-plugin";
  60             prefix "sample-plugin";
  61
  62             description
  63             "This YANG module defines the generic configuration and
  64             operational data for sample-plugin in VPP";
  65
  66             revision "2016-09-18" {
  67                description "Initial revision of sample-plugin model";
  68             }
  69
  70             container sample-plugin {
  71
  72                uses sample-plugin-params;
  73                description "Configuration data of sample-plugin in Honeycomb";
  74
  75                // READ
  76                // curl -u admin:admin http://localhost:8181/restconf/config/sample-plugin:sample-plugin
  77
  78                // WRITE
  79                // curl http://localhost:8181/restconf/operational/sample-plugin:sample-plugin
  80
  81             }
  82
  83             grouping sample-plugin-params {
  84                container pg-streams {
  85                   list pg-stream {
  86
  87                      key id;
  88                      leaf id {
  89                         type string;
  90                      }
  91
  92                      leaf is-enabled {
  93                         type boolean;
  94                      }
  95                   }
  96                }
  97             }
  98          }
  99
 100       Create the following sample XML data definition for the above model (:file:`pg-data.xml`).
 101       Later on this will initialise one single PG stream.
 102
 103       .. code-block:: sh
 104          :caption: **pg-data.xml**
 105
 106          <sample-plugin xmlns="urn:opendaylight:params:xml:ns:yang:sample-plugin">
 107             <pg-streams>
 108                <pg-stream>
 109                   <id>1</id>
 110                   <is-enabled>true</is-enabled>
 111                </pg-stream>
 112             </pg-streams>
 113          </sample-plugin>
 114
 115       Execute the following command within netopeer docker container to install the pg.yang model
 116
 117       .. code-block:: sh
 118
 119          sysrepoctl -v3 -i pg.yang
 120
 121       .. note::
 122          This command will just schedule the installation, it will be applied once the server is restarted.
 123
 124       Stop the container from outside with ``docker stop netopeer2`` and start it again with ``docker start netopeer2``
 125
 126       Enter the container like it's mentioned above with ``docker exec -it netopeer2 bin/bash``.
 127
 128       You can check all installed modules with ``sysrepoctl -l``.  `sample-plugin` module should appear with ``I`` flag.
 129
 130       Execute the following the commands to initialise the Yang model with one pg-stream record.
 131       We will be using CDS to perform the day-1 and day-2 configuration changes.
 132
 133       .. code-block:: sh
 134
 135          netopeer2-cli
 136          > connect --host localhost --login root
 137          # passwort is root
 138          > get --filter-xpath /sample-plugin:*
 139          # shows existing pg-stream records (empty)
 140          > edit-config --target running --config=/etc/sysrepo/yang/pg-data.xml
 141          # initialises Yang model with one pg-stream record
 142          > get --filter-xpath /sample-plugin:*
 143          # shows initialised pg-stream
 144
 145       If the output of the last command is like this, everything went successful:
 146
 147       .. code-block:: sh
 148
 149          DATA
 150          <sample-plugin xmlns="urn:opendaylight:params:xml:ns:yang:sample-plugin">
 151             <pg-streams>
 152                <pg-stream>
 153                   <id>1</id>
 154                   <is-enabled>true</is-enabled>
 155                </pg-stream>
 156             </pg-streams>
 157          </sample-plugin>
 158
 159
 160    .. tab:: sysrepo/sysrepo-netopeer2 (legacy)
 161
 162       Download and run docker container with ``docker run -d --name netopeer2 -p 830:830 -p 6513:6513 sysrepo/sysrepo-netopeer2:legacy``
 163
 164       Enter the container with ``docker exec -it netopeer2 bin/bash``
 165
 166       Browse to the target location where all YANG modules exist: ``cd /opt/dev/sysrepo/yang``
 167
 168       Create a simple mock YANG model for a packet generator (:file:`pg.yang`).
 169
 170       .. code-block:: sh
 171          :caption: **pg.yang**
 172
 173          module sample-plugin {
 174
 175             yang-version 1;
 176             namespace "urn:opendaylight:params:xml:ns:yang:sample-plugin";
 177             prefix "sample-plugin";
 178
 179             description
 180             "This YANG module defines the generic configuration and
 181             operational data for sample-plugin in VPP";
 182
 183             revision "2016-09-18" {
 184                description "Initial revision of sample-plugin model";
 185             }
 186
 187             container sample-plugin {
 188
 189                uses sample-plugin-params;
 190                description "Configuration data of sample-plugin in Honeycomb";
 191
 192                // READ
 193                // curl -u admin:admin http://localhost:8181/restconf/config/sample-plugin:sample-plugin
 194
 195                // WRITE
 196                // curl http://localhost:8181/restconf/operational/sample-plugin:sample-plugin
 197
 198             }
 199
 200             grouping sample-plugin-params {
 201                container pg-streams {
 202                   list pg-stream {
 203
 204                      key id;
 205                      leaf id {
 206                         type string;
 207                      }
 208
 209                      leaf is-enabled {
 210                         type boolean;
 211                      }
 212                   }
 213                }
 214             }
 215          }
 216
 217       Create the following sample XML data definition for the above model (:file:`pg-data.xml`).
 218       Later on this will initialise one single PG (packet-generator) stream.
 219
 220       .. code-block:: sh
 221          :caption: **pg-data.xml**
 222
 223          <sample-plugin xmlns="urn:opendaylight:params:xml:ns:yang:sample-plugin">
 224             <pg-streams>
 225                <pg-stream>
 226                   <id>1</id>
 227                   <is-enabled>true</is-enabled>
 228                </pg-stream>
 229             </pg-streams>
 230          </sample-plugin>
 231
 232       Execute the following command within netopeer docker container to install the pg.yang model
 233
 234       .. code-block:: sh
 235
 236          sysrepoctl -i -g pg.yang
 237
 238       You can check all installed modules with ``sysrepoctl -l``. `sample-plugin` module should appear with ``I`` flag.
 239
 240       In legacy version of `sysrepo/sysrepo-netopeer2` subscribers of a module are required, otherwise they are not
 241       running and configurations changes are not accepted, see https://github.com/sysrepo/sysrepo/issues/1395. There is
 242       an predefined application mock up which can be used for that. The usage is described
 243       here: https://asciinema.org/a/160247. You need to run the following
 244       commands to start the example application for subscribing to our sample-plugin YANG module.
 245
 246       .. code-block:: sh
 247
 248          cd /opt/dev/sysrepo/build/examples
 249          ./application_example sample-plugin
 250
 251       Following output should appear:
 252
 253       .. code-block:: sh
 254
 255          ========== READING STARTUP CONFIG sample-plugin: ==========
 256
 257          /sample-plugin:sample-plugin (container)
 258          /sample-plugin:sample-plugin/pg-streams (container)
 259
 260
 261          ========== STARTUP CONFIG sample-plugin APPLIED AS RUNNING ==========
 262
 263
 264       The terminal session needs to be kept open after application has started.
 265
 266       Open a new terminal and enter the container with ``docker exec -it netopeer2 bin/bash``.
 267       Execute the following commands in the container to initialise the Yang model with one pg-stream record.
 268       We will be using CDS to perform the day-1 configuration and day-2 configuration changes.
 269
 270       .. code-block:: sh
 271
 272          netopeer2-cli
 273          > connect --host localhost --login netconf
 274          # passwort is netconf
 275          > get --filter-xpath /sample-plugin:*
 276          # shows existing pg-stream records (empty)
 277          > edit-config --target running --config=/opt/dev/sysrepo/yang/pg-data.xml
 278          # initialises Yang model with one pg-stream record
 279          > get --filter-xpath /sample-plugin:*
 280          # shows initialised pg-stream
 281
 282       If the output of the last command is like this, everything went successful:
 283
 284       .. code-block:: sh
 285
 286          DATA
 287          <sample-plugin xmlns="urn:opendaylight:params:xml:ns:yang:sample-plugin">
 288             <pg-streams>
 289                <pg-stream>
 290                   <id>1</id>
 291                   <is-enabled>true</is-enabled>
 292                </pg-stream>
 293             </pg-streams>
 294          </sample-plugin>
 295
 296       You can also see that there are additional logs in the subscriber application after editing the configuration of our
 297       YANG module.
 298
 299    .. tab:: PNF simulator integration project
 300
 301       .. warning::
 302          This method of setting up the PNF simulator is not tested by the author of this guide
 303
 304       You can refer to `PnP PNF Simulator wiki page <https://wiki.onap.org/display/DW/PnP+PNF+Simulator>`_
 305       to clone the GIT repo and start the required docker containers. We are interested in the
 306       `sysrepo/sysrepo-netopeer2` docker container to load a simple YANG similar to vFW Packet Generator.
 307
 308       Start PNF simulator docker containers. You can consider changing the netopeer image verion to image:
 309       `sysrepo/sysrepo-netopeer2:iop` in docker-compose.yml file If you find any issues with the default image.
 310
 311       .. code-block:: sh
 312
 313          cd $HOME
 314
 315          git clone https://github.com/onap/integration.git
 316
 317          Start PNF simulator
 318
 319          cd ~/integration/test/mocks/pnfsimulator
 320
 321          ./simulator.sh start
 322
 323       Verify that you have netopeer docker container are up and running. It will be mapped to host port 830.
 324
 325       .. code-block:: sh
 326
 327          docker ps -a | grep netopeer
 328
 329
 330 Config-assign and config-deploy in CDS
 331 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 332
 333 In the following steps config-assignment is done and the config is deployed to the
 334 Netconf server through CDS. Example requests are in the following  Postman collection
 335 :download:`JSON <media/pnf-simulator.postman_collection.json>`. You can also use bash scripting to call the APIs.
 336
 337 .. note::
 338    The CBA for this PNF Demo gets loaded, enriched and saved in CDS through calling bootstrap. If not done before, call
 339    Bootstrap API
 340
 341 Password and username for API calls will be `ccsdkapps`.
 342
 343 **Config-Assign:**
 344
 345 The assumption is that we are using the same host to run PNF NETCONF simulator as well as CDS. You will need the
 346 IP Adress of the Netconf server container which can be found out with
 347 ``docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' netopeer2``. In the
 348 following example payloads we will use 172.17.0.2.
 349
 350 Call the `process` API (``http://{{host}}:{{port}}/api/v1/execution-service/process``) with POST method to
 351 create day-1 configuration. Use the following payload:
 352
 353 .. code-block:: JSON
 354
 355    {
 356       "actionIdentifiers": {
 357          "mode": "sync",
 358          "blueprintName": "pnf_netconf",
 359          "blueprintVersion": "1.0.0",
 360          "actionName": "config-assign"
 361       },
 362       "payload": {
 363          "config-assign-request": {
 364                "resolution-key": "day-1",
 365                "config-assign-properties": {
 366                   "stream-count": 5
 367                }
 368          }
 369       },
 370       "commonHeader": {
 371          "subRequestId": "143748f9-3cd5-4910-81c9-a4601ff2ea58",
 372          "requestId": "e5eb1f1e-3386-435d-b290-d49d8af8db4c",
 373          "originatorId": "SDNC_DG"
 374       }
 375    }
 376
 377 You can verify the day-1 NETCONF RPC payload looking into CDS DB. You should see the NETCONF RPC with 5
 378 streams (fw_udp_1 TO fw_udp_5). Connect to the DB and run the below statement. You should
 379 see the day-1 configuration as an output.
 380
 381 .. code-block:: sh
 382
 383    MariaDB [sdnctl]> select * from TEMPLATE_RESOLUTION where resolution_key='day-1' AND artifact_name='netconfrpc';
 384
 385    <rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1">
 386       <edit-config>
 387          <target>
 388             <running/>
 389          </target>
 390          <config>
 391             <sample-plugin xmlns="urn:opendaylight:params:xml:ns:yang:sample-plugin">
 392                <pg-streams>
 393                   <pg-stream>
 394                      <id>fw_udp_1</id>
 395                      <is-enabled>true</is-enabled>
 396                   </pg-stream>
 397                   <pg-stream>
 398                      <id>fw_udp_2</id>
 399                      <is-enabled>true</is-enabled>
 400                   </pg-stream>
 401                   <pg-stream>
 402                      <id>fw_udp_3</id>
 403                      <is-enabled>true</is-enabled>
 404                   </pg-stream>
 405                   <pg-stream>
 406                      <id>fw_udp_4</id>
 407                      <is-enabled>true</is-enabled>
 408                   </pg-stream>
 409                   <pg-stream>
 410                      <id>fw_udp_5</id>
 411                      <is-enabled>true</is-enabled>
 412                   </pg-stream>
 413                </pg-streams>
 414             </sample-plugin>
 415          </config>
 416       </edit-config>
 417    </rpc>
 418
 419 For creating day-2 configuration call the same endpoint and use the following payload:
 420
 421 .. code-block:: JSON
 422
 423    {
 424       "actionIdentifiers": {
 425          "mode": "sync",
 426          "blueprintName": "pnf_netconf",
 427          "blueprintVersion": "1.0.0",
 428          "actionName": "config-assign"
 429       },
 430       "payload": {
 431          "config-assign-request": {
 432                "resolution-key": "day-2",
 433                "config-assign-properties": {
 434                   "stream-count": 10
 435                }
 436          }
 437       },
 438       "commonHeader": {
 439          "subRequestId": "143748f9-3cd5-4910-81c9-a4601ff2ea58",
 440          "requestId": "e5eb1f1e-3386-435d-b290-d49d8af8db4c",
 441          "originatorId": "SDNC_DG"
 442       }
 443    }
 444
 445
 446 .. note::
 447    Until this step CDS did not interact with the PNF simulator or device. We just created the day-1 and day-2
 448    configurations and stored it in CDS database
 449
 450 **Config-Deploy:**
 451
 452 Now we will make the CDS REST API calls to push the day-1 and day-2 configuration changes to the PNF simulator.
 453 Call the same endpoint `process` with the following payload:
 454
 455 .. code-block::  JSON
 456
 457    {
 458       "actionIdentifiers": {
 459          "mode": "sync",
 460          "blueprintName": "pnf_netconf",
 461          "blueprintVersion": "1.0.0",
 462          "actionName": "config-deploy"
 463       },
 464       "payload": {
 465          "config-deploy-request": {
 466             "resolution-key": "day-1",
 467                "pnf-ipv4-address": "127.17.0.2",
 468                "netconf-username": "netconf",
 469                "netconf-password": "netconf"
 470          }
 471       },
 472       "commonHeader": {
 473          "subRequestId": "143748f9-3cd5-4910-81c9-a4601ff2ea58",
 474          "requestId": "e5eb1f1e-3386-435d-b290-d49d8af8db4c",
 475          "originatorId": "SDNC_DG"
 476       }
 477    }
 478
 479 Go back to PNF netopeer cli console like mentioned above and verify if you can see 5 streams fw_udp_1 to fw_udp_5 enabled. If the 5 streams
 480 appear in the output as follows, the day-1 configuration got successfully deployed and the use case is successfully done.
 481
 482 .. code-block:: sh
 483
 484    > get --filter-xpath /sample-plugin:*
 485    DATA
 486    <sample-plugin xmlns="urn:opendaylight:params:xml:ns:yang:sample-plugin">
 487       <pg-streams>
 488          <pg-stream>
 489             <id>1</id>
 490             <is-enabled>true</is-enabled>
 491          </pg-stream>
 492          <pg-stream>
 493             <id>fw_udp_1</id>
 494             <is-enabled>true</is-enabled>
 495          </pg-stream>
 496          <pg-stream>
 497             <id>fw_udp_2</id>
 498             <is-enabled>true</is-enabled>
 499          </pg-stream>
 500          <pg-stream>
 501             <id>fw_udp_3</id>
 502             <is-enabled>true</is-enabled>
 503          </pg-stream>
 504          <pg-stream>
 505             <id>fw_udp_4</id>
 506             <is-enabled>true</is-enabled>
 507          </pg-stream>
 508          <pg-stream>
 509             <id>fw_udp_5</id>
 510             <is-enabled>true</is-enabled>
 511          </pg-stream>
 512       </pg-streams>
 513    </sample-plugin>
 514    >
 515
 516 The same can be done for day-2 config (follow same steps just with day-2 in payload).
 517
 518 .. note::
 519    Through deployment we did not deploy the PNF, we just modified the PNF. The PNF could also be installed by CDS
 520    but this is not targeted in this guide.
 521
 522
 523 Creators of this guide
 524 ~~~~~~~~~~~~~~~~~~~~~~~
 525
 526 Deutsche Telekom AG
 527
 528 Jakob Krieg (Rocketchat @jakob.Krieg); Eli Halych (Rocketchat @elihalych)
 529
 530 This guide is a derivate from https://wiki.onap.org/display/DW/PNF+Simulator+Day-N+config-assign+and+config-deploy+use+case.