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