docs/user-guide.rst

   1 .. _transportpce-user-guide:
   2
   3 TransportPCE User 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…),
  13 a 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 For the time being, it provides very basic alarm/fault management and performance monitoring,
  21 but this function might be externalized to improve the scalability.
  22 A Graphical User Interface (`Transport PCE_GUI <https://gitlab.com/Orange-OpenSource/lfn/odl/tpce_gui>`__)
  23 has been developped separately and is not proposed here since automated control
  24 does not imply user interactions at the transport controller level.
  25
  26 TransportPCE modular architecture is described on the next diagram. Each main
  27 function such as Topology management, Path Calculation Engine (PCE), Service
  28 handler, Renderer responsible for the path configuration through optical
  29 equipment and Optical Line Management (OLM) is associated with a generic block
  30 relying on open models, each of them communicating through published APIs.
  31
  32 .. figure:: ./images/TransportPCE-Diagram-Phosphorus.jpg
  33    :alt: TransportPCE architecture
  34
  35    TransportPCE architecture
  36
  37 TransportPCE User-Facing Features
  38 ---------------------------------
  39 -  **odl-transportpce**
  40
  41    -  This feature contains all other features/bundles of TransportPCE project.
  42       If you install it, it provides all functions that the TransportPCE project
  43       can support.
  44       It exposes all Transportpce project specific models defined in "Service-path".
  45       These models complement OpenROADM models describing South and Northbound APIs, and define the
  46       data structure used to interconnect the generic blocks/functions described on the previous
  47       diagram.
  48
  49 -  **feature odl-transportpce-tapi**
  50
  51    -  This feature provides transportPCE a limited support of TAPI version 2.1.1 Northbound interface.
  52
  53 -  **feature odl-transportpce-inventory**
  54
  55    -  This feature is considered experimental. It provides transportPCE with an external connector to
  56       a MariaDB inventory currently limited to OpenROADM 1.2.1 devices.
  57
  58 -  **feature odl-transportpce-dmaap-client**
  59
  60    -  This feature is considered experimental. It provides a REST client in order to send TPCE notifications
  61       to ONAP Dmaap Message router.
  62
  63 -  **feature odl-transportpce-nbinotifications**
  64
  65    -  This feature is considered experimental. It provides transportPCE with connectors in order to read/write
  66       notifications stored in topics of a Kafka server.
  67
  68 How To Start
  69 ------------
  70
  71 Preparing for Installation
  72 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  73
  74 1. Devices must support the standard OpenROADM Models more precisely versions 1.2.1, 2.2.1 or 7.1.0.
  75    Since Magnesium SR0, an OTN experimental support is provided for OpenROADM devices 2.2.1.
  76    Magnesium SR2 is the first release managing end-to-end OTN services, as OCH-OTU4,
  77    structured ODU4 or again 10GE-ODU2e services.
  78    This has also been extended to be supported on 7.1 devices
  79
  80 2. Devices must support configuration through NETCONF protocol/API.
  81
  82
  83
  84 Installation Feature
  85 ~~~~~~~~~~~~~~~~~~~~
  86
  87 Creation of services with TransportPCE controller on real optical devices takes a rather long while,
  88 due to the fact that the output optical power level modification on interfaces requires time for stabilisation
  89 level. By default values of TransportPCE timers are those recommended by OpenROADM MSA, respectively 120 000
  90 and 20 000 seconds.
  91 When running TransportPCE controller with honeynode simulators, which is the case of all TransportPCE functional tests,
  92 we don't need so important timer values. You can considerably speed tests using respectively 3000 and 2000 seconds.
  93 To that end, before starting karaf of the OpenDaylight TransportPCE controller, set OLM_TIMER1 and OLM_TIMER2 as environment variables.
  94 For example::
  95
  96     export OLM_TIMER1=3000 OLM_TIMER2=2000
  97
  98 To come back with per default values for these timers, just logout from OpenDaylight controller, unset your
  99 environment variables, and start again the controller::
 100
 101     unset OLM_TIMER1 OLM_TIMER2
 102
 103
 104 Run OpenDaylight and install TransportPCE Service *odl-transportpce* as below::
 105
 106    feature:install odl-transportpce
 107
 108 if you need TAPI limited support, then run::
 109
 110    feature:install odl-transportpce-tapi
 111
 112 When installing the TAPI feature, you might encounter a heap memory size problem in Karaf.
 113 In that case, consider increasing Karaf heap memory size.
 114 For example by modifying the environment variables JAVA_MIN_MEM and JAVA_MAX_MEM before starting Karaf::
 115
 116    export JAVA_MIN_MEM=1024M
 117    export JAVA_MAX_MEM=4069M
 118
 119 In Chlorine, installation of odl-transportpce-tapi feature may cause some other transportpce OSGi bundle to be
 120 in failure. To restore the situation, just log out and log back in.
 121
 122 If you need the inventory external connector support limited to 1.2.1 OpenROADM devices, then run::
 123
 124    feature:install odl-transportpce-inventory
 125
 126 If you need the Dmaap connector support, before running Opendaylight, set DMAAP_BASE_URL as environment variable.
 127 For example, if the base url of your Dmaap server is "https://dmaap-mr:30226", then::
 128
 129     export DMAAP_BASE_URL=https://dmaap-mr:30226
 130
 131 If your Dmaap server provides https connection through a self-signed certificate, do not forget to add the certificate
 132 to the JAVA truststore::
 133
 134     echo -n | openssl s_client -showcerts -connect dmaap-mr:30226 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/dmaap.crt
 135     keytool -import -v -trustcacerts -alias dmaap -file /tmp/dmaap.crt -keystore /etc/ssl/certs/java/cacerts -keypass changeit -storepass changeit -noprompt
 136
 137 where dmaap-mr:30226 is the url of your Dmaap server.
 138
 139 Then run in karaf::
 140
 141    feature:install odl-transportpce-dmaap-client
 142
 143 If you need the NBI-notifications support, before installing odl-transportpce-nbinotifications feature,
 144 make sure to run ZooKeeper and then the Kafka server.
 145 By default, it is considered that the Kafka server is installed in localhost and listens on the 9092 port,
 146 if it isn't the case then set the KAFKA_SERVER environment variable of your system or
 147 modify the file *'transportpce/features/odl-transportpce-nbinotifications
 148 /src/main/resources/org.opendaylight.transportpce.nbinotifications.cfg'*::
 149
 150    suscriber.server=${env:KAFKA_SERVER:-[IP_ADDRESS]:[PORT]}
 151    publisher.server=${env:KAFKA_SERVER:-[IP_ADDRESS]:[PORT]}
 152
 153 *where [IP_ADDRESS] and [PORT] are respectively the IP address and the port that host the Kafka server.*
 154
 155 After that, run in karaf::
 156
 157    feature:install odl-transportpce-nbinotifications
 158
 159 .. note::
 160
 161     In Chlorine release, the odl-transportpce-swagger feature is no longer functional. Issue still under investigation.
 162
 163
 164 For a more detailed overview of the TransportPCE, see the :ref:`transportpce-dev-guide`.