docs/specs/service-binding-on-tunnels.rst

   1
   2 .. contents:: Table of Contents
   3       :depth: 3
   4
   5 ==========================
   6 Service Binding On Tunnels
   7 ==========================
   8
   9 https://git.opendaylight.org/gerrit/#/q/topic:service-binding-on-tunnels
  10
  11 Service Binding On Tunnels Feature enables applications to bind multiple services on
  12 an ingress/egress tunnel.
  13
  14
  15 Problem description
  16 ===================
  17
  18 Currently GENIUS does not provide a generic mechanism to support binding services on all
  19 interfaces.Ingress service binding pipeline is different for l2vlan interfaces and tunnel
  20 interfaces.Similarly, egress Service Binding is only supported for l2vlan interfaces.
  21
  22 Today when ingress services are bound on a tunnel, the highest priority service gets
  23 bound in ``INTERFACE INGRESS TABLE(0)`` itself, and remaining service entries get
  24 populated in ``LPORT DISPATCHER TABLE(17)``, which is not in alignment with the service
  25 binding logic for VM ports. As part of this feature, we enable ingress/egress service
  26 binding support for tunnels in the same way as for VM interfaces. This feature also enables
  27 service-binding based on a tunnel-type which is basically meant for optimizing the number
  28 of flow entries in dispatcher tables.
  29
  30 Use Cases
  31 ---------
  32
  33 This feature will support following use cases:
  34
  35 * Use case 1: IFM should support binding services based on tunnel type.
  36 * Use case 2: All application traffic ingressing on a tunnel should go through the ``LPORT
  37   DISPATCHER TABLE(17)``.
  38 * Use case 3: IFM should support binding multiple ingress services on tunnels.
  39 * Use case 4: IFM should support priority based ingress service handling for tunnels.
  40 * Use case 5: IFM should support unbinding ingress services on tunnels.
  41 * Use case 6: IFM should support binding multiple egress services on tunnels.
  42 * Use case 7: IFM should support priority based egress service handling for tunnels.
  43 * Use case 8: All application traffic egressing on a tunnel should go through the egress
  44   dispatcher table(220).
  45 * Use case 9: Datapath should be intact even if there is no egress service bound on the tunnel.
  46 * Use case 10: IFM should support unbinding egress services on tunnels.
  47 * Use case 11: IFM should support handling of lower layer interface deletions gracefully.
  48 * Use case 12: IFM should support binding services based on tunnel type and
  49   lport-tag on the same tunnel interface on a priority basis.
  50 * Use case 13: Applications should bind on specific tunnel types on module startup
  51 * Use case 13: IFM should take care of programming the tunnel type based binding flows
  52   on each DPN.
  53
  54 Following use cases will not be supported:
  55
  56 * Use case 1 : Update of service binding on tunnels. Any update should be done as
  57   delete and re-create
  58
  59 Proposed change
  60 ===============
  61
  62 The proposed change extends the current l2vlan service binding functionality to tunnel
  63 interfaces. With this feature, multiple applications can bind their services on the same
  64 tunnel interface, and traffic will be processed on an application priority basis.
  65 Applications are given the flexibility to provide service specific actions while they
  66 bind their services. Normally service binding actions include
  67 *go-to-service-pipeline-entry-table*. Packets will enter a particular service based
  68 on the service priority, and if the packet is not consumed by the service,
  69 it is the application's responsibility to resubmit the packet back to the ``egress/ingress
  70 dispatcher table`` for further processing by next priority service. Egress Dispatcher
  71 Table will have a default service priority entry per tunnel interface to egress the
  72 packet on the tunnel port.So, if there are no egress services bound on a tunnel interface,
  73 this default entry will take care of taking the packet out of the switch.
  74
  75 The feature also enables service binding based on tunnel type. This way number of entries in
  76 Dispatcher Tables can be optimized if all the packets entering on tunnel of a particular type
  77 needs to be handled in the same way.
  78
  79
  80 Pipeline changes
  81 ----------------
  82 There is a pipeline change introduced as part of this feature for tunnel egress as well
  83 as ingress, and is captured in genius pipeline document patch [2]_.
  84
  85 With this feature, all traffic from INTERFACE_INGRESS_TABLE(0) will be dispatched to
  86 LPORT_DISPATCHER_TABLE(17), from where the packets will be dispatched to the respective
  87 applications on a priority basis.
  88
  89 Register6 will be used to set the ingress tunnel-type in Table0, and this can be used to
  90 match in Table17 to identify the respective applications bound on the tunnel-type.
  91 Remaining logic of ingress service binding will remain as is, and service-priority and
  92 interface-tag will be set in metadata as usual. The bits from 25-28 of Register6 will be
  93 used to indicate tunnel-type.
  94
  95 After the ingress service processing, packets which are identified to be egressed on
  96 tunnel interfaces, currently directly go to the tunnel port. With this feature,
  97 these packets will goto Egress Dispatcher Table[Table 220] first, where the packet will be
  98 processed by Egress Services on the tunnel interface one by one, and finally will egress the switch.
  99
 100 Register6 will be used to indicate service priority as well as interface tag for the egress tunnel
 101 interface, in Egress Dispatcher Table, and when there are N services bound on a tunnel
 102 interface, there will be N+1 entries in Egress Dispatcher Table,
 103 the additional one for the default tunnel entry. The first 4 bits of Register6 will be
 104 used to indicate the service priority and the next 20 bits for interface Tag, and this will
 105 be the match criteria for packet redirection to service pipeline in Egress Dispatcher Table.
 106 Before sending the packet to the service, Egress Dispatcher Table will set the service index
 107 to the next service' priority. Same as ingress, Register6 will be used for egress tunnel-type
 108 matching, if there are services bound on tunnel-type.
 109
 110 +-------------------------+---------------------------+----------------------------------+
 111 | TABLE                   | MATCH                     |            ACTION                |
 112 +=========================+===========================+==================================+
 113 |                         |  in_port                  |  SI=0,reg6=interface_type,       |
 114 | INTERFACE_INGRESS_TABLE |                           |  metadata=lport tag,             |
 115 |                         |                           |  goto table 17                   |
 116 +-------------------------+---------------------------+----------------------------------+
 117 | LPORT_DISPATCHER_TABLE  | metadata=service priority |  increment SI,                   |
 118 |                         | && lport-tag(priority=10) |  apply service specific actions, |
 119 |                         |                           |  goto ingress service            |
 120 |                         +---------------------------+----------------------------------+
 121 |                         | reg6=tunnel-type          |  increment SI,                   |
 122 |                         | priority=5                |  apply service specific actions, |
 123 |                         |                           |  goto ingress service            |
 124 +-------------------------+---------------------------+----------------------------------+
 125 | EGRESS_DISPATCHER_TABLE | Reg6==service Priority    |  increment SI,                   |
 126 |                         | && lport-tag(priority=10) |  apply service specific actions, |
 127 |                         |                           |  goto egress service             |
 128 |                         +---------------------------+----------------------------------+
 129 |                         | reg6=tunnel-type          |  increment SI,                   |
 130 |                         | priority=5                |  apply service specific actions, |
 131 |                         |                           |  goto egress service             |
 132 +-------------------------+---------------------------+----------------------------------+
 133
 134 RPC Changes
 135 -----------
 136
 137 ``GetEgressActionsForInterface`` RPC in interface-manager currently returns the output:port
 138 action for tunnel interfaces. This will be changed to return
 139 set_field_reg6(default-service-index + interface-tag) and resubmit(egress_dispatcher_table).
 140
 141 Yang changes
 142 ------------
 143
 144 No yang changes are needed, as binding on tunnel-type is enabled by having reserved keywords for
 145 interface-names
 146
 147 Workflow
 148 --------
 149
 150 Create Tunnel
 151 ^^^^^^^^^^^^^
 152 #. User: User created a tunnel end point
 153 #. IFM:  When tunnel port is created on OVS, and the respective OpenFlow port Notification
 154    comes, IFM binds a default service in Egress Dispatcher Table for the tunnel interface,
 155    which will be the least priority service, and the action will be to take
 156    the packet out on the tunnel port.
 157
 158 Bind Service on Tunnel Interface
 159 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 160
 161 #. User: While binding service on tunnels user gives ``service-priority``, ``service-mode``
 162    and ``instructions`` for service being bound on the tunnel interface.
 163 #. IFM: When binding the service for the tunnel, if this is the first service
 164    being bound, program flow rules in Dispatcher Table(ingress/egress based on service mode)
 165    to match on ``service-priority`` and ``interface-tag`` value with actions
 166    pointing to the service specific actions supplied by the application.
 167 #. IFM: When binding a second service, based on the service priority one more flow will
 168    be created in Dispatcher Table with matches specific to the new service
 169    priority.
 170
 171 Unbind Service on Tunnel Interface
 172 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 173
 174 #. User: While unbinding service on tunnels user gives ``service-priority`` and
 175    ``service-mode`` for service being unbound on the tunnel interface.
 176 #. IFM: When unbinding the service for the tunnel, IFM removes the entry in
 177    Dispatcher Tables for the service. IFM also rearranges the remaining flows for the
 178    same tunnel interface to adjust the missing service priority
 179
 180 Bind Service on Tunnel Type
 181 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 182
 183 #. Application: While binding service on tunnel type user gives a reserved keyword
 184    indicating the tunnel-type apart from``service-priority``, ``service-mode``
 185    and ``instructions`` for service being bound. The reserved keywords will be
 186    ``ALL_VXLAN_INTERNAL``, ``ALL_VXLAN_EXTERNAL``, and ``ALL_MPLS_OVER_GRE``.
 187 #. IFM: When binding the service for the tunnel-type,program flow rules in Dispatcher
 188    Table(ingress/egress based on service mode) to match on ``service-priority`` and
 189    ``tunnel-type`` value with actions pointing to the service specific actions
 190    supplied by the application will be created on each DPN.
 191 #. IFM: When binding a second service, based on the service priority one more flow will
 192    be created in Dispatcher Table with matches specific to the new service
 193    priority will be created on each DPN..
 194
 195 Unbind Service on Tunnel Type
 196 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 197
 198 #. User: While unbinding service on tunnels user gives a reserved keyword
 199    indicating the tunnel-type ,``service-priority`` and ``service-mode`` for service being
 200    unbound on all connected DPNs.
 201 #. IFM: When unbinding the service for the tunnel-type, IFM removes the entry in
 202    Dispatcher Tables for the service. IFM also rearranges the remaining flows for the
 203    same tunnel type to adjust the missing service priority
 204
 205 Delete Tunnel
 206 ^^^^^^^^^^^^^
 207 #. User: User deleted a tunnel end point
 208 #. IFM:  When tunnel port is deleted on OVS, and the respective OpenFlow Port Notification
 209    comes, IFM unbinds the default service in Egress Dispatcher Table for the tunnel interface.
 210 #. IFM:  If there are any outstanding services bound on the tunnel interface, all the Dispatcher
 211    Table Entries for this Tunnel will be deleted by IFM.
 212
 213 Application Module Startup
 214 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 215
 216 #. Applications:  When Application bundle comes up, they can bind respective applications
 217    on the tunnel types they are interested in, with their respective service priorities.
 218
 219 Configuration impact
 220 ---------------------
 221 This change doesn't add or modify any configuration parameters.
 222
 223 Clustering considerations
 224 -------------------------
 225 The solution is supported on a 3-node cluster.
 226
 227 Other Infra considerations
 228 --------------------------
 229 N.A.
 230
 231 Security considerations
 232 -----------------------
 233 N.A.
 234
 235 Scale and Performance Impact
 236 ----------------------------
 237 * The feature adds one extra transaction during tunnel port creation, since the default
 238   Egress Dispatcher Table entry has to be programmed for each tunnel.
 239 * The feature provides support for service-binding on tunnel type with the primary purpose
 240   of minimizing the number of flow entries in ingress/egress dispatcher tables.
 241
 242 Targeted Release
 243 -----------------
 244 Carbon.
 245
 246 Alternatives
 247 ------------
 248 N/A
 249
 250 Usage
 251 =====
 252
 253 Features to Install
 254 -------------------
 255 This feature doesn't add any new karaf feature.Installing any of the below features
 256 can enable the service:
 257
 258 odl-genius-ui
 259 odl-genius-rest
 260 odl-genius
 261
 262 REST API
 263 --------
 264
 265 Creating tunnel-interface directly in IFM
 266 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 267
 268 This use case is mainly for those who want to write applications using Genius and/or
 269 want to create individual tunnel interfaces. Note that this is a simpler easy way to
 270 create tunnels without needing to delve into how OVSDB Plugin creates tunnels.
 271
 272 Refer `Genius User Guide [4]_`
 273 for more details on this.
 274
 275 **URL:** restconf/config/ietf-interfaces:interfaces
 276
 277 **Sample JSON data**
 278
 279 .. code-block:: json
 280
 281    {
 282     "interfaces": {
 283     "interface": [
 284         {
 285             "name": "vxlan_tunnel",
 286             "type": "iana-if-type:tunnel",
 287             "odl-interface:tunnel-interface-type": "odl-interface:tunnel-type-vxlan",
 288             "odl-interface:datapath-node-identifier": "1",
 289             "odl-interface:tunnel-source": "192.168.56.101",
 290             "odl-interface:tunnel-destination": "192.168.56.102",
 291             "odl-interface:monitor-enabled": false,
 292             "odl-interface:monitor-interval": 10000,
 293             "enabled": true
 294         }
 295      ]
 296     }
 297    }
 298
 299 Binding Egress Service On Tunnels
 300 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 301
 302 **URL:** http://localhost:8181/restconf/config/interface-service-bindings:service-bindings/services-info/{tunnel-interface-name}/interface-service-bindings:service-mode-egress
 303
 304 **Sample JSON data**
 305
 306 .. code-block:: json
 307
 308    {
 309       "bound-services": [
 310         {
 311           "service-name": "service1",
 312           "flow-priority": "5",
 313           "service-type": "service-type-flow-based",
 314           "instruction": [
 315            {
 316             "order": 1,
 317             "go-to-table": {
 318                "table_id": 88
 319              }
 320            }],
 321           "service-priority": "2",
 322           "flow-cookie": "1"
 323         }
 324       ]
 325    }
 326
 327
 328 CLI
 329 ---
 330 N.A.
 331
 332
 333 Implementation
 334 ==============
 335
 336 Assignee(s)
 337 -----------
 338 Primary assignee:
 339   Faseela K
 340
 341
 342 Work Items
 343 ----------
 344
 345 #. Create Table 0 tunnel entries to set tunnel-type and lport_tag and
 346    point to ``LPORT_DISPATCHER_TABLE``
 347 #. Support of reserved keyword in interface-names for tunnel type based
 348    service binding.
 349 #. Program tunnel-type based service binding flows on DPN connect events.
 350 #. Program Lport Dispatcher Flows(17) on bind service
 351 #. Remove Lport Dispatcher Flows(17) on unbind service
 352 #. Handle multiple service bind/unbind on tunnel interface
 353 #. Create default Egress Service for Tunnel on Tunnel Creation
 354 #. Add ``set_field_reg_6`` and ``resubmit(220)`` action to actions returned in
 355    ``getEgressActionsForInterface()`` for Tunnels.
 356 #. Program Egress Dispatcher Table(220) Flows on bind service
 357 #. Remove Egress Dispatcher Table(220) Flows on unbind service
 358 #. Handle multiple egress service bind/unbind on tunnel interface
 359 #. Delete default Egress Service for Tunnel on Tunnel Deletion
 360 #. Add UTs.
 361 #. Add CSIT.
 362 #. Add Documentation
 363
 364 #. Trello Card : https://trello.com/c/S8lNGd9S/6-service-binding-on-tunnel-interfaces
 365
 366 Dependencies
 367 ============
 368 Genius, Netvirt
 369
 370 There will be several impacts on netvirt pipeline with this change. A brief overview
 371 is given in the table below:
 372
 373 +-------------------------+-------------+-------------+--------------------------+
 374 | RESERVED_INTERFACE_NAME | TUNNEL_TYPE | APPLICATION | DISPATCHER RULES         |
 375 +=========================+=============+=============+==========================+
 376 | ALL_VXLAN_INTERNAL      |  OVS - OVS  |  ELAN       |  SI=1, reg6=vxlan_int,   |                     |
 377 |                         |             |             |  goto table 38           |
 378 +-------------------------+-------------+-------------+--------------------------+
 379 | ALL_VXLAN_EXTERNAL      |  OVS - TOR  |  DHCP       |  SI=0, reg6=vxlan_ext,   |
 380 |                         |             |             |  goto table 18           |
 381 |                         +-------------+-------------+--------------------------+
 382 |                         |  OVS - DCGW |  EVPN       |  SI=1, reg6=vxlan_ext,   |
 383 |                         |             |             |  goto table 38           |
 384 |                         +-------------+-------------+--------------------------+
 385 |                         |  OVS - TOR  |   ELAN      |  SI=2,reg6=vxlan_ext,    |
 386 |                         |             |             |  goto table 38           |
 387 +-------------------------+-------------+-------------+--------------------------+
 388 | ALL_MPLS_OVER_GRE       |  OVS - DCGW |  L3VPN      |  SI=0, reg6=mpls_o_gre,  |
 389 |                         |             |             |  goto table 20           |
 390 +-------------------------+-------------+-------------+--------------------------+
 391
 392
 393 Testing
 394 =======
 395 Capture details of testing that will need to be added.
 396
 397 Unit Tests
 398 ----------
 399 New junits will be added to InterfaceManagerConfigurationTest to cover the following :
 400
 401 #. Bind/Unbind single ingress service on tunnel-type
 402 #. Bind/Unbind single egress service on tunnel-type
 403 #. Bind single ingress service on tunnel-interface
 404 #. Unbind single ingress service on tunnel-interface
 405 #. Bind multiple ingress services on tunnel in priority order
 406 #. Unbind multiple ingress services on tunnel in priority order
 407 #. Bind multiple ingress services out of priority order
 408 #. Unbind multiple ingress services out of priority order
 409 #. Delete tunnel port to check if ingress dispatcher flows for bound services get deleted
 410 #. Add tunnel port back to check if ingress dispatcher flows for bound services get added back
 411 #. Bind single egress service on tunnel
 412 #. Unbind single egress service on tunnel
 413 #. Bind multiple egress services on tunnel in priority order
 414 #. Unbind multiple egress services on tunnel in priority order
 415 #. Bind multiple egress services out of priority order
 416 #. Unbind multiple egress services out of priority order
 417 #. Delete tunnel port to check if egress dispatcher flows for bound services get deleted
 418 #. Add tunnel port back to check if egress dispatcher flows for bound services get added back
 419
 420 Integration Tests
 421 -----------------
 422
 423 CSIT
 424 ----
 425 The following TCs should be added to CSIT to cover this feature:
 426
 427 #. Bind/Unbind single ingress/egress service on tunnel-type to see the corresponding
 428    table entries are created in switch.
 429 #. Bind single ingress service on tunnel to see the corresponding table entries
 430    are created in switch.
 431 #. Unbind single ingress service on tunnel to see the corresponding table entries
 432    are deleted in switch.
 433 #. Bind multiple ingress services on tunnel in priority order to see if metadata
 434    changes are proper on the flow table.
 435 #. Unbind multiple ingress services on tunnel in priority order to see if metadata
 436    changes are proper on the flow table on each unbind.
 437 #. Bind multiple ingress services out of priority order to see if metadata
 438    changes are proper on the flow table.
 439 #. Unbind multiple ingress services out of priority order.
 440 #. Delete tunnel port to check if ingress dispatcher flows for bound services get deleted.
 441 #. Add tunnel port back to check if ingress dispatcher flows for bound services get added back.
 442 #. Bind single egress service on tunnel to see the corresponding table entries
 443    are created in switch.
 444 #. Unbind single egress service on tunnel to see the corresponding table entries
 445    are deleted in switch.
 446 #. Bind multiple egress services on tunnel in priority order to see if metadata
 447    changes are proper on the flow table.
 448 #. Unbind multiple egress services on tunnel in priority order to see if metadata
 449    changes are proper on the flow table on each unbind.
 450 #. Bind multiple egress services out of priority order to see if metadata
 451    changes are proper on the flow table.
 452 #. Unbind multiple egress services out of priority order.
 453 #. Delete tunnel port to check if egress dispatcher flows for bound services get deleted.
 454 #. Add tunnel port back to check if egress dispatcher flows for bound services get added back.
 455
 456
 457 Documentation Impact
 458 ====================
 459 This will require changes to User Guide and Developer Guide.
 460
 461 There is a pipeline change for tunnel datapath introduced due to this change.
 462 This should go in User Guide.
 463
 464 Developer Guide should capture how to configure egress service binding on tunnels.
 465
 466
 467 References
 468 ==========
 469 .. [#] Genius Carbon Release Plan https://wiki.opendaylight.org/view/Genius:Carbon_Release_Plan
 470 .. [#] Netvirt Pipeline Diagram http://docs.opendaylight.org/en/latest/submodules/genius/docs/pipeline.html
 471 .. [#] Genius Trello Card https://trello.com/c/S8lNGd9S/6-service-binding-on-tunnel-interfaces
 472 .. [#] Genius User Guide http://docs.opendaylight.org/en/latest/user-guide/genius-user-guide.html#creating-overlay-tunnel-interfaces
 473
 474 .. note::
 475
 476   This template was derived from [2], and has been modified to support our project.
 477
 478   This work is licensed under a Creative Commons Attribution 3.0 Unported License.
 479   http://creativecommons.org/licenses/by/3.0/legalcode