docs/interface-manager-design.rst

   1 ========================
   2 Interface Manager Design
   3 ========================
   4
   5 The Interface Manager (IFM) uses MD-SAL based architecture, where
   6 different software components operate on, and interact via a set of
   7 data-models. Interface manager defines configuration data-stores where
   8 other OpenDaylight modules can write interface configurations and
   9 register for services. These configuration data-stores can also be
  10 accessed by external entities through REST interface. IFM listens to
  11 changes in these config data-stores and accordingly programs the
  12 data-plane. Data in Configuration data-stores remains persistent across
  13 controller restarts.
  14
  15 Operational data like network state and other service specific
  16 operational data are stored in operational data-stores. Change in
  17 network state is updated in southbound interfaces (OFplugin, OVSDB)
  18 data-stores. Interface Manager uses ODL Inventory and Topology
  19 datastores to retrive southbound configurations and events. IFM listens
  20 to these updates and accordingly updates its own operational data-stores.
  21 Operational data stores are cleaned up after a controller restart.
  22
  23 Additionally, a set of RPCs to access IFM data-stores
  24 and provide other useful information. Following figure presents
  25 different IFM data-stores and its interaction with other modules.
  26
  27 Follwoing diagram provides a toplevel architecture of Interface Manager.
  28
  29 .. image:: https://wiki.opendaylight.org/images/2/25/Ifmsbirenderers.png
  30    :scale: 60 %
  31
  32 InterfaceManager Dependencies
  33 =============================
  34 Interface Manager uses other Genius modules for its operations.
  35 It mainly interacts with following other genius modules-
  36
  37 #. **Id Manager** – For allocating dataplane interface-id (if-index)
  38 #. **Aliveness Monitor** - For registering the interfaces for monitoring
  39 #. **MdSalUtil** – For interactions with MD-SAL and other openflow operations
  40
  41 Following picture shows interface manager dependencies
  42
  43 .. graphviz:: images/ifm_dep.dot
  44
  45 Code structure
  46 ==============
  47 Interface manager code is organized in following folders -
  48
  49 #. **interfacemanager-api** contains the interface yang data models and
  50    corresponding interface implementation.
  51 #. **interfacemanager-impl** contains the interfacemanager
  52    implementation
  53 #. **interface-manager-shell** contains Karaf CLI implementation for
  54    interfacemanager
  55
  56 **interfacemanager-api**
  57
  58 | ``└───main``
  59 | ``   ├───java``
  60 | ``   │   └───org``
  61 | ``   │       └───opendaylight``
  62 | ``   │           └───genius``
  63 | ``   │               └───interfacemanager``
  64 | ``   │                   ├───exceptions``
  65 | ``   │                   ├───globals``
  66 | ``   │                   └───interfaces``
  67 | ``   └───yang``
  68
  69 **interfacemanager-impl**
  70
  71 | ``├───commons                   <--- contains common utility functions``
  72 | ``├───listeners                 <--- Contains interfacemanager DCN listenenrs for differnt MD-SAL datastores``
  73 | ``├───renderer                  <--- Contains different southbound renderers' implementation``
  74 | ``│   ├───hwvtep                <--- HWVTEP specific renderer``
  75 | ``│   │   ├───confighelpers                     ``
  76 | ``│   │   ├───statehelpers``
  77 | ``│   │   └───utilities``
  78 | ``│   └───ovs                   <--- OVS specific SBI renderer``
  79 | ``│       ├───confighelpers``
  80 | ``│       ├───statehelpers``
  81 | ``│       └───utilities``
  82 | ``├───servicebindings           <--- contains interface service binding DCN listener and corresponding implementation``
  83 | ``│   └───flowbased``
  84 | ``│       ├───confighelpers``
  85 | ``│       ├───listeners``
  86 | ``│       ├───statehelpers``
  87 | ``│       └───utilities``
  88 | ``├───rpcservice                <--- Contains interfacemanager RPCs' implementation``
  89 | ``├───pmcounters                <--- Contains PM counters gathering``\
  90 | ``└───statusanddiag             <--- contains status and diagnostics implementations``
  91
  92  *'interfacemanager-shell*
  93
  94 Interfacemanager Data-model
  95 ===========================
  96
  97 FOllowing picture shows different MD-SAL datastores used by intetrface manager.
  98 These datastores are created based on YANG datamodels defined in interfacemanager-api.
  99
 100 .. image:: https://wiki.opendaylight.org/images/4/46/Ifmarch.png
 101
 102
 103 Config Datastores
 104 -----------------
 105
 106 InterfaceManager mainly uses following two datastores to accept configurations.
 107
 108 #. **odl-interface** datamodel () where verious type of interface can be
 109    configuted.
 110 #. **service-binding** datamodel () where different applications can
 111    bind services to interfaces.
 112
 113 In addition to these datamodels, it also implements several RPCs for
 114 accessing interface operational data. Details of these datamodels and
 115 RPCs are described in following sections.
 116
 117 Interface Config DS
 118 ~~~~~~~~~~~~~~~~~~~
 119
 120 Interface config datamodel is defined in
 121 `odl-interface.yang <https://github.com/opendaylight/genius/blob/master/interfacemanager/interfacemanager-api/src/main/yang/odl-interface.yang>`__
 122 . It is based on ‘ietf-interfaces’ datamodel (imported in
 123 odl\_interface.yang) with additional augmentations to it. Common
 124 interface configurations are –
 125
 126 -  **name (string)** : this is the unique interface name/identifier.
 127 -  **type (identityref:iana-if-type)** : this configuration sets the
 128    interface type. Interface types are defined in iana-if-types data
 129    model. Odl-interfaces.yang data model adds augmentations to
 130    iana-if-types to define new interface types. Currently supported
 131    interface types are -
 132
 133    -  **l2vlan** (trunk, vlan classified sub-ports/trunk-member)
 134    -  **tunnel** (OVS based VxLAN, GRE, MPLSoverGRE/MPLSoverUDP)
 135
 136 -  **enabled (Boolean)** : this configuration sets the administrative
 137    state of the interface.
 138 -  **parent-refs :** this configuration specifies the parent of the
 139    interface, which feeds data/hosts this interface. It can be a
 140    physical switch port or a virtual switch port.
 141
 142    -  Parent-interface (string) : is the port name with which a network
 143       port in dataplane in that appearing on the southbound interface.
 144       E.g. neutron port. this can also be another interface, thus
 145       supporting a hierarchy of linked interfaces.
 146    -  Node-identifier (topology\_id, node\_id) : is used for configuring
 147       parent node for HW nodes/VTEPs
 148
 149 Additional configuration parameters are defined for specific interface
 150 type. Please see the table below.
 151
 152 +-------------------------------------+----------------------------------+----------------------------------------+------------------------------+----------------------------+
 153 | **Vlan-xparent**                    | **Vlan-trunk**                   | **Vlan-trunk-member**                  | **vxlan**                    | **gre**                    |
 154 +-------------------------------------+----------------------------------+----------------------------------------+------------------------------+----------------------------+
 155 | **Name** =uuid                      | **Name** =uuid                   | **Name** =uuid                         | **Name** =uuid               | **Name** =uuid             |
 156 +-------------------------------------+----------------------------------+----------------------------------------+------------------------------+----------------------------+
 157 | description                         | description                      | description                            | description                  | description                |
 158 +-------------------------------------+----------------------------------+----------------------------------------+------------------------------+----------------------------+
 159 | **Type** =l2vlan                    | **Type** =l2valn                 | **Type** =l2vlan                       | **Type** =tunnel             | **Type** =tunnel           |
 160 +-------------------------------------+----------------------------------+----------------------------------------+------------------------------+----------------------------+
 161 | **enabled**                         | **enabled**                      | **enabled**                            | **enabled**                  | **enabled**                |
 162 +-------------------------------------+----------------------------------+----------------------------------------+------------------------------+----------------------------+
 163 | **Parent-if** = port-name           | **Parent-if** = port-name        | **Parent-if** = vlan-trunkIf           | Vlan-id                      | Vlan-id                    |
 164 +-------------------------------------+----------------------------------+----------------------------------------+------------------------------+----------------------------+
 165 | **vlan-mode** = transparent         | **vlan-mode**  = trunk           | **vlan-mode** = trunk-member           | **tunnel-type** = vxlan      | **tunnel-type** = gre      |
 166 +-------------------------------------+----------------------------------+----------------------------------------+------------------------------+----------------------------+
 167 |                                     | vlan-list= [trunk-member-list]   | **Vlan-Id** =  trunk-vlanId            | dpn-id                       | dpn-id                     |
 168 +-------------------------------------+----------------------------------+----------------------------------------+------------------------------+----------------------------+
 169 |                                     |                                  | **Parent-if** = vlan-trunkIf           | Vlan-id                      | Vlan-id                    |
 170 +-------------------------------------+----------------------------------+----------------------------------------+------------------------------+----------------------------+
 171 |                                     |                                  |                                        | **local-ip**                 | **local-ip**               |
 172 +-------------------------------------+----------------------------------+----------------------------------------+------------------------------+----------------------------+
 173 |                                     |                                  |                                        | **remote-ip**                | **remote-ip**              |
 174 +-------------------------------------+----------------------------------+----------------------------------------+------------------------------+----------------------------+
 175 |                                     |                                  |                                        | **gayeway-ip**               | **gayeway-ip**             |
 176 +-------------------------------------+----------------------------------+----------------------------------------+------------------------------+----------------------------+
 177
 178 Interface service binding config
 179 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 180
 181 Yang Data Model
 182 `odl-interface-service-bindings.yang <https://github.com/opendaylight/genius/blob/master/interfacemanager/interfacemanager-api/src/main/yang/odl-interface-service-bindings.yang>`__
 183 contains the service binding configuration daatmodel.
 184
 185 An application can bind services to a particular interface by
 186 configuring MD-SAL data node at path /config/interface-service-binding.
 187 Binding services on interface allows particular service to pull traffic
 188 arriving on that interface, depending upon the a service priority. It is
 189 possible to bind services at ingress interface (when packet enters into
 190 the packet-pipeline from particular interface) as well as on the egress
 191 Interface (before the packet is sent out on particular interafce).
 192 Service modules can specify openflow-rules to be applied on the packet
 193 belonging to the interface. Usually these rules include sending the
 194 packet to specific service table/pipeline. Service modules/applications
 195 are responsible for sending the packet back (if not consumed) to service
 196 dispatcher table, for next service to process the packet.
 197
 198 .. image:: https://wiki.opendaylight.org/images/5/56/App_co_exist_new.png
 199    :scale: 70 %
 200
 201 Following are the service binding parameters –
 202
 203 -  **interface-name** is name of the interface to which service binding
 204    is being configured
 205 -  **Service-Priority** parameter is used to define the order in which
 206    the packet will be delivered to different services bind to the
 207    particular interface.
 208 -  Service-Name
 209 -  **Service-Info** parameter is used to configure flow rule to be
 210    applied to the packets as needed by services/applications.
 211
 212    -  (for service-type openflow-based)
 213    -  Flow-priority
 214    -  Instruction-list
 215
 216 When a service is bind to an interface, Interface Manager programs the
 217 service dispatcher table with a rule to match on the interface
 218 data-plane-id and the service-index (based on priority) and the
 219 instruction-set provided by the service/application. Every time when the
 220 packet leaves the dispatcher table the service-index (in metadata) is
 221 incremented to match the next service rule when the packet is
 222 resubmitted back to dispatcher table. Following table gives an example
 223 of the service dispatcher flows, where one interface is bind to 2
 224 services.
 225
 226 +--------------------------------------------------------------------------------------------------+
 227 | **Service Dispatcher Table**                                                                     |
 228 +--------------------------------+-----------------------------------------------------------------+
 229 | **Match**                      | **Actions**                                                     |
 230 +--------------------------------+-----------------------------------------------------------------+
 231 | -  if-index = I                | -  Set SI=2 in metadata                                         |
 232 | -  ServiceIndex = 1            | -  service specific actions <e.g., Goto prio 1 Service table>   |
 233 +--------------------------------+-----------------------------------------------------------------+
 234 | -  if-index = I                | -  Set SI=3 in metadata                                         |
 235 | -  ServiceIndex = 2            | -  service specific actions <e.g., Goto prio 2 Service table>   |
 236 +--------------------------------+-----------------------------------------------------------------+
 237 | miss                           | Drop                                                            |
 238 +--------------------------------+-----------------------------------------------------------------+
 239
 240 Interface Manager programs openflow rules in the service dispatcher
 241 table.
 242
 243 Egress Service Binding
 244 ~~~~~~~~~~~~~~~~~~~~~~
 245
 246 There are services that need packet processing on the
 247 egress, before sending the packet out to particular port/interface. To
 248 accommodate this, interface manager also supports egress
 249 service binding. This is achieved by introducing a new “egress
 250 dispatcher table” at the egress of packet pipeline before the interface
 251 egress groups.
 252
 253 On different application request, Interface Manager returns the egress
 254 actions for interfaces. Service modules program use these actions to
 255 send the packet to particular interface. Generally, these egress actions
 256 include sending packet out to port or appropriate interface egress
 257 group. With the inclusion of the egress dispatcher table the **egress
 258 actions** for the services would be to
 259
 260 -  Update REG6 -  Set service\_index =0 and egress if\_index
 261 -  send the packet to Egress Dispatcher table
 262
 263 IFM shall add a default entry in Egress Dispatcher Table for each interface
 264 With -
 265
 266 -  Match on if\_index with REG6
 267 -  Send packet to corresponding output port or Egress group.
 268
 269 On Egress Service binding, IFM shall add rules to Egress Dispatcher
 270 table with following parameters –
 271
 272 -  Match on
 273
 274    -  ServiceIndex=egress Service priority
 275    -  if\_index in REG6 = if\_index for egress interface
 276
 277 -  Actions
 278
 279    -  Increment service\_index
 280    -  Actions provided by egress service binding.
 281
 282 Egress Services will be responsible for sending packet back to Egress
 283 Dispatcher table, if the packet is not consumed (dropped/ send out). In
 284 this case the packet will hit the lowest priority default entry and the
 285 packet will be send out.
 286
 287
 288 Operational Datastores
 289 ----------------------
 290 Interface Manager uses ODL Inventory and Topology datastores to retrive southbound
 291 configurations and events.
 292
 293
 294 Interface Manager modules
 295 =========================
 296
 297 Interface manager is designed in a modular fashion to provide a flexible
 298 way to support multiple southbound protocols. North-bound
 299 interface/data-model is decoupled from south bound plugins. NBI Data
 300 change listeners select and interact with appropriate SBI renderers. The
 301 modular design also allows addition of new renderers to support new
 302 southbound interfaces, protocols plugins. Following figure shows
 303 interface manager modules –
 304
 305 .. image:: images/ifmsbirenderers.png
 306    :scale: 60 %
 307
 308 Threading Model and Clustering Considerations
 309 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 310
 311 InterfaceManager uses the datastore-job-coordinator module for all its
 312 operations.
 313
 314 .. toctree::
 315    :maxdepth: 1
 316
 317    datastore-job-coordinator
 318
 319 Datastore job coordinator solves the following problems
 320 which is observed in the previous Li-based interface manager :
 321
 322 #. The Business Logic for the Interface configuration/state handling is
 323    performed in the Actor Thread itself.
 324 #. This will cause the Actor’s mailbox to get filled up and may start
 325    causing unnecessary back-pressure.
 326 #. Actions that can be executed independently will get unnecessarily
 327    serialized.
 328 #. Can cause other unrelated applications starve for chance to execute.
 329 #. Available CPU power may not be utilized fully. (for instance, if 1000
 330    interfaces are created on different ports, all 1000 interfaces
 331    creation will happen one after the other.)
 332 #. May depend on external applications to distribute the load across the
 333    actors.
 334
 335
 336 IFM Listeners
 337 -------------
 338
 339 IFM listeners listen to data change events for different MD-SAL data-stores. On the NBI side it
 340 implements data change listeners for interface config data-store and the
 341 service-binding data store. On the SBI side IFM implements listeners for
 342 Topology and Inventory data-stores in opendaylight.
 343
 344 Interface Config change listener
 345 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 346
 347 Interface config change listener listens to ietf-interface/interfaces data node.
 348
 349 service-binding change listener
 350 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 351
 352 Interface config change listener listens to ietf-interface/interfaces data node.
 353
 354 Topology state change listener
 355 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 356
 357 Interface config change listener listens to ietf-interface/interfaces data node.
 358
 359 inventory state change listener
 360 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 361
 362 +++ this page is under construction +++
 363
 364 Dynamic Behavior
 365 ================
 366
 367 when a l2vlan interface is configured
 368 -------------------------------------
 369
 370 #. Interface ConfigDS is populated
 371 #. Interface DCN in InterfaceManager does the following :
 372
 373    - Add interface-state entry for the new interface along with if-index generated
 374    - Add ingress flow entry
 375    - If it is a trunk VLAN, need to add the interface-state for all child interfaces, and add ingress flows for all child interfaces
 376
 377 when a tunnel interface is configured
 378 -------------------------------------
 379
 380 #. Interface ConfigDS is populated
 381 #. Interface DCN in InterfaceManager does the following :
 382
 383    - Creates bridge interface entry in odl-interface-meta Config DS
 384    - Add port to Bridge using OVSDB
 385       - retrieves the bridge UUID corresponding to the interface and
 386       - populates the OVSDB Termination Point Datastore with the following information
 387
 388 |
 389 | ``tpAugmentationBuilder.setName(portName);``
 390 | ``tpAugmentationBuilder.setInterfaceType(type);``
 391 | ``options.put(``\ “``key``”\ ``, ``\ “``flow``”\ ``);``
 392 | ``options.put(``\ “``local_ip``”\ ``, localIp.getIpv4Address().getValue());``
 393 | ``options.put(``\ “``remote_ip``”\ ``, remoteIp.getIpv4Address().getValue());``
 394 | ``tpAugmentationBuilder.setOptions(options);``
 395
 396  OVSDB plugin acts upon this data change and configures the tunnel end
 397 points on the switch with the supplied information.
 398
 399 NodeConnector comes up on vSwitch
 400 ---------------------------------
 401
 402 Inventory DCN Listener in InterfaceManager does the following:
 403    #. Updates interface-state DS.
 404    #. Generate if-index for the interface
 405    #. Update if-index to interface reverse lookup map
 406    #. If interface maps to a vlan trunk entity, operational states of
 407       all vlan trunk members are updated
 408    #. If interface maps to tunnel entity, add ingress tunnel flow
 409
 410 Bridge is created on vSWitch
 411 ----------------------------
 412
 413 Topology DCN Listener in InterfaceManager does the following:
 414    #. Update odl-interface-meta OperDS to have the dpid to bridge
 415       reference
 416    #. Retrieve all pre provisioned bridge Interface Entries for this
 417       dpn, and add ports to bridge using ovsdb
 418
 419 ELAN/VPNManager does a bind service
 420 -----------------------------------
 421
 422 #. Interface service-bindings config DS is populated with service name,
 423    priority and lport dispatcher flow instruction details
 424 #. Based on the service priority, the higher priority service flow will
 425    go in dispatcher table with match as if-index
 426 #. Lower priority service will go in the same lport dispatcher table
 427    with match as if-index and service priority
 428
 429 Interface Manager Sequence Diagrams
 430 ===================================
 431
 432 Following gallery contains sequence diagrams for different IFM
 433 operations -
 434
 435 Removal of Tunnel Interface When OF Switch is Connected
 436 -------------------------------------------------------
 437
 438 .. image:: https://wiki.opendaylight.org/images/8/81/Removal_of_Tunnel_Interface_When_OF_Switch_is_Connected.png
 439
 440 Removal of Tunnel Interfaces in Pre provisioning Mode
 441 -----------------------------------------------------
 442
 443 .. image:: https://wiki.opendaylight.org/images/7/7e/Removal_of_Tunnel_Interfaces_in_Pre_provisioning_Mode.png
 444
 445 Updating of Tunnel Interfaces in Pre provisioning Mode
 446 ------------------------------------------------------
 447
 448 .. image:: https://wiki.opendaylight.org/images/5/57/Updating_of_Tunnel_Interfaces_in_Pre_provisioning_Mode.png
 449
 450 creation of tunnel-interface when OF switch is connected and PortName already in OperDS
 451 ---------------------------------------------------------------------------------------
 452
 453 .. image:: https://wiki.opendaylight.org/images/5/5d/Creation_of_tunnel-interface_when_OF_switch_is_connected_and_PortName_already_in_OperDS.png
 454
 455 creation of vlan interface in pre provisioning mode
 456 ---------------------------------------------------
 457
 458 .. image:: https://wiki.opendaylight.org/images/d/d7/Creation_of_vlan_interface_in_pre_provisioning_mode.png
 459
 460 creation of vlan interface when switch is connected
 461 ---------------------------------------------------
 462
 463 .. image:: https://wiki.opendaylight.org/images/b/b4/Creation_of_vlan_interface_when_switch_is_connected.png
 464
 465 deletion of vlan interface in pre provisioning mode
 466 ---------------------------------------------------
 467
 468 .. image:: https://wiki.opendaylight.org/images/9/96/Deletion_of_vlan_interface_in_pre_provisioning_mode.png
 469
 470 deletion of vlan interface when switch is connect
 471 -------------------------------------------------
 472
 473 .. image:: https://wiki.opendaylight.org/images/9/96/Deletion_of_vlan_interface_when_switch_is_connected.png
 474
 475 Node connector added updated DCN handling
 476 -----------------------------------------
 477
 478 .. image:: https://wiki.opendaylight.org/images/c/ce/Node_connector_added_updated_DCN_handling.png
 479
 480 Node connector removed DCN handling
 481 -----------------------------------
 482
 483 .. image:: https://wiki.opendaylight.org/images/3/36/Node_connector_removed_DCN_handling.png
 484
 485 updation of vlan interface in pre provisioning mode
 486 ---------------------------------------------------
 487
 488 .. image:: https://wiki.opendaylight.org/view/File:Updation_of_vlan_interface_in_pre_provisioning_mode.png
 489
 490 updation of vlan interface when switch is connect
 491 -------------------------------------------------
 492
 493 .. image:: https://wiki.opendaylight.org/images/e/e5/Updation_of_vlan_interface_when_switch_is_connected.png