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/TransportPCE-Diagramm-Magnesium.jpg
  32    :alt: TransportPCE architecture
  33
  34    TransportPCE architecture
  35
  36 Fluorine, Neon and Sodium releases of transportPCE are dedicated to the control
  37 of WDM transport infrastructure. The WDM layer is built from colorless ROADMs
  38 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 OpenROADM Multi-Source-Agreement (MSA)
  47 which defines interoperability specifications, consisting of both Optical
  48 interoperability and Yang data models.
  49
  50 Experimental support of OTN layer is introduced in Magnesium release of
  51 OpenDaylight. By experimental, we mean not all features can be accessed through
  52 northbound API based on RESTCONF encoded OpenROADM Service model. In the meanwhile,
  53 "east/west" APIs shall be used to trigger a path computation in the PCE (using
  54 path-computation-request RPC) and to create services (using otn-service-path RPC).
  55 OTN support will be improved in the following magnesium releases.
  56
  57
  58
  59 Module description
  60 ~~~~~~~~~~~~~~~~~~
  61
  62 ServiceHandler
  63 ^^^^^^^^^^^^^^
  64
  65 Service Handler handles request coming from a higher level controller or an orchestrator
  66 through the northbound API, as defined in the Open ROADM service model. Current
  67 implementation addresses the following rpcs: service-create, temp-service-create,
  68 service–delete, temp-service-delete, service-reroute, and service-restoration. It checks the
  69 request consistency and trigs path calculation sending rpcs to the PCE. If a valid path is
  70 returned by the PCE, path configuration is initiated relying on Renderer and OLM. At the
  71 confirmation of a successful service creation, the Service Handler updates the service-
  72 list/temp-service-list in the MD-SAL. For service deletion, the Service Handler relies on the
  73 Renderer and the OLM to delete connections and reset power levels associated with the
  74 service. The service-list is updated following a successful service deletion. In Neon SR0 is
  75 added the support for service from ROADM to ROADM, which brings additional flexibility and
  76 notably allows reserving resources when transponders are not in place at day one.
  77 The full support of OTN services, including OTU, HO-ODU and LO-ODU will be introduced
  78 in next release of Magnesium.
  79
  80 PCE
  81 ^^^
  82
  83 The Path Computation Element (PCE) is the component responsible for path
  84 calculation. An interface allows the Service Handler or external components such as an
  85 orchestrator to request a path computation and get a response from the PCE
  86 including the computed path(s) in case of success, or errors and indication of
  87 the reason for the failure in case the request cannot be satisfied. Additional
  88 parameters can be provided by the PCE in addition to the computed paths if
  89 requested by the client module. An interface to the Topology Management module
  90 allows keeping PCE aligned with the latest changes in the topology. Information
  91 about current and planned services is available in the MD-SAL data store.
  92
  93 Current implementation of PCE allows finding the shortest path, minimizing either the hop
  94 count (default) or the propagation delay. Wavelength is assigned considering a fixed grid of
  95 96 wavelengths. In Neon SR0, the PCE calculates the OSNR, on the base of incremental
  96 noise specifications provided in Open ROADM MSA. The support of unidirectional ports is
  97 also added. PCE handles the following constraints as hard constraints:
  98
  99 -   **Node exclusion**
 100 -   **SRLG exclusion**
 101 -   **Maximum latency**
 102
 103 In Magnesium SR0, the interconnection of the PCE with GNPY (Gaussian Noise Python), an
 104 open-source library developed in the scope of the Telecom Infra Project for building route
 105 planning and optimizing performance in optical mesh networks, is fully supported.
 106
 107 If the OSNR calculated by the PCE is too close to the limit defined in OpenROADM
 108 specifications, the PCE forwards through a REST interface to GNPY external tool the topology
 109 and the pre-computed path translated in routing constraints. GNPy calculates a set of Quality of
 110 Transmission metrics for this path using its own library which includes models for OpenROADM.
 111 The result is sent back to the PCE. If the path is validated, the PCE sends back a response to
 112 the service handler. In case of invalidation of the path by GNPY, the PCE sends a new request to
 113 GNPY, including only the constraints expressed in the path-computation-request initiated by the
 114 Service Handler. GNPy then tries to calculate a path based on these relaxed constraints. The result
 115 of the path computation is provided to the PCE which translates the path according to the topology
 116 handled in transportPCE and forwards the results to the Service Handler.
 117
 118 GNPy relies on SNR and takes into account the linear and non-linear impairments
 119 to check feasibility. In the related tests, GNPy module runs externally in a
 120 docker and the communication with T-PCE is ensured via HTTPs.
 121
 122 Topology Management
 123 ^^^^^^^^^^^^^^^^^^^
 124
 125 Topology management module builds the Topology according to the Network model
 126 defined in OpenROADM. The topology is aligned with IETF I2RS RFC8345 model.
 127 It includes several network layers:
 128
 129 -  **CLLI layer corresponds to the locations that host equipment**
 130 -  **Network layer corresponds to a first level of disaggregation where we
 131    separate Xponders (transponder, muxponders or switchponders) from ROADMs**
 132 -  **Topology layer introduces a second level of disaggregation where ROADMs
 133    Add/Drop modules ("SRGs") are separated from the degrees which includes line
 134    amplifiers and WSS that switch wavelengths from one to another degree**
 135 -  **OTN layer introduced in Magnesium includes transponders as well as switch-ponders and
 136    mux-ponders having the ability to switch OTN containers from client to line cards. SR0 release
 137    includes creation of the switching pool (used to model cross-connect matrices),
 138    tributary-ports and tributary-slots at the initial connection of NETCONF devices.
 139    However, the population of OTN links, and the adjustment of the tributary ports/slots
 140    pull occupancy when OTN services are created will be handled in later Magnesium release.**
 141
 142
 143 Renderer
 144 ^^^^^^^^
 145
 146 The Renderer module, on request coming from the Service Handler through a service-
 147 implementation-request /service delete rpc, sets/deletes the path corresponding to a specific
 148 service between A and Z ends. The path description provided by the service-handler to the
 149 renderer is based on abstracted resources (nodes, links and termination-points), as provided
 150 by the PCE module. The renderer converts this path-description in a path topology based on
 151 device resources (circuit-packs, ports,…).
 152
 153 The conversion from abstracted resources to device resources is performed relying on the
 154 portmapping module which maintains the connections between these different resource types.
 155 Portmapping module also allows to keep the topology independant from the devices releases.
 156 In Neon (SR0), portmapping module has been enriched to support both openroadm 1.2.1 and 2.2.1
 157 device models. The full support of openroadm 2.2.1 device models (both in the topology management
 158 and the rendering function) has been added in Neon SR1. In Magnesium, portmapping is enriched with
 159 the supported-interface-capability, OTN supporting-interfaces, and switching-pools (reflecting
 160 cross-connection capabilities of OTN switch-ponders).
 161
 162 After the path is provided, the renderer first checks what are the existing interfaces on the
 163 ports of the different nodes that the path crosses. It then creates missing interfaces. After all
 164 needed interfaces have been created it sets the connections required in the nodes and
 165 notifies the Service Handler on the status of the path creation. Path is created in 2 steps
 166 (from A to Z and Z to A). In case the path between A and Z could not be fully created, a
 167 rollback function is called to set the equipment on the path back to their initial configuration
 168 (as they were before invoking the Renderer).
 169
 170 Magnesium brings the support of OTN services. SR0 supports the creation of OTU4, ODU4, ODU2/ODU2e
 171 and ODU0 interfaces. The creation of these low-order otn interfaces must be triggered through
 172 otn-service-path RPC. Full support (service-implementation-request /service delete rpc, topology
 173 alignement after the service has been created) will be provided in later releases of Magnesium.
 174
 175
 176 OLM
 177 ^^^
 178
 179 Optical Line Management module implements two main features: it is responsible
 180 for setting up the optical power levels on the different interfaces, and is in
 181 charge of adjusting these settings across the life of the optical
 182 infrastructure.
 183
 184 After the different connections have been established in the ROADMS, between 2
 185 Degrees for an express path, or between a SRG and a Degree for an Add or Drop
 186 path; meaning the devices have set WSS and all other required elements to
 187 provide path continuity, power setting are provided as attributes of these
 188 connections. This allows the device to set all complementary elements such as
 189 VOAs, to guaranty that the signal is launched at a correct power level
 190 (in accordance to the specifications) in the fiber span. This also applies
 191 to X-Ponders, as their output power must comply with the specifications defined
 192 for the Add/Drop ports (SRG) of the ROADM. OLM has the responsibility of
 193 calculating the right power settings, sending it to the device, and check the
 194 PM retrieved from the device to verify that the setting was correctly applied
 195 and the configuration was successfully completed.
 196
 197 Key APIs and Interfaces
 198 -----------------------
 199
 200 External API
 201 ~~~~~~~~~~~~
 202
 203 North API, interconnecting the Service Handler to higher level applications
 204 relies on the Service Model defined in the MSA. The Renderer and the OLM are
 205 developed to allow configuring Open ROADM devices through a southbound
 206 Netconf/Yang interface and rely on the MSA’s device model.
 207
 208 ServiceHandler Service
 209 ^^^^^^^^^^^^^^^^^^^^^^
 210
 211 -  RPC call
 212
 213    -  service-create (given service-name, service-aend, service-zend)
 214
 215    -  service-delete (given service-name)
 216
 217    -  service-reroute (given service-name, service-aend, service-zend)
 218
 219    -  service-restoration (given service-name, service-aend, service-zend)
 220
 221    -  temp-service-create (given common-id, service-aend, service-zend)
 222
 223    -  temp-service-delete (given common-id)
 224
 225 -  Data structure
 226
 227    -  service list : made of services
 228    -  temp-service list : made of temporary services
 229    -  service : composed of service-name, topology wich describes the detailed path (list of used resources)
 230
 231 -  Notification
 232
 233    - service-rpc-result : result of service RPC
 234    - service-notification : service has been added, modified or removed
 235
 236 Netconf Service
 237 ^^^^^^^^^^^^^^^
 238
 239 -  RPC call
 240
 241    -  connect-device : PUT
 242    -  disconnect-device : DELETE
 243    -  check-connected-device : GET
 244
 245 -  Data Structure
 246
 247    -  node list : composed of netconf nodes in topology-netconf
 248
 249 Internal APIs
 250 ~~~~~~~~~~~~~
 251
 252 Internal APIs define REST APIs to interconnect TransportPCE modules :
 253
 254 -   Service Handler to PCE
 255 -   PCE to Topology Management
 256 -   Service Handler to Renderer
 257 -   Renderer to OLM
 258
 259 Pce Service
 260 ^^^^^^^^^^^
 261
 262 -  RPC call
 263
 264    -  path-computation-request (given service-name, service-aend, service-zend)
 265
 266    -  cancel-resource-reserve (given service-name)
 267
 268 -  Notification
 269
 270    - service-path-rpc-result : result of service RPC
 271
 272 Renderer Service
 273 ^^^^^^^^^^^^^^^^
 274
 275 -  RPC call
 276
 277    -  service-implementation-request (given service-name, service-aend, service-zend)
 278
 279    -  service-delete (given service-name)
 280
 281 -  Data structure
 282
 283    -  service path list : composed of service paths
 284    -  service path : composed of service-name, path description giving the list of abstracted elements (nodes, tps, links)
 285
 286 -  Notification
 287
 288    - service-path-rpc-result : result of service RPC
 289
 290 Device Renderer
 291 ^^^^^^^^^^^^^^^
 292
 293 -  RPC call
 294
 295    -  service-path used in SR0 as an intermediate solution to address directly the renderer
 296       from a REST NBI to create OCH-OTU4-ODU4 interfaces on network port of otn devices.
 297
 298    -  otn-service-path used in SR0 as an intermediate solution to address directly the renderer
 299       from a REST NBI for otn-service creation. Otn service-creation through
 300       service-implementation-request call from the Service Handler will be supported in later
 301       Magnesium releases
 302
 303 Topology Management Service
 304 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 305
 306 -  Data structure
 307
 308    -  network list : composed of networks(openroadm-topology, netconf-topology)
 309    -  node list : composed of nodes identified by their node-id
 310    -  link list : composed of links identified by their link-id
 311    -  node : composed of roadm, xponder
 312       link : composed of links of different types (roadm-to-roadm, express, add-drop ...)
 313
 314 OLM Service
 315 ^^^^^^^^^^^
 316
 317 -  RPC call
 318
 319    -  get-pm (given node-id)
 320
 321    -  service-power-setup
 322
 323    -  service-power-turndown
 324
 325    -  service-power-reset
 326
 327    -  calculate-spanloss-base
 328
 329    -  calculate-spanloss-current
 330
 331 odl-transportpce-stubmodels
 332 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 333
 334    -  This feature provides function to be able to stub some of TransportPCE modules, pce and
 335       renderer (Stubpce and Stubrenderer).
 336       Stubs are used for development purposes and can be used for some of the functionnal tests.
 337
 338 Interfaces to external software
 339 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 340
 341 It defines the interfaces implemented to interconnect TransportPCE modules with other software in
 342 order to perform specific tasks
 343
 344 GNPy interface
 345 ^^^^^^^^^^^^^^
 346
 347 -  Request structure
 348
 349    -  topology : composed of list of elements and connections
 350    -  service : source, destination, explicit-route-objects, path-constraints
 351
 352 -  Response structure
 353
 354    -  path-properties/path-metric : OSNR-0.1nm, OSNR-bandwidth, SNR-0.1nm, SNR-bandwidth,
 355    -  path-properties/path-route-objects : composed of path elements
 356
 357
 358 Running transportPCE project
 359 ----------------------------
 360
 361 To use transportPCE controller, the first step is to connect the controller to optical nodes
 362 through the NETCONF connector.
 363
 364 .. note::
 365
 366     In the current version, only optical equipment compliant with open ROADM datamodels are managed
 367     by transportPCE.
 368
 369
 370 Connecting nodes
 371 ~~~~~~~~~~~~~~~~
 372
 373 To connect a node, use the following JSON RPC
 374
 375 **REST API** : *POST /restconf/config/network-topology:network-topology/topology/topology-netconf/node/<node-id>*
 376
 377 **Sample JSON Data**
 378
 379 .. code:: json
 380
 381     {
 382         "node": [
 383             {
 384                 "node-id": "<node-id>",
 385                 "netconf-node-topology:tcp-only": "false",
 386                 "netconf-node-topology:reconnect-on-changed-schema": "false",
 387                 "netconf-node-topology:host": "<node-ip-address>",
 388                 "netconf-node-topology:default-request-timeout-millis": "120000",
 389                 "netconf-node-topology:max-connection-attempts": "0",
 390                 "netconf-node-topology:sleep-factor": "1.5",
 391                 "netconf-node-topology:actor-response-wait-time": "5",
 392                 "netconf-node-topology:concurrent-rpc-limit": "0",
 393                 "netconf-node-topology:between-attempts-timeout-millis": "2000",
 394                 "netconf-node-topology:port": "<netconf-port>",
 395                 "netconf-node-topology:connection-timeout-millis": "20000",
 396                 "netconf-node-topology:username": "<node-username>",
 397                 "netconf-node-topology:password": "<node-password>",
 398                 "netconf-node-topology:keepalive-delay": "300"
 399             }
 400         ]
 401     }
 402
 403
 404 Then check that the netconf session has been correctly established between the controller and the
 405 node. the status of **netconf-node-topology:connection-status** must be **connected**
 406
 407 **REST API** : *GET /restconf/operational/network-topology:network-topology/topology/topology-netconf/node/<node-id>*
 408
 409
 410 Node configuration discovery
 411 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 412
 413 Once the controller is connected to the node, transportPCE application automatically launchs a
 414 discovery of the node configuration datastore and creates **Logical Connection Points** to any
 415 physical ports related to transmission. All *circuit-packs* inside the node configuration are
 416 analyzed.
 417
 418 Use the following JSON RPC to check that function internally named *portMapping*.
 419
 420 **REST API** : *GET /restconf/config/portmapping:network*
 421
 422 .. note::
 423
 424     In ``org-openroadm-device.yang``, four types of optical nodes can be managed:
 425         * rdm: ROADM device (optical switch)
 426         * xpdr: Xponder device (device that converts client to optical channel interface)
 427         * ila: in line amplifier (optical amplifier)
 428         * extplug: external pluggable (an optical pluggable that can be inserted in an external unit such as a router)
 429
 430     TransportPCE currently supports rdm and xpdr
 431
 432 Depending on the kind of open ROADM device connected, different kind of *Logical Connection Points*
 433 should appear, if the node configuration is not empty:
 434
 435 -  DEG<degree-number>-TTP-<port-direction>: created on the line port of a degree on a rdm equipment
 436 -  SRG<srg-number>-PP<port-number>: created on the client port of a srg on a rdm equipment
 437 -  XPDR<number>-CLIENT<port-number>: created on the client port of a xpdr equipment
 438 -  XPDR<number>-NETWORK<port-number>: created on the line port of a xpdr equipment
 439
 440     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>`__.
 441
 442 Optical Network topology
 443 ~~~~~~~~~~~~~~~~~~~~~~~~
 444
 445 Before creating an optical connectivity service, your topology must contain at least two xpdr
 446 devices connected to two different rdm devices. Normally, the *openroadm-topology* is automatically
 447 created by transportPCE. Nevertheless, depending on the configuration inside optical nodes, this
 448 topology can be partial. Check that link of type *ROADMtoROADM* exists between two adjacent rdm
 449 nodes.
 450
 451 **REST API** : *GET /restconf/config/ietf-network:network/openroadm-topology*
 452
 453 If it is not the case, you need to manually complement the topology with *ROADMtoROADM* link using
 454 the following REST RPC:
 455
 456
 457 **REST API** : *POST /restconf/operations/networkutils:init-roadm-nodes*
 458
 459 **Sample JSON Data**
 460
 461 .. code:: json
 462
 463     {
 464       "networkutils:input": {
 465         "networkutils:rdm-a-node": "<node-id-A>",
 466         "networkutils:deg-a-num": "<degree-A-number>",
 467         "networkutils:termination-point-a": "<Logical-Connection-Point>",
 468         "networkutils:rdm-z-node": "<node-id-Z>",
 469         "networkutils:deg-z-num": "<degree-Z-number>",
 470         "networkutils:termination-point-z": "<Logical-Connection-Point>"
 471       }
 472     }
 473
 474 *<Logical-Connection-Point> comes from the portMapping function*.
 475
 476 Unidirectional links between xpdr and rdm nodes must be created manually. To that end use the two
 477 following REST RPCs:
 478
 479 From xpdr to rdm:
 480 ^^^^^^^^^^^^^^^^^
 481
 482 **REST API** : *POST /restconf/operations/networkutils:init-xpdr-rdm-links*
 483
 484 **Sample JSON Data**
 485
 486 .. code:: json
 487
 488     {
 489       "networkutils:input": {
 490         "networkutils:links-input": {
 491           "networkutils:xpdr-node": "<xpdr-node-id>",
 492           "networkutils:xpdr-num": "1",
 493           "networkutils:network-num": "<xpdr-network-port-number>",
 494           "networkutils:rdm-node": "<rdm-node-id>",
 495           "networkutils:srg-num": "<srg-number>",
 496           "networkutils:termination-point-num": "<Logical-Connection-Point>"
 497         }
 498       }
 499     }
 500
 501 From rdm to xpdr:
 502 ^^^^^^^^^^^^^^^^^
 503
 504 **REST API** : *POST /restconf/operations/networkutils:init-rdm-xpdr-links*
 505
 506 **Sample JSON Data**
 507
 508 .. code:: json
 509
 510     {
 511       "networkutils:input": {
 512         "networkutils:links-input": {
 513           "networkutils:xpdr-node": "<xpdr-node-id>",
 514           "networkutils:xpdr-num": "1",
 515           "networkutils:network-num": "<xpdr-network-port-number>",
 516           "networkutils:rdm-node": "<rdm-node-id>",
 517           "networkutils:srg-num": "<srg-number>",
 518           "networkutils:termination-point-num": "<Logical-Connection-Point>"
 519         }
 520       }
 521     }
 522
 523 OTN topology
 524 ~~~~~~~~~~~~
 525
 526 Before creating an OTN service, your topology must contain at least two xpdr devices of MUXPDR
 527 or SWITCH type connected to two different rdm devices. To check that these xpdr are present in the
 528 OTN topology, use the following command on the REST API :
 529
 530 **REST API** : *GET /restconf/config/ietf-network:network/otn-topology*
 531
 532 An optical connectivity service shall have been created in a first setp. In Magnesium SR0, the OTN
 533 links are not automatically populated in the topology after the Och, OTU4 and ODU4 interfaces have
 534 been created on the two network ports of the xpdr. Thus the otn link must be posted manually through
 535 the REST API (as APIDoc for example).
 536
 537 **REST API** : *POST /restconf/config/ietf-network:networks/network/otn-topology/ietf-network-topology:link/<link-id>*
 538
 539 **Sample JSON Data**
 540
 541 .. code:: json
 542
 543    {
 544    "ietf-network-topology:link": [
 545      {
 546        "link-id": "<link-id>",
 547          "source": {
 548            "source-node": "<xpdr-node-id>",
 549            "source-tp": "<xpdr-network-port-id>"
 550          },
 551          "org-openroadm-common-network:link-type": "OTN-LINK",
 552          "destination": {
 553            "dest-node": "<xpdr-node-id>",
 554            "dest-tp": "<xpdr-network-port-id>"
 555          }
 556        }
 557      ]
 558    }
 559
 560
 561 Creating a service
 562 ~~~~~~~~~~~~~~~~~~
 563
 564 Use the *service handler* module to create any end-to-end connectivity service on an OpenROADM
 565 network. Two kind of end-to-end services are managed by TransportPCE :
 566 - 100GE service from client port to client port of two transponders (TPDR)
 567 - Optical Channel (OC) service from client add/drop port (PP port of SRG) to client add/drop port of
 568 two ROADMs.
 569
 570 For these services, TransportPCE automatically invokes *renderer* module to create all required
 571 interfaces and cross-connection on each device supporting the service.
 572 As an example, the creation of a 100GE service implies among other things, the creation of OCH, OTU4
 573 and ODU4 interfaces on the Network port of TPDR devices.
 574
 575 In Magnesium SR0, the *service handler* module does not manage directly the end-to-end aspect of otn
 576 connectivity services. OTN services must be manualy created invoking directly the *renderer* module.
 577
 578
 579 Before creating a low-order otn service (1GE or 10GE services terminating on client port of MUXPDR
 580 or SWITCH), the user must ensure that a high-order ODU4 container exists and has previously been
 581 configured (low-order structured) to support low-order OTN containers. Thus, otn service creation
 582 implies two steps:
 583 1. OCH, OTU-4 and ODU-4 service from network port to network port of two OTN Xponders
 584 (MUXPDR or SWITCH)
 585 2. 1GE or 10GE service creation from client port to client port of two OTN Xponders
 586 (MUXPDR or SWITCH)
 587
 588 Since in Magnesium SR0 otn service creation is not automatically done by TransportPCE, the user has
 589 to check the connectivity between nodes using the internal API of the *PCE* module, through the
 590 path-computation-request rpc.
 591 Afterwards, for the first step otn service creation, the user has to use the internal service-path
 592 rpc of the *renderer* module.
 593 Finally, the 1GE and 10GE services creation is performed using internal otn-service-path rpc of the
 594 *renderer* module.
 595
 596 100GE service creation
 597 ^^^^^^^^^^^^^^^^^^^^^^
 598
 599 Use the following REST RPC to invoke *service handler* module in order to create a bidirectional
 600 end-to-end optical connectivity service between two xpdr over an optical network composed of rdm
 601 nodes.
 602
 603 **REST API** : *POST /restconf/operations/org-openroadm-service:service-create*
 604
 605 **Sample JSON Data**
 606
 607 .. code:: json
 608
 609     {
 610         "input": {
 611             "sdnc-request-header": {
 612                 "request-id": "request-1",
 613                 "rpc-action": "service-create",
 614                 "request-system-id": "appname"
 615             },
 616             "service-name": "test1",
 617             "common-id": "commonId",
 618             "connection-type": "service",
 619             "service-a-end": {
 620                 "service-rate": "100",
 621                 "node-id": "<xpdr-node-id>",
 622                 "service-format": "Ethernet",
 623                 "clli": "<ccli-name>",
 624                 "tx-direction": {
 625                     "port": {
 626                         "port-device-name": "<xpdr-client-port>",
 627                         "port-type": "fixed",
 628                         "port-name": "<xpdr-client-port-number>",
 629                         "port-rack": "000000.00",
 630                         "port-shelf": "Chassis#1"
 631                     },
 632                     "lgx": {
 633                         "lgx-device-name": "Some lgx-device-name",
 634                         "lgx-port-name": "Some lgx-port-name",
 635                         "lgx-port-rack": "000000.00",
 636                         "lgx-port-shelf": "00"
 637                     }
 638                 },
 639                 "rx-direction": {
 640                     "port": {
 641                         "port-device-name": "<xpdr-client-port>",
 642                         "port-type": "fixed",
 643                         "port-name": "<xpdr-client-port-number>",
 644                         "port-rack": "000000.00",
 645                         "port-shelf": "Chassis#1"
 646                     },
 647                     "lgx": {
 648                         "lgx-device-name": "Some lgx-device-name",
 649                         "lgx-port-name": "Some lgx-port-name",
 650                         "lgx-port-rack": "000000.00",
 651                         "lgx-port-shelf": "00"
 652                     }
 653                 },
 654                 "optic-type": "gray"
 655             },
 656             "service-z-end": {
 657                 "service-rate": "100",
 658                 "node-id": "<xpdr-node-id>",
 659                 "service-format": "Ethernet",
 660                 "clli": "<ccli-name>",
 661                 "tx-direction": {
 662                     "port": {
 663                         "port-device-name": "<xpdr-client-port>",
 664                         "port-type": "fixed",
 665                         "port-name": "<xpdr-client-port-number>",
 666                         "port-rack": "000000.00",
 667                         "port-shelf": "Chassis#1"
 668                     },
 669                     "lgx": {
 670                         "lgx-device-name": "Some lgx-device-name",
 671                         "lgx-port-name": "Some lgx-port-name",
 672                         "lgx-port-rack": "000000.00",
 673                         "lgx-port-shelf": "00"
 674                     }
 675                 },
 676                 "rx-direction": {
 677                     "port": {
 678                         "port-device-name": "<xpdr-client-port>",
 679                         "port-type": "fixed",
 680                         "port-name": "<xpdr-client-port-number>",
 681                         "port-rack": "000000.00",
 682                         "port-shelf": "Chassis#1"
 683                     },
 684                     "lgx": {
 685                         "lgx-device-name": "Some lgx-device-name",
 686                         "lgx-port-name": "Some lgx-port-name",
 687                         "lgx-port-rack": "000000.00",
 688                         "lgx-port-shelf": "00"
 689                     }
 690                 },
 691                 "optic-type": "gray"
 692             },
 693             "due-date": "yyyy-mm-ddT00:00:01Z",
 694             "operator-contact": "some-contact-info"
 695         }
 696     }
 697
 698 Most important parameters for this REST RPC are the identification of the two physical client ports
 699 on xpdr nodes.This RPC invokes the *PCE* module to compute a path over the *openroadm-topology* and
 700 then invokes *renderer* and *OLM* to implement the end-to-end path into the devices.
 701
 702
 703 OC service creation
 704 ^^^^^^^^^^^^^^^^^^^
 705
 706 Use the following REST RPC to invoke *service handler* module in order to create a bidirectional
 707 end-to end Optical Channel (OC) connectivity service between two add/drop ports (PP port of SRG
 708 node) over an optical network only composed of rdm nodes.
 709
 710 **REST API** : *POST /restconf/operations/org-openroadm-service:service-create*
 711
 712 **Sample JSON Data**
 713
 714 .. code:: json
 715
 716     {
 717         "input": {
 718             "sdnc-request-header": {
 719                 "request-id": "request-1",
 720                 "rpc-action": "service-create",
 721                 "request-system-id": "appname"
 722             },
 723             "service-name": "something",
 724             "common-id": "commonId",
 725             "connection-type": "roadm-line",
 726             "service-a-end": {
 727                 "service-rate": "100",
 728                 "node-id": "<xpdr-node-id>",
 729                 "service-format": "OC",
 730                 "clli": "<ccli-name>",
 731                 "tx-direction": {
 732                     "port": {
 733                         "port-device-name": "<xpdr-client-port>",
 734                         "port-type": "fixed",
 735                         "port-name": "<xpdr-client-port-number>",
 736                         "port-rack": "000000.00",
 737                         "port-shelf": "Chassis#1"
 738                     },
 739                     "lgx": {
 740                         "lgx-device-name": "Some lgx-device-name",
 741                         "lgx-port-name": "Some lgx-port-name",
 742                         "lgx-port-rack": "000000.00",
 743                         "lgx-port-shelf": "00"
 744                     }
 745                 },
 746                 "rx-direction": {
 747                     "port": {
 748                         "port-device-name": "<xpdr-client-port>",
 749                         "port-type": "fixed",
 750                         "port-name": "<xpdr-client-port-number>",
 751                         "port-rack": "000000.00",
 752                         "port-shelf": "Chassis#1"
 753                     },
 754                     "lgx": {
 755                         "lgx-device-name": "Some lgx-device-name",
 756                         "lgx-port-name": "Some lgx-port-name",
 757                         "lgx-port-rack": "000000.00",
 758                         "lgx-port-shelf": "00"
 759                     }
 760                 },
 761                 "optic-type": "gray"
 762             },
 763             "service-z-end": {
 764                 "service-rate": "100",
 765                 "node-id": "<xpdr-node-id>",
 766                 "service-format": "OC",
 767                 "clli": "<ccli-name>",
 768                 "tx-direction": {
 769                     "port": {
 770                         "port-device-name": "<xpdr-client-port>",
 771                         "port-type": "fixed",
 772                         "port-name": "<xpdr-client-port-number>",
 773                         "port-rack": "000000.00",
 774                         "port-shelf": "Chassis#1"
 775                     },
 776                     "lgx": {
 777                         "lgx-device-name": "Some lgx-device-name",
 778                         "lgx-port-name": "Some lgx-port-name",
 779                         "lgx-port-rack": "000000.00",
 780                         "lgx-port-shelf": "00"
 781                     }
 782                 },
 783                 "rx-direction": {
 784                     "port": {
 785                         "port-device-name": "<xpdr-client-port>",
 786                         "port-type": "fixed",
 787                         "port-name": "<xpdr-client-port-number>",
 788                         "port-rack": "000000.00",
 789                         "port-shelf": "Chassis#1"
 790                     },
 791                     "lgx": {
 792                         "lgx-device-name": "Some lgx-device-name",
 793                         "lgx-port-name": "Some lgx-port-name",
 794                         "lgx-port-rack": "000000.00",
 795                         "lgx-port-shelf": "00"
 796                     }
 797                 },
 798                 "optic-type": "gray"
 799             },
 800             "due-date": "yyyy-mm-ddT00:00:01Z",
 801             "operator-contact": "some-contact-info"
 802         }
 803     }
 804
 805 As for the previous RPC, this RPC invokes the *PCE* module to compute a path over the
 806 *openroadm-topology* and then invokes *renderer* and *OLM* to implement the end-to-end path into
 807 the devices.
 808
 809 OTN OCH, OTU4 and ODU4 service creation
 810 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 811
 812 Use the following REST RPC to invoke *renderer* module in order to create adequate interfaces on
 813 otn device in order to support a bidirectional end-to-end Low-Order OTN connectivity service on
 814 network port of a MUXPDR or SWITCH xpdr node.
 815
 816 **REST API** : *POST /restconf/operations/transportpce-device-renderer:service-path*
 817
 818 **Sample JSON Data**
 819
 820 .. code:: json
 821
 822    {
 823      "input": {
 824        "nodes": [
 825          {
 826            "node-id": "<otn-node-id>",
 827            "dest-tp": "<otn-network-port-logical-connection-point>"
 828          }
 829        ],
 830            "modulation-format": "qpsk",
 831            "operation": "create",
 832            "service-name": "<service-name>",
 833            "wave-number": "<wavenumber-returned-by-PCE>"
 834      }
 835    }
 836
 837 1GE/ODU0 and 10GE/ODU2e service creation
 838 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 839
 840 Use the following REST RPC to invoke *renderer* module and create adequate interfaces on otn xpdr
 841 device (MUXPDR or SWITCH) in order to support a low-order otn service on its client port.
 842
 843 - 1GE and ODU0 interfaces for 1GE services
 844 - 10GE and ODU2e interfaces for 10GE services
 845
 846 The following example corresponds to the creation of a 10GE service
 847
 848 *REST API** : *POST /restconf/operations/transportpce-device-renderer:otn-service-path*
 849
 850 **Sample JSON Data**
 851
 852 .. code:: json
 853
 854    {
 855      "input": {
 856        "service-rate": "10G",
 857        "service-type": "Ethernet",
 858        "ethernet-encoding": "something",
 859        "trib-slot": "<trib-slot-number-inside-supported-ODU4>",
 860        "trib-port-number": "<trib-port-number-inside-supported-ODU4>",
 861        "operation": "create",
 862        "service-name": "something",
 863        "nodes": [
 864          {
 865          "node-id": "<otn-node-id>",
 866          "client-tp": "<client-port-logical-connection-point>",
 867          "network-tp": "<network-port-logical-connection-point>"
 868          }
 869        ]
 870      }
 871    }
 872
 873 .. note::
 874     OTN links are not automatically populated in the topology after the ODU2e interfaces have
 875     been created on the two client ports of the xpdr. The otn link can be posted manually through
 876     the REST API (APIDoc).
 877
 878 .. note::
 879     With Magnesium SR0, the service-list corresponding to 1GE/10GE and OTU4/ODU4 services is not
 880     updated in the datastore after the interfaces have been created in the device.
 881
 882 .. note::
 883     trib-slot is used when the equipment supports contiguous trib-slot allocation (supported in
 884     Magnesium SR0). The trib-slot provided corresponds to the first of the used trib-slots.
 885     complex-trib-slots will be used when the equipment does not support contiguous trib-slot
 886     allocation. In this case a list of the different trib-slots to be used shall be provided.
 887     The support for non contiguous trib-slot allocation is planned for later Magnesium release.
 888
 889 Deleting a service
 890 ~~~~~~~~~~~~~~~~~~
 891
 892 Deleting a 100GE and OC service
 893 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 894
 895 Use the following REST RPC to invoke *service handler* module in order to delete a given optical
 896 connectivity service.
 897
 898 **REST API** : *POST /restconf/operations/org-openroadm-service:service-delete*
 899
 900 **Sample JSON Data**
 901
 902 .. code:: json
 903
 904     {
 905         "input": {
 906             "sdnc-request-header": {
 907                 "request-id": "request-1",
 908                 "rpc-action": "service-delete",
 909                 "request-system-id": "appname",
 910                 "notification-url": "http://localhost:8585/NotificationServer/notify"
 911             },
 912             "service-delete-req-info": {
 913                 "service-name": "something",
 914                 "tail-retention": "no"
 915             }
 916         }
 917     }
 918
 919 Most important parameters for this REST RPC is the *service-name*.
 920
 921 Deleting 1GE/ODU0 or 10GE/ODU2e
 922 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 923
 924 Use the following REST RPC to invoke *renderer* module and delete adequate interfaces on otn node.
 925 The following example corresponds to the deletion of a 10GE service
 926
 927 *REST API** : *POST /restconf/operations/transportpce-device-renderer:otn-service-path*
 928
 929 **Sample JSON Data**
 930
 931 .. code:: json
 932
 933    {
 934      "input": {
 935        "service-rate": "10G",
 936        "service-type": "Ethernet",
 937        "ethernet-encoding": "something",
 938        "trib-slot": "<trib-slot-number-inside-supported-ODU4>",
 939        "trib-port-number": "<trib-port-number-inside-supported-ODU4>",
 940        "operation": "delete",
 941        "service-name": "something",
 942        "nodes": [
 943          {
 944          "node-id": "<otn-node-id>",
 945          "client-tp": "<client-port-logical-connection-point>",
 946          "network-tp": "<network-port-logical-connection-point>"
 947          }
 948        ]
 949      }
 950    }
 951
 952
 953 Deleting OTN OCH, OTU4 and ODU4 service
 954 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 955
 956 Use the following REST RPC to invoke *renderer* module in order to delete adequate interfaces on
 957 otn node.
 958
 959 **REST API** : *POST /restconf/operations/transportpce-device-renderer:service-path*
 960
 961 **Sample JSON Data**
 962
 963 .. code:: json
 964
 965    {
 966      "input": {
 967        "nodes": [
 968          {
 969            "node-id": "<otn-node-id>",
 970            "dest-tp": "<otn-network-port-logical-connection-point>"
 971          }
 972        ],
 973        "modulation-format": "qpsk",
 974        "operation": "delete",
 975        "service-name": "<service-name>",
 976        "wave-number": "<wavenumber-returned-by-PCE>",
 977      }
 978    }
 979
 980 .. note::
 981     Be sure to have deleted all low-order otn services before deleting high-order OTN container
 982
 983
 984 Invoking PCE module
 985 ~~~~~~~~~~~~~~~~~~~
 986
 987 Use the following REST RPCs to invoke *PCE* module in order to check connectivity between xponder
 988 nodes and the availability of a supporting optical connectivity between the network-ports of the
 989 nodes.
 990
 991 Checking OTU4 service connectivity
 992 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 993
 994 **REST API** : *POST /restconf/operations/transportpce-pce:path-computation-request*
 995
 996 **Sample JSON Data**
 997
 998 .. code:: json
 999
1000    {
1001       "input": {
1002            "service-name": "something",
1003            "resource-reserve": "true",
1004            "service-handler-header": {
1005              "request-id": "request1"
1006            },
1007            "service-a-end": {
1008              "service-rate": "100",
1009              "clli": "<clli-node>",
1010              "service-format": "OTU",
1011              "node-id": "<otn-node-id>"
1012            },
1013            "service-z-end": {
1014              "service-rate": "100",
1015              "clli": "<clli-node>",
1016              "service-format": "OTU",
1017              "node-id": "<otn-node-id>"
1018              },
1019            "pce-metric": "hop-count"
1020        }
1021    }
1022
1023 .. note::
1024     here, the <otn-node-id> corresponds to the node-id as appearing in "openroadm-network" topology
1025     layer
1026
1027 Checking ODU4 service connectivity
1028 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1029
1030 **REST API** : *POST /restconf/operations/transportpce-pce:path-computation-request*
1031
1032 **Sample JSON Data**
1033
1034 .. code:: json
1035
1036    {
1037       "input": {
1038            "service-name": "something",
1039            "resource-reserve": "true",
1040            "service-handler-header": {
1041              "request-id": "request1"
1042            },
1043            "service-a-end": {
1044              "service-rate": "100",
1045              "clli": "<clli-node>",
1046              "service-format": "ODU",
1047              "node-id": "<otn-node-id>"
1048            },
1049            "service-z-end": {
1050              "service-rate": "100",
1051              "clli": "<clli-node>",
1052              "service-format": "ODU",
1053              "node-id": "<otn-node-id>"
1054              },
1055            "pce-metric": "hop-count"
1056        }
1057    }
1058
1059 .. note::
1060     here, the <otn-node-id> corresponds to the node-id as appearing in "otn-topology" layer
1061
1062 Checking 10GE/ODU2e service connectivity
1063 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1064
1065 **REST API** : *POST /restconf/operations/transportpce-pce:path-computation-request*
1066
1067 **Sample JSON Data**
1068
1069 .. code:: json
1070
1071    {
1072       "input": {
1073            "service-name": "something",
1074            "resource-reserve": "true",
1075            "service-handler-header": {
1076              "request-id": "request1"
1077            },
1078            "service-a-end": {
1079              "service-rate": "10",
1080              "clli": "<clli-node>",
1081              "service-format": "Ethernet",
1082              "node-id": "<otn-node-id>"
1083            },
1084            "service-z-end": {
1085              "service-rate": "10",
1086              "clli": "<clli-node>",
1087              "service-format": "Ethernet",
1088              "node-id": "<otn-node-id>"
1089              },
1090            "pce-metric": "hop-count"
1091        }
1092    }
1093
1094 .. note::
1095     here, the <otn-node-id> corresponds to the node-id as appearing in "otn-topology" layer
1096
1097
1098 Help
1099 ----
1100
1101 -  `TransportPCE Wiki archive <https://wiki-archive.opendaylight.org/view/TransportPCE:Main>`__
1102
1103 -  TransportPCE Mailing List
1104    (`developer <https://lists.opendaylight.org/mailman/listinfo/transportpce-dev>`__)