manuals/user-guide/src/main/asciidoc/groupbasedpolicy/odl-groupbasedpolicy-ofoverlay-user-guide.adoc

   1 ==== Overview
   2
   3 The OpenFlow Overlay (OfOverlay) feature enables the OpenFlow Overlay
   4 renderer, which creates a network virtualization solution across nodes
   5 that host OpenvSwitch software switches.
   6
   7 ===== Installing and Pre-requisites
   8
   9 From the karaf console in OpenDaylight:
  10
  11  feature:install odl-groupbasedpolicy-ofoverlay
  12
  13 This renderer is designed to work with OpenVSwitch (OVS) 2.1+ (although 2.3 is strongly recommended) and OpenFlow 1.3.
  14
  15 When used in conjunction with the <<Neutron,Neutron Mapper feature>> no extra OfOverlay specific setup is required.
  16
  17 When this feature is loaded "standalone", the user is required to configure infrastructure, such as
  18
  19 * instantiating OVS bridges,
  20 * attaching hosts to the bridges,
  21 * and creating the VXLAN/VXLAN-GPE tunnel ports on the bridges.
  22
  23 [[offset]]
  24 In Lithium, the *GBP* OfOverlay renderer also supports a table offset option, to offset the pipeline post-table 0
  25
  26 This is set by changing:
  27  <gbp-ofoverlay-table-offset>0</gbp-ofoverlay-table-offset>
  28
  29 in file:
  30 ./distribution-karaf/target/assembly/etc/opendaylight/karaf/15-groupbasedpolicy-ofoverlay.xml
  31
  32 ==== OpenFlow Overlay Architecture
  33
  34 These are the primary components of *GBP*. The OfOverlay components are highlighted in red.
  35
  36 .OfOverlay within *GBP*
  37 image::groupbasedpolicy/ofoverlay-1-components.png[align="center",width=500]
  38
  39 In terms of the inner components of the *GBP* OfOverlay renderer:
  40
  41 .OfOverlay expanded view:
  42 image::groupbasedpolicy/ofoverlay-2-components.png[align="center",width=500]
  43
  44 *OfOverlay Renderer*
  45
  46 Launches components below:
  47
  48 *Policy Resolver*
  49
  50 Policy resolution is completely domain independent, and the OfOverlay leverages process policy information internally. See <<policyresolution,Policy Resolution process>>.
  51
  52 It listens to inputs to the _Tenants_ configuration datastore, validates tenant input, then writes this to the Tenants operational datastore.
  53
  54 From there an internal notification is generated to the PolicyManager.
  55
  56 In the next release, this will be moving to a non-renderer specific location.
  57
  58 *Endpoint Manager*
  59
  60 The endpoint repository, in Lithium, operates in *orchestrated* mode. This means the user is responsible for the provisioning of endpoints via:
  61
  62 * <<UX,UX/GUI>>
  63 * REST API
  64
  65 NOTE: When using the <<Neutron,Neutron mapper>> feature, everything is managed transparently via Neutron.
  66
  67 The Endpoint Manager is responsible for listening to Endpoint repository updates and notifying the Switch Manager when a valid Endpoint has been registered.
  68
  69 It also supplies utility functions to the flow pipeline process.
  70
  71 *Switch Manager*
  72
  73 The Switch Manager has been refactored in Lithium to be purely a state manager.
  74
  75 Switches are in one of 3 states:
  76
  77 * DISCONNECTED
  78 * PREPARING
  79 * READY
  80
  81 *Ready* is denoted by a connected switch:
  82
  83 * having a tunnel interface
  84 * having at least one endpoint connected.
  85
  86 In this way *GBP* is not writing to switches it has no business to.
  87
  88 *Preparing* simply means the switch has a controller connection but is missing one of the above _complete and necessary_ conditions
  89
  90 *Disconnected* means a previously connected switch is no longer present in the Inventory operational datastore.
  91
  92 .OfOverlay Flow Pipeline
  93 image::groupbasedpolicy/ofoverlay-3-flowpipeline.png[align="center",width=500]
  94
  95 The OfOverlay leverages Nicira registers as follows:
  96
  97 * REG0 = Source EndpointGroup + Tenant ordinal
  98 * REG1 = Source Conditions + Tenant ordinal
  99 * REG2 = Destination EndpointGroup + Tenant ordinal
 100 * REG3 = Destination Conditions + Tenant ordinal
 101 * REG4 = Bridge Domain + Tenant ordinal
 102 * REG5 = Flood Domain + Tenant ordinal
 103 * REG6 = Layer 3 Context + Tenant ordinal
 104
 105 *Port Security*
 106
 107 Table 0 of the OpenFlow pipeline. Responsible for ensuring that only valid connections can send packets into the pipeline:
 108
 109  cookie=0x0, <snip> , priority=200,in_port=3 actions=goto_table:2
 110  cookie=0x0, <snip> , priority=200,in_port=1 actions=goto_table:1
 111  cookie=0x0, <snip> , priority=121,arp,in_port=5,dl_src=fa:16:3e:d5:b9:8d,arp_spa=10.1.1.3 actions=goto_table:2
 112  cookie=0x0, <snip> , priority=120,ip,in_port=5,dl_src=fa:16:3e:d5:b9:8d,nw_src=10.1.1.3 actions=goto_table:2
 113  cookie=0x0, <snip> , priority=115,ip,in_port=5,dl_src=fa:16:3e:d5:b9:8d,nw_dst=255.255.255.255 actions=goto_table:2
 114  cookie=0x0, <snip> , priority=112,ipv6 actions=drop
 115  cookie=0x0, <snip> , priority=111, ip actions=drop
 116  cookie=0x0, <snip> , priority=110,arp actions=drop
 117  cookie=0x0, <snip> ,in_port=5,dl_src=fa:16:3e:d5:b9:8d actions=goto_table:2
 118  cookie=0x0, <snip> , priority=1 actions=drop
 119
 120 Ingress from tunnel interface, go to Table _Source Mapper_:
 121
 122  cookie=0x0, <snip> , priority=200,in_port=3 actions=goto_table:2
 123
 124 Ingress from outside, goto Table _Ingress NAT Mapper_:
 125
 126  cookie=0x0, <snip> , priority=200,in_port=1 actions=goto_table:1
 127
 128 ARP from Endpoint, go to Table _Source Mapper_:
 129
 130  cookie=0x0, <snip> , priority=121,arp,in_port=5,dl_src=fa:16:3e:d5:b9:8d,arp_spa=10.1.1.3 actions=goto_table:2
 131
 132 IPv4 from Endpoint, go to Table _Source Mapper_:
 133
 134  cookie=0x0, <snip> , priority=120,ip,in_port=5,dl_src=fa:16:3e:d5:b9:8d,nw_src=10.1.1.3 actions=goto_table:2
 135
 136 DHCP DORA from Endpoint, go to Table _Source Mapper_:
 137
 138  cookie=0x0, <snip> , priority=115,ip,in_port=5,dl_src=fa:16:3e:d5:b9:8d,nw_dst=255.255.255.255 actions=goto_table:2
 139
 140 Series of DROP tables with priority set to capture any non-specific traffic that should have matched above:
 141
 142  cookie=0x0, <snip> , priority=112,ipv6 actions=drop
 143  cookie=0x0, <snip> , priority=111, ip actions=drop
 144  cookie=0x0, <snip> , priority=110,arp actions=drop
 145
 146 "L2" catch all traffic not identified above:
 147
 148  cookie=0x0, <snip> ,in_port=5,dl_src=fa:16:3e:d5:b9:8d actions=goto_table:2
 149
 150 Drop Flow:
 151
 152  cookie=0x0, <snip> , priority=1 actions=drop
 153
 154
 155 *Ingress NAT Mapper*
 156
 157 Table <<offset,_offset_>>+1.
 158
 159 ARP responder for external NAT address:
 160
 161  cookie=0x0, <snip> , priority=150,arp,arp_tpa=192.168.111.51,arp_op=1 actions=move:NXM_OF_ETH_SRC[]->NXM_OF_ETH_DST[],set_field:fa:16:3e:58:c3:dd->eth_src,load:0x2->NXM_OF_ARP_OP[],move:NXM_NX_ARP_SHA[]->NXM_NX_ARP_THA[],load:0xfa163e58c3dd->NXM_NX_ARP_SHA[],move:NXM_OF_ARP_SPA[]->NXM_OF_ARP_TPA[],load:0xc0a86f33->NXM_OF_ARP_SPA[],IN_PORT
 162
 163 Translate from Outside to Inside and perform same functions as SourceMapper.
 164
 165  cookie=0x0, <snip> , priority=100,ip,nw_dst=192.168.111.51 actions=set_field:10.1.1.2->ip_dst,set_field:fa:16:3e:58:c3:dd->eth_dst,load:0x2->NXM_NX_REG0[],load:0x1->NXM_NX_REG1[],load:0x4->NXM_NX_REG4[],load:0x5->NXM_NX_REG5[],load:0x7->NXM_NX_REG6[],load:0x3->NXM_NX_TUN_ID[0..31],goto_table:3
 166
 167 *Source Mapper*
 168
 169 Table <<offset,_offset_>>+2.
 170
 171 Determines based on characteristics from the ingress port, which:
 172
 173 * EndpointGroup(s) it belongs to
 174 * Forwarding context
 175 * Tunnel VNID ordinal
 176
 177 Establishes tunnels at valid destination switches for ingress.
 178
 179 Ingress Tunnel established at remote node with VNID Ordinal that maps to Source EPG, Forwarding Context etc:
 180
 181  cookie=0x0, <snip>, priority=150,tun_id=0xd,in_port=3 actions=load:0xc->NXM_NX_REG0[],load:0xffffff->NXM_NX_REG1[],load:0x4->NXM_NX_REG4[],load:0x5->NXM_NX_REG5[],load:0x7->NXM_NX_REG6[],goto_table:3
 182
 183 Maps endpoint to Source EPG, Forwarding Context based on ingress port, and MAC:
 184
 185  cookie=0x0, <snip> , priority=100,in_port=5,dl_src=fa:16:3e:b4:b4:b1 actions=load:0xc->NXM_NX_REG0[],load:0x1->NXM_NX_REG1[],load:0x4->NXM_NX_REG4[],load:0x5->NXM_NX_REG5[],load:0x7->NXM_NX_REG6[],load:0xd->NXM_NX_TUN_ID[0..31],goto_table:3
 186
 187 Generic drop:
 188
 189  cookie=0x0, duration=197.622s, table=2, n_packets=0, n_bytes=0, priority=1 actions=drop
 190
 191 *Destination Mapper*
 192
 193 Table <<offset,_offset_>>+3.
 194
 195 Determines based on characteristics of the endpoint:
 196
 197 * EndpointGroup(s) it belongs to
 198 * Forwarding context
 199 * Tunnel Destination value
 200
 201 Manages routing based on valid ingress nodes ARP'ing for their default gateway, and matches on either gateway MAC or destination endpoint MAC.
 202
 203 ARP for default gateway for the 10.1.1.0/24 subnet:
 204
 205  cookie=0x0, <snip> , priority=150,arp,reg6=0x7,arp_tpa=10.1.1.1,arp_op=1 actions=move:NXM_OF_ETH_SRC[]->NXM_OF_ETH_DST[],set_field:fa:16:3e:28:4c:82->eth_src,load:0x2->NXM_OF_ARP_OP[],move:NXM_NX_ARP_SHA[]->NXM_NX_ARP_THA[],load:0xfa163e284c82->NXM_NX_ARP_SHA[],move:NXM_OF_ARP_SPA[]->NXM_OF_ARP_TPA[],load:0xa010101->NXM_OF_ARP_SPA[],IN_PORT
 206
 207 Broadcast traffic destined for GroupTable:
 208
 209  cookie=0x0, <snip> , priority=140,reg5=0x5,dl_dst=01:00:00:00:00:00/01:00:00:00:00:00 actions=load:0x5->NXM_NX_TUN_ID[0..31],group:5
 210
 211 Layer3 destination matching flows, where priority=100+masklength. Since *GBP* now support L3Prefix endpoint, we can set default routes etc:
 212
 213  cookie=0x0, <snip>, priority=132,ip,reg6=0x7,dl_dst=fa:16:3e:b4:b4:b1,nw_dst=10.1.1.3 actions=load:0xc->NXM_NX_REG2[],load:0x1->NXM_NX_REG3[],load:0x5->NXM_NX_REG7[],set_field:fa:16:3e:b4:b4:b1->eth_dst,dec_ttl,goto_table:4
 214
 215 Layer2 destination matching flows, designed to be caught only after last IP flow (lowest priority IP flow is 100):
 216
 217  cookie=0x0, duration=323.203s, table=3, n_packets=4, n_bytes=168, priority=50,reg4=0x4,dl_dst=fa:16:3e:58:c3:dd actions=load:0x2->NXM_NX_REG2[],load:0x1->NXM_NX_REG3[],load:0x2->NXM_NX_REG7[],goto_table:4
 218
 219 General drop flow:
 220  cookie=0x0, duration=323.207s, table=3, n_packets=6, n_bytes=588, priority=1 actions=drop
 221
 222 *Policy Enforcer*
 223
 224 Table <<offset,_offset_>>+4.
 225
 226 Once the Source and Destination EndpointGroups are assigned, policy is enforced based on resolved rules.
 227
 228 In the case of <<SFC,Service Function Chaining>>, the encapsulation and destination for traffic destined to a chain, is discovered and enforced.
 229
 230 Policy flow, allowing IP traffic between EndpointGroups:
 231
 232  cookie=0x0, <snip> , priority=64998,ip,reg0=0x8,reg1=0x1,reg2=0xc,reg3=0x1 actions=goto_table:5
 233
 234 *Egress NAT Mapper*
 235
 236 Table <<offset,_offset_>>+5.
 237
 238 Performs NAT function before Egressing OVS instance to the underlay network.
 239
 240 Inside to Outside NAT translation before sending to underlay:
 241
 242  cookie=0x0, <snip> , priority=100,ip,reg6=0x7,nw_src=10.1.1.2 actions=set_field:192.168.111.51->ip_src,goto_table:6
 243
 244 *External Mapper*
 245
 246 Table <<offset,_offset_>>+6.
 247
 248 Manages post-policy enforcement for endpoint specific destination effects. Specifically for <<SFC,Service Function Chaining>>, which is why we can support both symmetric and asymmetric chains
 249 and distributed ingress/egress classification.
 250
 251 Generic allow:
 252
 253  cookie=0x0, <snip>, priority=100 actions=output:NXM_NX_REG7[]
 254
 255 ==== Configuring OpenFlow Overlay via REST
 256
 257 NOTE: Please see the <<UX,UX>> section on how to configure *GBP* via the GUI.
 258
 259 *Endpoint*
 260
 261 ----
 262 POST http://{{controllerIp}}:8181/restconf/operations/endpoint:register-endpoint
 263 {
 264     "input": {
 265         "endpoint-group": "<epg0>",
 266         "endpoint-groups" : ["<epg1>","<epg2>"],
 267         "network-containment" : "<fowarding-model-context1>",
 268         "l2-context": "<bridge-domain1>",
 269         "mac-address": "<mac1>",
 270         "l3-address": [
 271             {
 272                 "ip-address": "<ipaddress1>",
 273                 "l3-context": "<l3_context1>"
 274             }
 275         ],
 276         "*ofoverlay:port-name*": "<ovs port name>",
 277         "tenant": "<tenant1>"
 278     }
 279 }
 280 ----
 281
 282 NOTE: The usage of "port-name" preceded by "ofoverlay". In OpenDaylight, base datastore objects can be _augmented_. In *GBP*, the base endpoint model has no renderer
 283 specifics, hence can be leveraged across multiple renderers.
 284
 285 *OVS Augmentations to Inventory*
 286
 287 ----
 288 PUT http://{{controllerIp}}:8181/restconf/config/opendaylight-inventory:nodes/
 289 {
 290     "opendaylight-inventory:nodes": {
 291         "node": [
 292             {
 293                 "id": "openflow:123456",
 294                 "ofoverlay:tunnel": [
 295                     {
 296                         "tunnel-type": "overlay:tunnel-type-vxlan",
 297                         "ip": "<ip_address_of_ovs>",
 298                         "port": 4789,
 299                         "node-connector-id": "openflow:123456:1"
 300                     }
 301                 ]
 302             },
 303             {
 304                 "id": "openflow:654321",
 305                 "ofoverlay:tunnel": [
 306                     {
 307                         "tunnel-type": "overlay:tunnel-type-vxlan",
 308                         "ip": "<ip_address_of_ovs>",
 309                         "port": 4789,
 310                         "node-connector-id": "openflow:654321:1"
 311                     }
 312                 ]
 313             }
 314         ]
 315     }
 316 }
 317 ----
 318
 319 *Tenants* see <<policyresolution,Policy Resolution>> and <<forwarding,Forwarding Model>> for details:
 320
 321 ----
 322 {
 323   "policy:tenant": {
 324     "contract": [
 325       {
 326         "clause": [
 327           {
 328             "name": "allow-http-clause",
 329             "subject-refs": [
 330               "allow-http-subject",
 331               "allow-icmp-subject"
 332             ]
 333           }
 334         ],
 335         "id": "<id>",
 336         "subject": [
 337           {
 338             "name": "allow-http-subject",
 339             "rule": [
 340               {
 341                 "classifier-ref": [
 342                   {
 343                     "direction": "in",
 344                     "name": "http-dest"
 345                   },
 346                   {
 347                     "direction": "out",
 348                     "name": "http-src"
 349                   }
 350                 ],
 351                 "action-ref": [
 352                   {
 353                     "name": "allow1",
 354                     "order": 0
 355                   }
 356                 ],
 357                 "name": "allow-http-rule"
 358               }
 359             ]
 360           },
 361           {
 362             "name": "allow-icmp-subject",
 363             "rule": [
 364               {
 365                 "classifier-ref": [
 366                   {
 367                     "name": "icmp"
 368                   }
 369                 ],
 370                 "action-ref": [
 371                   {
 372                     "name": "allow1",
 373                     "order": 0
 374                   }
 375                 ],
 376                 "name": "allow-icmp-rule"
 377               }
 378             ]
 379           }
 380         ]
 381       }
 382     ],
 383     "endpoint-group": [
 384       {
 385         "consumer-named-selector": [
 386           {
 387             "contract": [
 388               "<id>"
 389             ],
 390             "name": "<name>"
 391           }
 392         ],
 393         "id": "<id>",
 394         "provider-named-selector": []
 395       },
 396       {
 397         "consumer-named-selector": [],
 398         "id": "<id>",
 399         "provider-named-selector": [
 400           {
 401             "contract": [
 402               "<id>"
 403             ],
 404             "name": "<name>"
 405           }
 406         ]
 407       }
 408     ],
 409     "id": "<id>",
 410     "l2-bridge-domain": [
 411       {
 412         "id": "<id>",
 413         "parent": "<id>"
 414       }
 415     ],
 416     "l2-flood-domain": [
 417       {
 418         "id": "<id>",
 419         "parent": "<id>"
 420       },
 421       {
 422         "id": "<id>",
 423         "parent": "<id>"
 424       }
 425     ],
 426     "l3-context": [
 427       {
 428         "id": "<id>"
 429       }
 430     ],
 431     "name": "GBPPOC",
 432     "subject-feature-instances": {
 433       "classifier-instance": [
 434         {
 435           "classifier-definition-id": "<id>",
 436           "name": "http-dest",
 437           "parameter-value": [
 438             {
 439               "int-value": "6",
 440               "name": "proto"
 441             },
 442             {
 443               "int-value": "80",
 444               "name": "destport"
 445             }
 446           ]
 447         },
 448         {
 449           "classifier-definition-id": "<id>",
 450           "name": "http-src",
 451           "parameter-value": [
 452             {
 453               "int-value": "6",
 454               "name": "proto"
 455             },
 456             {
 457               "int-value": "80",
 458               "name": "sourceport"
 459             }
 460           ]
 461         },
 462         {
 463           "classifier-definition-id": "<id>",
 464           "name": "icmp",
 465           "parameter-value": [
 466             {
 467               "int-value": "1",
 468               "name": "proto"
 469             }
 470           ]
 471         }
 472       ],
 473       "action-instance": [
 474         {
 475           "name": "allow1",
 476           "action-definition-id": "<id>"
 477         }
 478       ]
 479     },
 480     "subnet": [
 481       {
 482         "id": "<id>",
 483         "ip-prefix": "<ip_prefix>",
 484         "parent": "<id>",
 485         "virtual-router-ip": "<ip address>"
 486       },
 487       {
 488         "id": "<id>",
 489         "ip-prefix": "<ip prefix>",
 490         "parent": "<id>",
 491         "virtual-router-ip": "<ip address>"
 492       }
 493     ]
 494   }
 495 }
 496 ----
 497
 498
 499 ==== Tutorials[[Demo]]
 500
 501 Comprehensive tutorials, along with a demonstration environment leveraging Vagrant
 502 can be found on the https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)[*GBP* wiki]
 503