1 ========================
2 Interface Manager Design
3 ========================
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
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.
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.
27 Follwoing diagram provides a toplevel architecture of Interface Manager.
29 .. image:: https://wiki.opendaylight.org/images/2/25/Ifmsbirenderers.png
32 InterfaceManager Dependencies
33 =============================
34 Interface Manager uses other Genius modules for its operations.
35 It mainly interacts with following other genius modules-
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
41 Following picture shows interface manager dependencies
43 .. graphviz:: images/ifm_dep.dot
47 Interface manager code is organized in following folders -
49 #. **interfacemanager-api** contains the interface yang data models and
50 corresponding interface implementation.
51 #. **interfacemanager-impl** contains the interfacemanager
53 #. **interface-manager-shell** contains Karaf CLI implementation for
56 **interfacemanager-api**
61 | `` │ └───opendaylight``
63 | `` │ └───interfacemanager``
64 | `` │ ├───exceptions``
66 | `` │ └───interfaces``
69 **interfacemanager-impl**
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``
82 | ``├───servicebindings <--- contains interface service binding DCN listener and corresponding implementation``
84 | ``│ ├───confighelpers``
86 | ``│ ├───statehelpers``
88 | ``├───rpcservice <--- Contains interfacemanager RPCs' implementation``
89 | ``├───pmcounters <--- Contains PM counters gathering``\
90 | ``└───statusanddiag <--- contains status and diagnostics implementations``
92 *'interfacemanager-shell*
94 Interfacemanager Data-model
95 ===========================
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.
100 .. image:: https://wiki.opendaylight.org/images/4/46/Ifmarch.png
106 InterfaceManager mainly uses following two datastores to accept configurations.
108 #. **odl-interface** datamodel () where verious type of interface can be
110 #. **service-binding** datamodel () where different applications can
111 bind services to interfaces.
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.
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 –
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 -
133 - **l2vlan** (trunk, vlan classified sub-ports/trunk-member)
134 - **tunnel** (OVS based VxLAN, GRE, MPLSoverGRE/MPLSoverUDP)
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.
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
149 Additional configuration parameters are defined for specific interface
150 type. Please see the table below.
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 +-------------------------------------+----------------------------------+----------------------------------------+------------------------------+----------------------------+
178 Interface service binding config
179 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
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.
198 .. image:: https://wiki.opendaylight.org/images/5/56/App_co_exist_new.png
201 Following are the service binding parameters –
203 - **interface-name** is name of the interface to which service binding
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.
209 - **Service-Info** parameter is used to configure flow rule to be
210 applied to the packets as needed by services/applications.
212 - (for service-type openflow-based)
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
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 +--------------------------------+-----------------------------------------------------------------+
238 +--------------------------------+-----------------------------------------------------------------+
240 Interface Manager programs openflow rules in the service dispatcher
243 Egress Service Binding
244 ~~~~~~~~~~~~~~~~~~~~~~
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
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
260 - Update REG6 - Set service\_index =0 and egress if\_index
261 - send the packet to Egress Dispatcher table
263 IFM shall add a default entry in Egress Dispatcher Table for each interface
266 - Match on if\_index with REG6
267 - Send packet to corresponding output port or Egress group.
269 On Egress Service binding, IFM shall add rules to Egress Dispatcher
270 table with following parameters –
274 - ServiceIndex=egress Service priority
275 - if\_index in REG6 = if\_index for egress interface
279 - Increment service\_index
280 - Actions provided by egress service binding.
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.
288 Operational Datastores
289 ----------------------
290 Interface Manager uses ODL Inventory and Topology datastores to retrive southbound
291 configurations and events.
294 Interface Manager modules
295 =========================
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 –
305 .. image:: images/ifmsbirenderers.png
308 Threading Model and Clustering Considerations
309 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
311 InterfaceManager uses the datastore-job-coordinator module for all its
317 datastore-job-coordinator
319 Datastore job coordinator solves the following problems
320 which is observed in the previous Li-based interface manager :
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
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
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.
344 Interface Config change listener
345 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
347 Interface config change listener listens to ietf-interface/interfaces data node.
349 service-binding change listener
350 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
352 Interface config change listener listens to ietf-interface/interfaces data node.
354 Topology state change listener
355 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
357 Interface config change listener listens to ietf-interface/interfaces data node.
359 inventory state change listener
360 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
362 +++ this page is under construction +++
367 when a l2vlan interface is configured
368 -------------------------------------
370 #. Interface ConfigDS is populated
371 #. Interface DCN in InterfaceManager does the following :
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
377 when a tunnel interface is configured
378 -------------------------------------
380 #. Interface ConfigDS is populated
381 #. Interface DCN in InterfaceManager does the following :
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
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);``
396 OVSDB plugin acts upon this data change and configures the tunnel end
397 points on the switch with the supplied information.
399 NodeConnector comes up on vSwitch
400 ---------------------------------
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
410 Bridge is created on vSWitch
411 ----------------------------
413 Topology DCN Listener in InterfaceManager does the following:
414 #. Update odl-interface-meta OperDS to have the dpid to bridge
416 #. Retrieve all pre provisioned bridge Interface Entries for this
417 dpn, and add ports to bridge using ovsdb
419 ELAN/VPNManager does a bind service
420 -----------------------------------
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
429 Interface Manager Sequence Diagrams
430 ===================================
432 Following gallery contains sequence diagrams for different IFM
435 Removal of Tunnel Interface When OF Switch is Connected
436 -------------------------------------------------------
438 .. image:: https://wiki.opendaylight.org/images/8/81/Removal_of_Tunnel_Interface_When_OF_Switch_is_Connected.png
440 Removal of Tunnel Interfaces in Pre provisioning Mode
441 -----------------------------------------------------
443 .. image:: https://wiki.opendaylight.org/images/7/7e/Removal_of_Tunnel_Interfaces_in_Pre_provisioning_Mode.png
445 Updating of Tunnel Interfaces in Pre provisioning Mode
446 ------------------------------------------------------
448 .. image:: https://wiki.opendaylight.org/images/5/57/Updating_of_Tunnel_Interfaces_in_Pre_provisioning_Mode.png
450 creation of tunnel-interface when OF switch is connected and PortName already in OperDS
451 ---------------------------------------------------------------------------------------
453 .. image:: https://wiki.opendaylight.org/images/5/5d/Creation_of_tunnel-interface_when_OF_switch_is_connected_and_PortName_already_in_OperDS.png
455 creation of vlan interface in pre provisioning mode
456 ---------------------------------------------------
458 .. image:: https://wiki.opendaylight.org/images/d/d7/Creation_of_vlan_interface_in_pre_provisioning_mode.png
460 creation of vlan interface when switch is connected
461 ---------------------------------------------------
463 .. image:: https://wiki.opendaylight.org/images/b/b4/Creation_of_vlan_interface_when_switch_is_connected.png
465 deletion of vlan interface in pre provisioning mode
466 ---------------------------------------------------
468 .. image:: https://wiki.opendaylight.org/images/9/96/Deletion_of_vlan_interface_in_pre_provisioning_mode.png
470 deletion of vlan interface when switch is connect
471 -------------------------------------------------
473 .. image:: https://wiki.opendaylight.org/images/9/96/Deletion_of_vlan_interface_when_switch_is_connected.png
475 Node connector added updated DCN handling
476 -----------------------------------------
478 .. image:: https://wiki.opendaylight.org/images/c/ce/Node_connector_added_updated_DCN_handling.png
480 Node connector removed DCN handling
481 -----------------------------------
483 .. image:: https://wiki.opendaylight.org/images/3/36/Node_connector_removed_DCN_handling.png
485 updation of vlan interface in pre provisioning mode
486 ---------------------------------------------------
488 .. image:: https://wiki.opendaylight.org/view/File:Updation_of_vlan_interface_in_pre_provisioning_mode.png
490 updation of vlan interface when switch is connect
491 -------------------------------------------------
493 .. image:: https://wiki.opendaylight.org/images/e/e5/Updation_of_vlan_interface_when_switch_is_connected.png