docs/developer-guide.rst

   1 .. _transportpce-dev-guide:
   2
   3 TransportPCE Developer Guide
   4 ============================
   5
   6 Overview
   7 --------
   8
   9 TransportPCE describes an application running on top of the OpenDaylight
  10 controller. Its primary function is to control an optical transport
  11 infrastructure using a non-proprietary South Bound Interface (SBI). It may be
  12 interconnected with Controllers of different layers (L2, L3 Controller…), a
  13 higher layer Controller and/or an Orchestrator through non-proprietary
  14 Application Programing Interfaces (APIs). Control includes the capability to
  15 configure the optical equipment, and to provision services according to a
  16 request coming from a higher layer controller and/or an orchestrator.
  17 This capability may rely on the controller only or it may be delegated to
  18 distributed (standardized) protocols.
  19
  20
  21 Architecture
  22 ------------
  23
  24 TransportPCE modular architecture is described on the next diagram. Each main
  25 function such as Topology management, Path Calculation Engine (PCE), Service
  26 handler, Renderer \_responsible for the path configuration through optical
  27 equipment\_ and Optical Line Management (OLM) is associated with a generic block
  28 relying on open models, each of them communicating through published APIs.
  29
  30
  31 .. figure:: ./images/tpce_architecture.jpg
  32    :alt: TransportPCE architecture
  33
  34    TransportPCE architecture
  35
  36 The current version of transportPCE is dedicated to the control of WDM transport
  37 infrastructure. OTN layer will be integrated in a later step. The WDM layer is
  38 built from colorless ROADMs and transponders.
  39
  40 The interest of using a controller to provision automatically services strongly
  41 relies on its ability to handle end to end optical services that spans through
  42 the different network domains, potentially equipped with equipment coming from
  43 different suppliers. Thus, interoperability in the optical layer is a key
  44 element to get the benefit of automated control.
  45
  46 Initial design of TransportPCE leverages Open ROADM Multi-Source-Agreement (MSA)
  47 which defines interoperability specifications, consisting of both Optical
  48 interoperability and Yang data models.
  49
  50 Module description
  51 ~~~~~~~~~~~~~~~~~~
  52
  53 ServiceHandler
  54 ^^^^^^^^^^^^^^
  55
  56 Service Handler handles request coming from a higher level controller or an orchestrator
  57 through the northbound API, as defined in the Open ROADM service model. Current
  58 implementation addresses the following rpcs: service-create, temp-service-create,
  59 service–delete, temp-service-delete, service-reroute, and service-restoration. It checks the
  60 request consistency and trigs path calculation sending rpcs to the PCE. If a valid path is
  61 returned by the PCE, path configuration is initiated relying on Renderer and OLM. At the
  62 confirmation of a successful service creation, the Service Handler updates the service-
  63 list/temp-service-list in the MD-SAL. For service deletion, the Service Handler relies on the
  64 Renderer and the OLM to delete connections and reset power levels associated with the
  65 service. The service-list is updated following a successful service deletion. In Neon SR0 is
  66 added the support for service from ROADM to ROADM, which brings additional flexibility and
  67 notably allows reserving resources when transponders are not in place at day one.
  68
  69 PCE
  70 ^^^^^^^^^^^^^^
  71
  72 The Path Computation Element (PCE) is the component responsible for path
  73 calculation. An interface allows the Renderer or external components such as an
  74 orchestrator to request a path computation and get a response from the PCE
  75 including the computed path(s) in case of success, or errors and indication of
  76 the reason for the failure in case the request cannot be satisfied. Additional
  77 parameters can be provided by the PCE in addition to the computed paths if
  78 requested by the client module. An interface to the Topology Management module
  79 allows keeping PCE aligned with the latest changes in the topology. Information
  80 about current and planned services is available in the MD-SAL data store.
  81
  82 Current implementation of PCE allows finding the shortest path, minimizing either the hop
  83 count (default) or the propagation delay. Wavelength is assigned considering a fixed grid of
  84 96 wavelengths. In Neon SR0, the PCE calculates the OSNR, on the base of incremental
  85 noise specifications provided in Open RAODM MSA. The support of unidirectional ports is
  86 also added. PCE handles the following constraints as hard constraints:
  87
  88 -   **Node exclusion**
  89 -   **SRLG exclusion**
  90 -   **Maximum latency**
  91
  92
  93 Topology Management
  94 ^^^^^^^^^^^^^^^^^^^^^^^^
  95
  96 Topology management module builds the Topology according to the Network model
  97 defined in OpenROADM. The topology is aligned with I2RS model. It includes
  98 several network layers:
  99
 100 -  **CLLI layer corresponds to the locations that host equipment**
 101 -  **Network layer corresponds to a first level of disaggregation where we
 102    separate Xponders (transponder, muxponders or switchponders) from ROADMs**
 103 -  **Topology layer introduces a second level of disaggregation where ROADMs
 104    Add/Drop modules ("SRGs") are separated from the degrees which includes line
 105    amplifiers and WSS that switch wavelengths from one to another degree**
 106
 107 OTN layer which includes OTN elements having or not the ability to switch OTN
 108 containers from client to line cards is not currently implemented.
 109
 110 Renderer
 111 ^^^^^^^^
 112
 113 The Renderer module, on request coming from the Service Handler through a service-
 114 implementation-request /service delete rpc, sets/deletes the path corresponding to a specific
 115 service between A and Z ends. The path description provided by the service-handler to the
 116 renderer is based on abstracted resources (nodes, links and termination-points), as provided
 117 by the PCE module. The renderer converts this path-description in a path topology based on
 118 device resources (circuit-packs, ports,…). The conversion from abstracted resources to
 119 device resources is performed relying on the portmapping module which maintains the
 120 connections between these different resource types. In Neon (SR0), portmapping modules
 121 has been enriched to support both openroadm 1.2.1 and 2.2 device models. The full support
 122 of openroadm 2.2 device models (both in the topology management and the rendering
 123 function) is planned at a later step (ORD2.2 full support is targeted for Neon SR1).
 124
 125 After the path is provided, the renderer first checks what are the existing interfaces on the
 126 ports of the different nodes that the path crosses. It then creates missing interfaces. After all
 127 needed interfaces have been created it sets the connections required in the nodes and
 128 notifies the Service Handler on the status of the path creation. Path is created in 2 steps
 129 (from A to Z and Z to A). In case the path between A and Z could not be fully created, a
 130 rollback function is called to set the equipment on the path back to their initial configuration
 131 (as they were before invoking the Renderer).
 132
 133 OLM
 134 ^^^^^^^^
 135
 136 Optical Line Management module implements two main features: it is responsible
 137 for setting up the optical power levels on the different interfaces, and is in
 138 charge of adjusting these settings across the life of the optical
 139 infrastructure.
 140
 141 After the different connections have been established in the ROADMS, between 2
 142 Degrees for an express path, or between a SRG and a Degree for an Add or Drop
 143 path; meaning the devices have set WSS and all other required elements to
 144 provide path continuity, power setting are provided as attributes of these
 145 connections. This allows the device to set all complementary elements such as
 146 VOAs, to guaranty that the signal is launched at a correct power level
 147 (in accordance to the specifications) in the fiber span. This also applies
 148 to X-Ponders, as their output power must comply with the specifications defined
 149 for the Add/Drop ports (SRG) of the ROADM. OLM has the responsibility of
 150 calculating the right power settings, sending it to the device, and check the
 151 PM retrieved from the device to verify that the setting was correctly applied
 152 and the configuration was successfully completed.
 153
 154 Key APIs and Interfaces
 155 -----------------------
 156
 157 External API
 158 ~~~~~~~~~~~~
 159
 160 North API, interconnecting the Service Handler to higher level applications
 161 relies on the Service Model defined in the MSA. The Renderer and the OLM are
 162 developed to allow configuring Open ROADM devices through a southbound
 163 Netconf/Yang interface and rely on the MSA’s device model.
 164
 165 ServiceHandler Service
 166 ^^^^^^^^^^^^^^^^^^^^^^
 167
 168 -  RPC call
 169
 170    -  service-create (given service-name, service-aend, service-zend)
 171
 172    -  service-delete (given service-name)
 173
 174    -  service-reroute (given service-name, service-aend, service-zend)
 175
 176    -  service-restoration (given service-name, service-aend, service-zend)
 177
 178    -  temp-service-create (given common-id, service-aend, service-zend)
 179
 180    -  temp-service-delete (given common-id)
 181
 182 -  Data structure
 183
 184    -  service list : made of services
 185    -  temp-service list : made of temporary services
 186    -  service : composed of service-name, topology wich describes the detailed path (list of used resources)
 187
 188 -  Notification
 189
 190    - service-rpc-result : result of service RPC
 191    - service-notification : service has been added, modified or removed
 192
 193 Netconf Service
 194 ^^^^^^^^^^^^^^^
 195
 196 -  RPC call
 197
 198    -  connect-device : PUT
 199    -  disconnect-device : DELETE
 200    -  check-connected-device : GET
 201
 202 -  Data Structure
 203
 204    -  node list : composed of netconf nodes in topology-netconf
 205
 206
 207 Internal APIs
 208 ~~~~~~~~~~~~~
 209
 210 Internal APIs define REST APIs to interconnect TransportPCE modules :
 211
 212 -   Service Handler to PCE
 213 -   PCE to Topology Management
 214 -   Service Handler to Renderer
 215 -   Renderer to OLM
 216
 217 Pce Service
 218 ^^^^^^^^^^^
 219
 220 -  RPC call
 221
 222    -  path-computation-request (given service-name, service-aend, service-zend)
 223
 224    -  cancel-resource-reserve (given service-name)
 225
 226 -  Notification
 227
 228    - service-path-rpc-result : result of service RPC
 229
 230 Renderer Service
 231 ^^^^^^^^^^^^^^^^
 232
 233 -  RPC call
 234
 235    -  service-implementation-request (given service-name, service-aend, service-zend)
 236
 237    -  service-delete (given service-name)
 238
 239 -  Data structure
 240
 241    -  service path list : composed of service paths
 242    -  service path : composed of service-name, path description giving the list of abstracted elements (nodes, tps, links)
 243
 244 -  Notification
 245
 246    - service-path-rpc-result : result of service RPC
 247
 248 Topology Management Service
 249 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 250
 251 -  Data structure
 252
 253    -  network list : composed of networks(openroadm-topology, netconf-topology)
 254    -  node list : composed of node-id
 255    -  link list : composed of link-id
 256    -  node : composed of roadm, xponder
 257       link : composed of links of different types (roadm-to-roadm, express, add-drop ...)
 258
 259 OLM Service
 260 ^^^^^^^^^^^
 261
 262 -  RPC call
 263
 264    -  get-pm (given node-id)
 265
 266    -  service-power-setup
 267
 268    -  service-power-turndown
 269
 270    -  service-power-reset
 271
 272    -  calculate-spanloss-base
 273
 274    -  calculate-spanloss-current
 275
 276 odl-transportpce-stubmodels
 277 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 278
 279    -  This feature provides function to be able to stub some of TransportPCE modules, pce and
 280       renderer (Stubpce and Stubrenderer).
 281       Stubs are used for development purposes and can be used for some of the functionnal tests.
 282
 283
 284 Running transportPCE project
 285 ----------------------------
 286
 287 To use transportPCE controller, the first step is to connect the controller to optical nodes
 288 through the NETCONF connector.
 289
 290 .. note::
 291
 292     In the current version, only optical equipment compliant with open ROADM datamodels are managed
 293     by transportPCE.
 294
 295
 296 Connecting nodes
 297 ~~~~~~~~~~~~~~~~
 298
 299 To connect a node, use the following JSON RPC
 300
 301 **REST API** : *POST /restconf/config/network-topology:network-topology/topology/topology-netconf/node/<node-id>*
 302
 303 **Sample JSON Data**
 304
 305 .. code:: json
 306
 307     {
 308         "node": [
 309             {
 310                 "node-id": "<node-id>",
 311                 "netconf-node-topology:tcp-only": "false",
 312                 "netconf-node-topology:reconnect-on-changed-schema": "false",
 313                 "netconf-node-topology:host": "<node-ip-address>",
 314                 "netconf-node-topology:default-request-timeout-millis": "120000",
 315                 "netconf-node-topology:max-connection-attempts": "0",
 316                 "netconf-node-topology:sleep-factor": "1.5",
 317                 "netconf-node-topology:actor-response-wait-time": "5",
 318                 "netconf-node-topology:concurrent-rpc-limit": "0",
 319                 "netconf-node-topology:between-attempts-timeout-millis": "2000",
 320                 "netconf-node-topology:port": "<netconf-port>",
 321                 "netconf-node-topology:connection-timeout-millis": "20000",
 322                 "netconf-node-topology:username": "<node-username>",
 323                 "netconf-node-topology:password": "<node-password>",
 324                 "netconf-node-topology:keepalive-delay": "300"
 325             }
 326         ]
 327     }
 328
 329
 330 Then check that the netconf session has been correctly established between the controller and the
 331 node. the status of **netconf-node-topology:connection-status** must be **connected**
 332
 333 **REST API** : *GET /restconf/operational/network-topology:network-topology/topology/topology-netconf/node/<node-id>*
 334
 335
 336 Node configuration discovery
 337 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 338
 339 Once the controller is connected to the node, transportPCE application automatically launchs a
 340 discovery of the node configuration datastore and creates **Logical Connection Points** to any
 341 physical ports related to transmission. All *circuit-packs* inside the node configuration are
 342 analyzed.
 343
 344 Use the following JSON RPC to check that function internally named *portMapping*.
 345
 346 **REST API** : *GET /restconf/config/portmapping:network*
 347
 348 .. note::
 349
 350     in Neon SR0, the support of openroadm 2.2 device model is added. Thus 2.2 nodes can be
 351     discovered and added to the portmapping node list. However, full topology management
 352     support (and notably link discovery) is not provided for 2.2 nodes. The support for link
 353     discovery and full topology management with 1.2.1 and 2.2 nodes will be added in a next release.
 354
 355 .. note::
 356
 357     In ``org-openroadm-device.yang``, two types of optical nodes can be managed:
 358         * rdm: ROADM device (optical switch)
 359         * xpdr: Xponder device (device that converts client to optical channel interface)
 360
 361 Depending on the kind of open ROADM device connected, different kind of *Logical Connection Points*
 362 should appear, if the node configuration is not empty:
 363
 364 -  DEG<degree-number>-TTP-<port-direction>: created on the line port of a degree on a rdm equipment
 365 -  SRG<srg-number>-PP<port-number>: created on the client port of a srg on a rdm equipment
 366 -  XPDR<number>-CLIENT<port-number>: created on the client port of a xpdr equipment
 367 -  XPDR<number>-NETWORK<port-number>: created on the line port of a xpdr equipment
 368
 369     For further details on openROADM device models, see `openROADM MSA white paper <https://0201.nccdn.net/1_2/000/000/134/c50/Open-ROADM-MSA-release-2-Device-White-paper-v1-1.pdf>`__.
 370
 371 Optical Network topology
 372 ~~~~~~~~~~~~~~~~~~~~~~~~
 373
 374 Before creating an optical connectivity service, your topology must contain at least two xpdr
 375 devices connected to two different rdm devices. Normally, the *openroadm-topology* is automatically
 376 created by transportPCE. Nevertheless, depending on the configuration inside optical nodes, this
 377 topology can be partial. Check that link of type *ROADMtoROADM* exists between two adjacent rdm
 378 nodes.
 379
 380 **REST API** : *GET /restconf/config/ietf-network:network/openroadm-topology*
 381
 382 If it is not the case, you need to manually complement the topology with *ROADMtoROADM* link using
 383 the following REST RPC:
 384
 385
 386 **REST API** : *POST /restconf/operations/networkutils:init-roadm-nodes*
 387
 388 **Sample JSON Data**
 389
 390 .. code:: json
 391
 392     {
 393       "networkutils:input": {
 394         "networkutils:rdm-a-node": "<node-id-A>",
 395         "networkutils:deg-a-num": "<degree-A-number>",
 396         "networkutils:termination-point-a": "<Logical-Connection-Point>",
 397         "networkutils:rdm-z-node": "<node-id-Z>",
 398         "networkutils:deg-z-num": "<degree-Z-number>",
 399         "networkutils:termination-point-z": "<Logical-Connection-Point>"
 400       }
 401     }
 402
 403 *<Logical-Connection-Point> comes from the portMapping function*.
 404
 405 Unidirectional links between xpdr and rdm nodes must be created manually. To that end use the two
 406 following REST RPCs:
 407
 408 From xpdr to rdm:
 409 ^^^^^^^^^^^^^^^^^
 410
 411 **REST API** : *POST /restconf/operations/networkutils:init-xpdr-rdm-links*
 412
 413 **Sample JSON Data**
 414
 415 .. code:: json
 416
 417     {
 418       "networkutils:input": {
 419         "networkutils:links-input": {
 420           "networkutils:xpdr-node": "<xpdr-node-id>",
 421           "networkutils:xpdr-num": "1",
 422           "networkutils:network-num": "<xpdr-network-port-number>",
 423           "networkutils:rdm-node": "<rdm-node-id>",
 424           "networkutils:srg-num": "<srg-number>",
 425           "networkutils:termination-point-num": "<Logical-Connection-Point>"
 426         }
 427       }
 428     }
 429
 430 From rdm to xpdr:
 431 ^^^^^^^^^^^^^^^^^
 432
 433 **REST API** : *POST /restconf/operations/networkutils:init-rdm-xpdr-links*
 434
 435 **Sample JSON Data**
 436
 437 .. code:: json
 438
 439     {
 440       "networkutils:input": {
 441         "networkutils:links-input": {
 442           "networkutils:xpdr-node": "<xpdr-node-id>",
 443           "networkutils:xpdr-num": "1",
 444           "networkutils:network-num": "<xpdr-network-port-number>",
 445           "networkutils:rdm-node": "<rdm-node-id>",
 446           "networkutils:srg-num": "<srg-number>",
 447           "networkutils:termination-point-num": "<Logical-Connection-Point>"
 448         }
 449       }
 450     }
 451
 452
 453 Creating a service
 454 ~~~~~~~~~~~~~~~~~~
 455
 456 Use the following REST RPC to invoke *service handler* module in order to create a bidirectional
 457 end-to-end optical connectivity service between two xpdr over an optical network composed of rdm
 458 nodes.
 459
 460 **REST API** : *POST /restconf/operations/org-openroadm-service:service-create*
 461
 462 **Sample JSON Data**
 463
 464 .. code:: json
 465
 466     {
 467         "input": {
 468             "sdnc-request-header": {
 469                 "request-id": "request-1",
 470                 "rpc-action": "service-create",
 471                 "request-system-id": "appname"
 472             },
 473             "service-name": "test1",
 474             "common-id": "commonId",
 475             "connection-type": "service",
 476             "service-a-end": {
 477                 "service-rate": "100",
 478                 "node-id": "<xpdr-node-id>",
 479                 "service-format": "Ethernet",
 480                 "clli": "<ccli-name>",
 481                 "tx-direction": {
 482                     "port": {
 483                         "port-device-name": "<xpdr-client-port>",
 484                         "port-type": "fixed",
 485                         "port-name": "<xpdr-client-port-number>",
 486                         "port-rack": "000000.00",
 487                         "port-shelf": "Chassis#1"
 488                     },
 489                     "lgx": {
 490                         "lgx-device-name": "Some lgx-device-name",
 491                         "lgx-port-name": "Some lgx-port-name",
 492                         "lgx-port-rack": "000000.00",
 493                         "lgx-port-shelf": "00"
 494                     }
 495                 },
 496                 "rx-direction": {
 497                     "port": {
 498                         "port-device-name": "<xpdr-client-port>",
 499                         "port-type": "fixed",
 500                         "port-name": "<xpdr-client-port-number>",
 501                         "port-rack": "000000.00",
 502                         "port-shelf": "Chassis#1"
 503                     },
 504                     "lgx": {
 505                         "lgx-device-name": "Some lgx-device-name",
 506                         "lgx-port-name": "Some lgx-port-name",
 507                         "lgx-port-rack": "000000.00",
 508                         "lgx-port-shelf": "00"
 509                     }
 510                 },
 511                 "optic-type": "gray"
 512             },
 513             "service-z-end": {
 514                 "service-rate": "100",
 515                 "node-id": "<xpdr-node-id>",
 516                 "service-format": "Ethernet",
 517                 "clli": "<ccli-name>",
 518                 "tx-direction": {
 519                     "port": {
 520                         "port-device-name": "<xpdr-client-port>",
 521                         "port-type": "fixed",
 522                         "port-name": "<xpdr-client-port-number>",
 523                         "port-rack": "000000.00",
 524                         "port-shelf": "Chassis#1"
 525                     },
 526                     "lgx": {
 527                         "lgx-device-name": "Some lgx-device-name",
 528                         "lgx-port-name": "Some lgx-port-name",
 529                         "lgx-port-rack": "000000.00",
 530                         "lgx-port-shelf": "00"
 531                     }
 532                 },
 533                 "rx-direction": {
 534                     "port": {
 535                         "port-device-name": "<xpdr-client-port>",
 536                         "port-type": "fixed",
 537                         "port-name": "<xpdr-client-port-number>",
 538                         "port-rack": "000000.00",
 539                         "port-shelf": "Chassis#1"
 540                     },
 541                     "lgx": {
 542                         "lgx-device-name": "Some lgx-device-name",
 543                         "lgx-port-name": "Some lgx-port-name",
 544                         "lgx-port-rack": "000000.00",
 545                         "lgx-port-shelf": "00"
 546                     }
 547                 },
 548                 "optic-type": "gray"
 549             },
 550             "due-date": "yyyy-mm-ddT00:00:01Z",
 551             "operator-contact": "some-contact-info"
 552         }
 553     }
 554
 555 Most important parameters for this REST RPC are the identification of the two physical client ports
 556 on xpdr nodes.This RPC invokes the *PCE* module to compute a path over the *openroadm-topology* and
 557 then invokes *renderer* and *OLM* to implement the end-to-end path into the devices.
 558
 559
 560 Deleting a service
 561 ~~~~~~~~~~~~~~~~~~
 562
 563 Use the following REST RPC to invoke *service handler* module in order to delete a given optical
 564 connectivity service.
 565
 566 **REST API** : *POST /restconf/operations/org-openroadm-service:service-delete*
 567
 568 **Sample JSON Data**
 569
 570 .. code:: json
 571
 572     {
 573         "input": {
 574             "sdnc-request-header": {
 575                 "request-id": "request-1",
 576                 "rpc-action": "service-delete",
 577                 "request-system-id": "appname",
 578                 "notification-url": "http://localhost:8585/NotificationServer/notify"
 579             },
 580             "service-delete-req-info": {
 581                 "service-name": "test1",
 582                 "tail-retention": "no"
 583             }
 584         }
 585     }
 586
 587 Most important parameters for this REST RPC is the *service-name*.
 588
 589
 590 Help
 591 ----
 592
 593 -  `TransportPCE Wiki <https://wiki.lfnetworking.org/display/ODL/Projects>`__
 594
 595 -  TransportPCE Mailing List
 596    (`developer <https://lists.opendaylight.org/mailman/listinfo/transportpce-dev>`__)