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
 198 Inventory
 199 ^^^^^^^^^
 200
 201 TransportPCE Inventory module is responsible to keep track of devices connected in an external MariaDB database.
 202 Other databases may be used as long as they comply with SQL and are compatible with OpenDaylight (for example MySQL).
 203 At present, the module supports extracting and persisting inventory of devices OpenROADM MSA version 1.2.1.
 204 Inventory module changes to support newer device models (2.2.1, etc) and other models (network, service, etc)
 205 will be progressively included.
 206
 207 The inventory module can be activated by the associated karaf feature (odl-transporpce-inventory)
 208 The database properties are supplied in the “opendaylight-release” and “opendaylight-snapshots” profiles.
 209 Below is the settings.xml with properties included in the distribution.
 210 The module can be rebuild from sources with different parameters.
 211
 212 Sample entry in settings.xml to declare an external inventory database:
 213 ::
 214
 215     <profiles>
 216       <profile>
 217           <id>opendaylight-release</id>
 218     [..]
 219          <properties>
 220                  <transportpce.db.host><<hostname>>:3306</transportpce.db.host>
 221                  <transportpce.db.database><<databasename>></transportpce.db.database>
 222                  <transportpce.db.username><<username>></transportpce.db.username>
 223                  <transportpce.db.password><<password>></transportpce.db.password>
 224                  <karaf.localFeature>odl-transportpce-inventory</karaf.localFeature>
 225          </properties>
 226     </profile>
 227     [..]
 228     <profile>
 229           <id>opendaylight-snapshots</id>
 230     [..]
 231          <properties>
 232                  <transportpce.db.host><<hostname>>:3306</transportpce.db.host>
 233                  <transportpce.db.database><<databasename>></transportpce.db.database>
 234                  <transportpce.db.username><<username>></transportpce.db.username>
 235                  <transportpce.db.password><<password>></transportpce.db.password>
 236                  <karaf.localFeature>odl-transportpce-inventory</karaf.localFeature>
 237          </properties>
 238         </profile>
 239     </profiles>
 240
 241
 242 Once the project built and when karaf is started, the cfg file is generated in etc folder with the corresponding
 243 properties supplied in settings.xml. When devices with OpenROADM 1.2.1 device model are mounted, the device listener in
 244 the inventory module loads several device attributes to various tables as per the supplied database.
 245 The database structure details can be retrieved from the file tests/inventory/initdb.sql inside project sources.
 246 Installation scripts and a docker file are also provided.
 247
 248 Key APIs and Interfaces
 249 -----------------------
 250
 251 External API
 252 ~~~~~~~~~~~~
 253
 254 North API, interconnecting the Service Handler to higher level applications
 255 relies on the Service Model defined in the MSA. The Renderer and the OLM are
 256 developed to allow configuring Open ROADM devices through a southbound
 257 Netconf/Yang interface and rely on the MSA’s device model.
 258
 259 ServiceHandler Service
 260 ^^^^^^^^^^^^^^^^^^^^^^
 261
 262 -  RPC call
 263
 264    -  service-create (given service-name, service-aend, service-zend)
 265
 266    -  service-delete (given service-name)
 267
 268    -  service-reroute (given service-name, service-aend, service-zend)
 269
 270    -  service-restoration (given service-name, service-aend, service-zend)
 271
 272    -  temp-service-create (given common-id, service-aend, service-zend)
 273
 274    -  temp-service-delete (given common-id)
 275
 276 -  Data structure
 277
 278    -  service list : made of services
 279    -  temp-service list : made of temporary services
 280    -  service : composed of service-name, topology wich describes the detailed path (list of used resources)
 281
 282 -  Notification
 283
 284    - service-rpc-result : result of service RPC
 285    - service-notification : service has been added, modified or removed
 286
 287 Netconf Service
 288 ^^^^^^^^^^^^^^^
 289
 290 -  RPC call
 291
 292    -  connect-device : PUT
 293    -  disconnect-device : DELETE
 294    -  check-connected-device : GET
 295
 296 -  Data Structure
 297
 298    -  node list : composed of netconf nodes in topology-netconf
 299
 300 Internal APIs
 301 ~~~~~~~~~~~~~
 302
 303 Internal APIs define REST APIs to interconnect TransportPCE modules :
 304
 305 -   Service Handler to PCE
 306 -   PCE to Topology Management
 307 -   Service Handler to Renderer
 308 -   Renderer to OLM
 309
 310 Pce Service
 311 ^^^^^^^^^^^
 312
 313 -  RPC call
 314
 315    -  path-computation-request (given service-name, service-aend, service-zend)
 316
 317    -  cancel-resource-reserve (given service-name)
 318
 319 -  Notification
 320
 321    - service-path-rpc-result : result of service RPC
 322
 323 Renderer Service
 324 ^^^^^^^^^^^^^^^^
 325
 326 -  RPC call
 327
 328    -  service-implementation-request (given service-name, service-aend, service-zend)
 329
 330    -  service-delete (given service-name)
 331
 332 -  Data structure
 333
 334    -  service path list : composed of service paths
 335    -  service path : composed of service-name, path description giving the list of abstracted elements (nodes, tps, links)
 336
 337 -  Notification
 338
 339    - service-path-rpc-result : result of service RPC
 340
 341 Device Renderer
 342 ^^^^^^^^^^^^^^^
 343
 344 -  RPC call
 345
 346    -  service-path used in SR0 as an intermediate solution to address directly the renderer
 347       from a REST NBI to create OCH-OTU4-ODU4 interfaces on network port of otn devices.
 348
 349    -  otn-service-path used in SR0 as an intermediate solution to address directly the renderer
 350       from a REST NBI for otn-service creation. Otn service-creation through
 351       service-implementation-request call from the Service Handler will be supported in later
 352       Magnesium releases
 353
 354 Topology Management Service
 355 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 356
 357 -  Data structure
 358
 359    -  network list : composed of networks(openroadm-topology, netconf-topology)
 360    -  node list : composed of nodes identified by their node-id
 361    -  link list : composed of links identified by their link-id
 362    -  node : composed of roadm, xponder
 363       link : composed of links of different types (roadm-to-roadm, express, add-drop ...)
 364
 365 OLM Service
 366 ^^^^^^^^^^^
 367
 368 -  RPC call
 369
 370    -  get-pm (given node-id)
 371
 372    -  service-power-setup
 373
 374    -  service-power-turndown
 375
 376    -  service-power-reset
 377
 378    -  calculate-spanloss-base
 379
 380    -  calculate-spanloss-current
 381
 382 odl-transportpce-stubmodels
 383 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 384
 385    -  This feature provides function to be able to stub some of TransportPCE modules, pce and
 386       renderer (Stubpce and Stubrenderer).
 387       Stubs are used for development purposes and can be used for some of the functionnal tests.
 388
 389 Interfaces to external software
 390 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 391
 392 It defines the interfaces implemented to interconnect TransportPCE modules with other software in
 393 order to perform specific tasks
 394
 395 GNPy interface
 396 ^^^^^^^^^^^^^^
 397
 398 -  Request structure
 399
 400    -  topology : composed of list of elements and connections
 401    -  service : source, destination, explicit-route-objects, path-constraints
 402
 403 -  Response structure
 404
 405    -  path-properties/path-metric : OSNR-0.1nm, OSNR-bandwidth, SNR-0.1nm, SNR-bandwidth,
 406    -  path-properties/path-route-objects : composed of path elements
 407
 408
 409 Running transportPCE project
 410 ----------------------------
 411
 412 To use transportPCE controller, the first step is to connect the controller to optical nodes
 413 through the NETCONF connector.
 414
 415 .. note::
 416
 417     In the current version, only optical equipment compliant with open ROADM datamodels are managed
 418     by transportPCE.
 419
 420
 421 Connecting nodes
 422 ~~~~~~~~~~~~~~~~
 423
 424 To connect a node, use the following JSON RPC
 425
 426 **REST API** : *POST /restconf/config/network-topology:network-topology/topology/topology-netconf/node/<node-id>*
 427
 428 **Sample JSON Data**
 429
 430 .. code:: json
 431
 432     {
 433         "node": [
 434             {
 435                 "node-id": "<node-id>",
 436                 "netconf-node-topology:tcp-only": "false",
 437                 "netconf-node-topology:reconnect-on-changed-schema": "false",
 438                 "netconf-node-topology:host": "<node-ip-address>",
 439                 "netconf-node-topology:default-request-timeout-millis": "120000",
 440                 "netconf-node-topology:max-connection-attempts": "0",
 441                 "netconf-node-topology:sleep-factor": "1.5",
 442                 "netconf-node-topology:actor-response-wait-time": "5",
 443                 "netconf-node-topology:concurrent-rpc-limit": "0",
 444                 "netconf-node-topology:between-attempts-timeout-millis": "2000",
 445                 "netconf-node-topology:port": "<netconf-port>",
 446                 "netconf-node-topology:connection-timeout-millis": "20000",
 447                 "netconf-node-topology:username": "<node-username>",
 448                 "netconf-node-topology:password": "<node-password>",
 449                 "netconf-node-topology:keepalive-delay": "300"
 450             }
 451         ]
 452     }
 453
 454
 455 Then check that the netconf session has been correctly established between the controller and the
 456 node. the status of **netconf-node-topology:connection-status** must be **connected**
 457
 458 **REST API** : *GET /restconf/operational/network-topology:network-topology/topology/topology-netconf/node/<node-id>*
 459
 460
 461 Node configuration discovery
 462 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 463
 464 Once the controller is connected to the node, transportPCE application automatically launchs a
 465 discovery of the node configuration datastore and creates **Logical Connection Points** to any
 466 physical ports related to transmission. All *circuit-packs* inside the node configuration are
 467 analyzed.
 468
 469 Use the following JSON RPC to check that function internally named *portMapping*.
 470
 471 **REST API** : *GET /restconf/config/portmapping:network*
 472
 473 .. note::
 474
 475     In ``org-openroadm-device.yang``, four types of optical nodes can be managed:
 476         * rdm: ROADM device (optical switch)
 477         * xpdr: Xponder device (device that converts client to optical channel interface)
 478         * ila: in line amplifier (optical amplifier)
 479         * extplug: external pluggable (an optical pluggable that can be inserted in an external unit such as a router)
 480
 481     TransportPCE currently supports rdm and xpdr
 482
 483 Depending on the kind of open ROADM device connected, different kind of *Logical Connection Points*
 484 should appear, if the node configuration is not empty:
 485
 486 -  DEG<degree-number>-TTP-<port-direction>: created on the line port of a degree on a rdm equipment
 487 -  SRG<srg-number>-PP<port-number>: created on the client port of a srg on a rdm equipment
 488 -  XPDR<number>-CLIENT<port-number>: created on the client port of a xpdr equipment
 489 -  XPDR<number>-NETWORK<port-number>: created on the line port of a xpdr equipment
 490
 491     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>`__.
 492
 493 Optical Network topology
 494 ~~~~~~~~~~~~~~~~~~~~~~~~
 495
 496 Before creating an optical connectivity service, your topology must contain at least two xpdr
 497 devices connected to two different rdm devices. Normally, the *openroadm-topology* is automatically
 498 created by transportPCE. Nevertheless, depending on the configuration inside optical nodes, this
 499 topology can be partial. Check that link of type *ROADMtoROADM* exists between two adjacent rdm
 500 nodes.
 501
 502 **REST API** : *GET /restconf/config/ietf-network:network/openroadm-topology*
 503
 504 If it is not the case, you need to manually complement the topology with *ROADMtoROADM* link using
 505 the following REST RPC:
 506
 507
 508 **REST API** : *POST /restconf/operations/networkutils:init-roadm-nodes*
 509
 510 **Sample JSON Data**
 511
 512 .. code:: json
 513
 514     {
 515       "networkutils:input": {
 516         "networkutils:rdm-a-node": "<node-id-A>",
 517         "networkutils:deg-a-num": "<degree-A-number>",
 518         "networkutils:termination-point-a": "<Logical-Connection-Point>",
 519         "networkutils:rdm-z-node": "<node-id-Z>",
 520         "networkutils:deg-z-num": "<degree-Z-number>",
 521         "networkutils:termination-point-z": "<Logical-Connection-Point>"
 522       }
 523     }
 524
 525 *<Logical-Connection-Point> comes from the portMapping function*.
 526
 527 Unidirectional links between xpdr and rdm nodes must be created manually. To that end use the two
 528 following REST RPCs:
 529
 530 From xpdr to rdm:
 531 ^^^^^^^^^^^^^^^^^
 532
 533 **REST API** : *POST /restconf/operations/networkutils:init-xpdr-rdm-links*
 534
 535 **Sample JSON Data**
 536
 537 .. code:: json
 538
 539     {
 540       "networkutils:input": {
 541         "networkutils:links-input": {
 542           "networkutils:xpdr-node": "<xpdr-node-id>",
 543           "networkutils:xpdr-num": "1",
 544           "networkutils:network-num": "<xpdr-network-port-number>",
 545           "networkutils:rdm-node": "<rdm-node-id>",
 546           "networkutils:srg-num": "<srg-number>",
 547           "networkutils:termination-point-num": "<Logical-Connection-Point>"
 548         }
 549       }
 550     }
 551
 552 From rdm to xpdr:
 553 ^^^^^^^^^^^^^^^^^
 554
 555 **REST API** : *POST /restconf/operations/networkutils:init-rdm-xpdr-links*
 556
 557 **Sample JSON Data**
 558
 559 .. code:: json
 560
 561     {
 562       "networkutils:input": {
 563         "networkutils:links-input": {
 564           "networkutils:xpdr-node": "<xpdr-node-id>",
 565           "networkutils:xpdr-num": "1",
 566           "networkutils:network-num": "<xpdr-network-port-number>",
 567           "networkutils:rdm-node": "<rdm-node-id>",
 568           "networkutils:srg-num": "<srg-number>",
 569           "networkutils:termination-point-num": "<Logical-Connection-Point>"
 570         }
 571       }
 572     }
 573
 574 OTN topology
 575 ~~~~~~~~~~~~
 576
 577 Before creating an OTN service, your topology must contain at least two xpdr devices of MUXPDR
 578 or SWITCH type connected to two different rdm devices. To check that these xpdr are present in the
 579 OTN topology, use the following command on the REST API :
 580
 581 **REST API** : *GET /restconf/config/ietf-network:network/otn-topology*
 582
 583 An optical connectivity service shall have been created in a first setp. In Magnesium SR0, the OTN
 584 links are not automatically populated in the topology after the Och, OTU4 and ODU4 interfaces have
 585 been created on the two network ports of the xpdr. Thus the otn link must be posted manually through
 586 the REST API (as APIDoc for example).
 587
 588 **REST API** : *POST /restconf/config/ietf-network:networks/network/otn-topology/ietf-network-topology:link/<link-id>*
 589
 590 **Sample JSON Data**
 591
 592 .. code:: json
 593
 594    {
 595    "ietf-network-topology:link": [
 596      {
 597        "link-id": "<link-id>",
 598          "source": {
 599            "source-node": "<xpdr-node-id>",
 600            "source-tp": "<xpdr-network-port-id>"
 601          },
 602          "org-openroadm-common-network:link-type": "OTN-LINK",
 603          "destination": {
 604            "dest-node": "<xpdr-node-id>",
 605            "dest-tp": "<xpdr-network-port-id>"
 606          }
 607        }
 608      ]
 609    }
 610
 611
 612 Creating a service
 613 ~~~~~~~~~~~~~~~~~~
 614
 615 Use the *service handler* module to create any end-to-end connectivity service on an OpenROADM
 616 network. Two kind of end-to-end services are managed by TransportPCE :
 617 - 100GE service from client port to client port of two transponders (TPDR)
 618 - Optical Channel (OC) service from client add/drop port (PP port of SRG) to client add/drop port of
 619 two ROADMs.
 620
 621 For these services, TransportPCE automatically invokes *renderer* module to create all required
 622 interfaces and cross-connection on each device supporting the service.
 623 As an example, the creation of a 100GE service implies among other things, the creation of OCH, OTU4
 624 and ODU4 interfaces on the Network port of TPDR devices.
 625
 626 In Magnesium SR0, the *service handler* module does not manage directly the end-to-end aspect of otn
 627 connectivity services. OTN services must be manualy created invoking directly the *renderer* module.
 628
 629
 630 Before creating a low-order otn service (1GE or 10GE services terminating on client port of MUXPDR
 631 or SWITCH), the user must ensure that a high-order ODU4 container exists and has previously been
 632 configured (low-order structured) to support low-order OTN containers. Thus, otn service creation
 633 implies two steps:
 634 1. OCH, OTU-4 and ODU-4 service from network port to network port of two OTN Xponders
 635 (MUXPDR or SWITCH)
 636 2. 1GE or 10GE service creation from client port to client port of two OTN Xponders
 637 (MUXPDR or SWITCH)
 638
 639 Since in Magnesium SR0 otn service creation is not automatically done by TransportPCE, the user has
 640 to check the connectivity between nodes using the internal API of the *PCE* module, through the
 641 path-computation-request rpc.
 642 Afterwards, for the first step otn service creation, the user has to use the internal service-path
 643 rpc of the *renderer* module.
 644 Finally, the 1GE and 10GE services creation is performed using internal otn-service-path rpc of the
 645 *renderer* module.
 646
 647 100GE service creation
 648 ^^^^^^^^^^^^^^^^^^^^^^
 649
 650 Use the following REST RPC to invoke *service handler* module in order to create a bidirectional
 651 end-to-end optical connectivity service between two xpdr over an optical network composed of rdm
 652 nodes.
 653
 654 **REST API** : *POST /restconf/operations/org-openroadm-service:service-create*
 655
 656 **Sample JSON Data**
 657
 658 .. code:: json
 659
 660     {
 661         "input": {
 662             "sdnc-request-header": {
 663                 "request-id": "request-1",
 664                 "rpc-action": "service-create",
 665                 "request-system-id": "appname"
 666             },
 667             "service-name": "test1",
 668             "common-id": "commonId",
 669             "connection-type": "service",
 670             "service-a-end": {
 671                 "service-rate": "100",
 672                 "node-id": "<xpdr-node-id>",
 673                 "service-format": "Ethernet",
 674                 "clli": "<ccli-name>",
 675                 "tx-direction": {
 676                     "port": {
 677                         "port-device-name": "<xpdr-client-port>",
 678                         "port-type": "fixed",
 679                         "port-name": "<xpdr-client-port-number>",
 680                         "port-rack": "000000.00",
 681                         "port-shelf": "Chassis#1"
 682                     },
 683                     "lgx": {
 684                         "lgx-device-name": "Some lgx-device-name",
 685                         "lgx-port-name": "Some lgx-port-name",
 686                         "lgx-port-rack": "000000.00",
 687                         "lgx-port-shelf": "00"
 688                     }
 689                 },
 690                 "rx-direction": {
 691                     "port": {
 692                         "port-device-name": "<xpdr-client-port>",
 693                         "port-type": "fixed",
 694                         "port-name": "<xpdr-client-port-number>",
 695                         "port-rack": "000000.00",
 696                         "port-shelf": "Chassis#1"
 697                     },
 698                     "lgx": {
 699                         "lgx-device-name": "Some lgx-device-name",
 700                         "lgx-port-name": "Some lgx-port-name",
 701                         "lgx-port-rack": "000000.00",
 702                         "lgx-port-shelf": "00"
 703                     }
 704                 },
 705                 "optic-type": "gray"
 706             },
 707             "service-z-end": {
 708                 "service-rate": "100",
 709                 "node-id": "<xpdr-node-id>",
 710                 "service-format": "Ethernet",
 711                 "clli": "<ccli-name>",
 712                 "tx-direction": {
 713                     "port": {
 714                         "port-device-name": "<xpdr-client-port>",
 715                         "port-type": "fixed",
 716                         "port-name": "<xpdr-client-port-number>",
 717                         "port-rack": "000000.00",
 718                         "port-shelf": "Chassis#1"
 719                     },
 720                     "lgx": {
 721                         "lgx-device-name": "Some lgx-device-name",
 722                         "lgx-port-name": "Some lgx-port-name",
 723                         "lgx-port-rack": "000000.00",
 724                         "lgx-port-shelf": "00"
 725                     }
 726                 },
 727                 "rx-direction": {
 728                     "port": {
 729                         "port-device-name": "<xpdr-client-port>",
 730                         "port-type": "fixed",
 731                         "port-name": "<xpdr-client-port-number>",
 732                         "port-rack": "000000.00",
 733                         "port-shelf": "Chassis#1"
 734                     },
 735                     "lgx": {
 736                         "lgx-device-name": "Some lgx-device-name",
 737                         "lgx-port-name": "Some lgx-port-name",
 738                         "lgx-port-rack": "000000.00",
 739                         "lgx-port-shelf": "00"
 740                     }
 741                 },
 742                 "optic-type": "gray"
 743             },
 744             "due-date": "yyyy-mm-ddT00:00:01Z",
 745             "operator-contact": "some-contact-info"
 746         }
 747     }
 748
 749 Most important parameters for this REST RPC are the identification of the two physical client ports
 750 on xpdr nodes.This RPC invokes the *PCE* module to compute a path over the *openroadm-topology* and
 751 then invokes *renderer* and *OLM* to implement the end-to-end path into the devices.
 752
 753
 754 OC service creation
 755 ^^^^^^^^^^^^^^^^^^^
 756
 757 Use the following REST RPC to invoke *service handler* module in order to create a bidirectional
 758 end-to end Optical Channel (OC) connectivity service between two add/drop ports (PP port of SRG
 759 node) over an optical network only composed of rdm nodes.
 760
 761 **REST API** : *POST /restconf/operations/org-openroadm-service:service-create*
 762
 763 **Sample JSON Data**
 764
 765 .. code:: json
 766
 767     {
 768         "input": {
 769             "sdnc-request-header": {
 770                 "request-id": "request-1",
 771                 "rpc-action": "service-create",
 772                 "request-system-id": "appname"
 773             },
 774             "service-name": "something",
 775             "common-id": "commonId",
 776             "connection-type": "roadm-line",
 777             "service-a-end": {
 778                 "service-rate": "100",
 779                 "node-id": "<xpdr-node-id>",
 780                 "service-format": "OC",
 781                 "clli": "<ccli-name>",
 782                 "tx-direction": {
 783                     "port": {
 784                         "port-device-name": "<xpdr-client-port>",
 785                         "port-type": "fixed",
 786                         "port-name": "<xpdr-client-port-number>",
 787                         "port-rack": "000000.00",
 788                         "port-shelf": "Chassis#1"
 789                     },
 790                     "lgx": {
 791                         "lgx-device-name": "Some lgx-device-name",
 792                         "lgx-port-name": "Some lgx-port-name",
 793                         "lgx-port-rack": "000000.00",
 794                         "lgx-port-shelf": "00"
 795                     }
 796                 },
 797                 "rx-direction": {
 798                     "port": {
 799                         "port-device-name": "<xpdr-client-port>",
 800                         "port-type": "fixed",
 801                         "port-name": "<xpdr-client-port-number>",
 802                         "port-rack": "000000.00",
 803                         "port-shelf": "Chassis#1"
 804                     },
 805                     "lgx": {
 806                         "lgx-device-name": "Some lgx-device-name",
 807                         "lgx-port-name": "Some lgx-port-name",
 808                         "lgx-port-rack": "000000.00",
 809                         "lgx-port-shelf": "00"
 810                     }
 811                 },
 812                 "optic-type": "gray"
 813             },
 814             "service-z-end": {
 815                 "service-rate": "100",
 816                 "node-id": "<xpdr-node-id>",
 817                 "service-format": "OC",
 818                 "clli": "<ccli-name>",
 819                 "tx-direction": {
 820                     "port": {
 821                         "port-device-name": "<xpdr-client-port>",
 822                         "port-type": "fixed",
 823                         "port-name": "<xpdr-client-port-number>",
 824                         "port-rack": "000000.00",
 825                         "port-shelf": "Chassis#1"
 826                     },
 827                     "lgx": {
 828                         "lgx-device-name": "Some lgx-device-name",
 829                         "lgx-port-name": "Some lgx-port-name",
 830                         "lgx-port-rack": "000000.00",
 831                         "lgx-port-shelf": "00"
 832                     }
 833                 },
 834                 "rx-direction": {
 835                     "port": {
 836                         "port-device-name": "<xpdr-client-port>",
 837                         "port-type": "fixed",
 838                         "port-name": "<xpdr-client-port-number>",
 839                         "port-rack": "000000.00",
 840                         "port-shelf": "Chassis#1"
 841                     },
 842                     "lgx": {
 843                         "lgx-device-name": "Some lgx-device-name",
 844                         "lgx-port-name": "Some lgx-port-name",
 845                         "lgx-port-rack": "000000.00",
 846                         "lgx-port-shelf": "00"
 847                     }
 848                 },
 849                 "optic-type": "gray"
 850             },
 851             "due-date": "yyyy-mm-ddT00:00:01Z",
 852             "operator-contact": "some-contact-info"
 853         }
 854     }
 855
 856 As for the previous RPC, this RPC invokes the *PCE* module to compute a path over the
 857 *openroadm-topology* and then invokes *renderer* and *OLM* to implement the end-to-end path into
 858 the devices.
 859
 860 OTN OCH, OTU4 and ODU4 service creation
 861 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 862
 863 Use the following REST RPC to invoke *renderer* module in order to create adequate interfaces on
 864 otn device in order to support a bidirectional end-to-end Low-Order OTN connectivity service on
 865 network port of a MUXPDR or SWITCH xpdr node.
 866
 867 **REST API** : *POST /restconf/operations/transportpce-device-renderer:service-path*
 868
 869 **Sample JSON Data**
 870
 871 .. code:: json
 872
 873    {
 874      "input": {
 875        "nodes": [
 876          {
 877            "node-id": "<otn-node-id>",
 878            "dest-tp": "<otn-network-port-logical-connection-point>"
 879          }
 880        ],
 881            "modulation-format": "qpsk",
 882            "operation": "create",
 883            "service-name": "<service-name>",
 884            "wave-number": "<wavenumber-returned-by-PCE>"
 885      }
 886    }
 887
 888 1GE/ODU0 and 10GE/ODU2e service creation
 889 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 890
 891 Use the following REST RPC to invoke *renderer* module and create adequate interfaces on otn xpdr
 892 device (MUXPDR or SWITCH) in order to support a low-order otn service on its client port.
 893
 894 - 1GE and ODU0 interfaces for 1GE services
 895 - 10GE and ODU2e interfaces for 10GE services
 896
 897 The following example corresponds to the creation of a 10GE service
 898
 899 *REST API** : *POST /restconf/operations/transportpce-device-renderer:otn-service-path*
 900
 901 **Sample JSON Data**
 902
 903 .. code:: json
 904
 905    {
 906      "input": {
 907        "service-rate": "10G",
 908        "service-type": "Ethernet",
 909        "ethernet-encoding": "something",
 910        "trib-slot": "<trib-slot-number-inside-supported-ODU4>",
 911        "trib-port-number": "<trib-port-number-inside-supported-ODU4>",
 912        "operation": "create",
 913        "service-name": "something",
 914        "nodes": [
 915          {
 916          "node-id": "<otn-node-id>",
 917          "client-tp": "<client-port-logical-connection-point>",
 918          "network-tp": "<network-port-logical-connection-point>"
 919          }
 920        ]
 921      }
 922    }
 923
 924 .. note::
 925     OTN links are not automatically populated in the topology after the ODU2e interfaces have
 926     been created on the two client ports of the xpdr. The otn link can be posted manually through
 927     the REST API (APIDoc).
 928
 929 .. note::
 930     With Magnesium SR0, the service-list corresponding to 1GE/10GE and OTU4/ODU4 services is not
 931     updated in the datastore after the interfaces have been created in the device.
 932
 933 .. note::
 934     trib-slot is used when the equipment supports contiguous trib-slot allocation (supported in
 935     Magnesium SR0). The trib-slot provided corresponds to the first of the used trib-slots.
 936     complex-trib-slots will be used when the equipment does not support contiguous trib-slot
 937     allocation. In this case a list of the different trib-slots to be used shall be provided.
 938     The support for non contiguous trib-slot allocation is planned for later Magnesium release.
 939
 940 Deleting a service
 941 ~~~~~~~~~~~~~~~~~~
 942
 943 Deleting a 100GE and OC service
 944 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 945
 946 Use the following REST RPC to invoke *service handler* module in order to delete a given optical
 947 connectivity service.
 948
 949 **REST API** : *POST /restconf/operations/org-openroadm-service:service-delete*
 950
 951 **Sample JSON Data**
 952
 953 .. code:: json
 954
 955     {
 956         "input": {
 957             "sdnc-request-header": {
 958                 "request-id": "request-1",
 959                 "rpc-action": "service-delete",
 960                 "request-system-id": "appname",
 961                 "notification-url": "http://localhost:8585/NotificationServer/notify"
 962             },
 963             "service-delete-req-info": {
 964                 "service-name": "something",
 965                 "tail-retention": "no"
 966             }
 967         }
 968     }
 969
 970 Most important parameters for this REST RPC is the *service-name*.
 971
 972 Deleting 1GE/ODU0 or 10GE/ODU2e
 973 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 974
 975 Use the following REST RPC to invoke *renderer* module and delete adequate interfaces on otn node.
 976 The following example corresponds to the deletion of a 10GE service
 977
 978 *REST API** : *POST /restconf/operations/transportpce-device-renderer:otn-service-path*
 979
 980 **Sample JSON Data**
 981
 982 .. code:: json
 983
 984    {
 985      "input": {
 986        "service-rate": "10G",
 987        "service-type": "Ethernet",
 988        "ethernet-encoding": "something",
 989        "trib-slot": "<trib-slot-number-inside-supported-ODU4>",
 990        "trib-port-number": "<trib-port-number-inside-supported-ODU4>",
 991        "operation": "delete",
 992        "service-name": "something",
 993        "nodes": [
 994          {
 995          "node-id": "<otn-node-id>",
 996          "client-tp": "<client-port-logical-connection-point>",
 997          "network-tp": "<network-port-logical-connection-point>"
 998          }
 999        ]
1000      }
1001    }
1002
1003
1004 Deleting OTN OCH, OTU4 and ODU4 service
1005 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1006
1007 Use the following REST RPC to invoke *renderer* module in order to delete adequate interfaces on
1008 otn node.
1009
1010 **REST API** : *POST /restconf/operations/transportpce-device-renderer:service-path*
1011
1012 **Sample JSON Data**
1013
1014 .. code:: json
1015
1016    {
1017      "input": {
1018        "nodes": [
1019          {
1020            "node-id": "<otn-node-id>",
1021            "dest-tp": "<otn-network-port-logical-connection-point>"
1022          }
1023        ],
1024        "modulation-format": "qpsk",
1025        "operation": "delete",
1026        "service-name": "<service-name>",
1027        "wave-number": "<wavenumber-returned-by-PCE>",
1028      }
1029    }
1030
1031 .. note::
1032     Be sure to have deleted all low-order otn services before deleting high-order OTN container
1033
1034
1035 Invoking PCE module
1036 ~~~~~~~~~~~~~~~~~~~
1037
1038 Use the following REST RPCs to invoke *PCE* module in order to check connectivity between xponder
1039 nodes and the availability of a supporting optical connectivity between the network-ports of the
1040 nodes.
1041
1042 Checking OTU4 service connectivity
1043 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1044
1045 **REST API** : *POST /restconf/operations/transportpce-pce:path-computation-request*
1046
1047 **Sample JSON Data**
1048
1049 .. code:: json
1050
1051    {
1052       "input": {
1053            "service-name": "something",
1054            "resource-reserve": "true",
1055            "service-handler-header": {
1056              "request-id": "request1"
1057            },
1058            "service-a-end": {
1059              "service-rate": "100",
1060              "clli": "<clli-node>",
1061              "service-format": "OTU",
1062              "node-id": "<otn-node-id>"
1063            },
1064            "service-z-end": {
1065              "service-rate": "100",
1066              "clli": "<clli-node>",
1067              "service-format": "OTU",
1068              "node-id": "<otn-node-id>"
1069              },
1070            "pce-metric": "hop-count"
1071        }
1072    }
1073
1074 .. note::
1075     here, the <otn-node-id> corresponds to the node-id as appearing in "openroadm-network" topology
1076     layer
1077
1078 Checking ODU4 service connectivity
1079 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1080
1081 **REST API** : *POST /restconf/operations/transportpce-pce:path-computation-request*
1082
1083 **Sample JSON Data**
1084
1085 .. code:: json
1086
1087    {
1088       "input": {
1089            "service-name": "something",
1090            "resource-reserve": "true",
1091            "service-handler-header": {
1092              "request-id": "request1"
1093            },
1094            "service-a-end": {
1095              "service-rate": "100",
1096              "clli": "<clli-node>",
1097              "service-format": "ODU",
1098              "node-id": "<otn-node-id>"
1099            },
1100            "service-z-end": {
1101              "service-rate": "100",
1102              "clli": "<clli-node>",
1103              "service-format": "ODU",
1104              "node-id": "<otn-node-id>"
1105              },
1106            "pce-metric": "hop-count"
1107        }
1108    }
1109
1110 .. note::
1111     here, the <otn-node-id> corresponds to the node-id as appearing in "otn-topology" layer
1112
1113 Checking 10GE/ODU2e service connectivity
1114 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1115
1116 **REST API** : *POST /restconf/operations/transportpce-pce:path-computation-request*
1117
1118 **Sample JSON Data**
1119
1120 .. code:: json
1121
1122    {
1123       "input": {
1124            "service-name": "something",
1125            "resource-reserve": "true",
1126            "service-handler-header": {
1127              "request-id": "request1"
1128            },
1129            "service-a-end": {
1130              "service-rate": "10",
1131              "clli": "<clli-node>",
1132              "service-format": "Ethernet",
1133              "node-id": "<otn-node-id>"
1134            },
1135            "service-z-end": {
1136              "service-rate": "10",
1137              "clli": "<clli-node>",
1138              "service-format": "Ethernet",
1139              "node-id": "<otn-node-id>"
1140              },
1141            "pce-metric": "hop-count"
1142        }
1143    }
1144
1145 .. note::
1146     here, the <otn-node-id> corresponds to the node-id as appearing in "otn-topology" layer
1147
1148
1149 Help
1150 ----
1151
1152 -  `TransportPCE Wiki <https://wiki.opendaylight.org/display/ODL/TransportPCE>`__