1ovn-architecture(7)               OVN Manual               ovn-architecture(7)
2
3
4

NAME

6       ovn-architecture - Open Virtual Network architecture
7

DESCRIPTION

9       OVN,  the  Open Virtual Network, is a system to support logical network
10       abstraction in virtual machine and container environments. OVN  comple‐
11       ments  the existing capabilities of OVS to add native support for logi‐
12       cal network abstractions, such as logical L2 and L3 overlays and  secu‐
13       rity  groups.  Services  such as DHCP are also desirable features. Just
14       like OVS, OVN’s design goal is to have a production-quality implementa‐
15       tion that can operate at significant scale.
16
17       A  physical  network comprises physical wires, switches, and routers. A
18       virtual network extends a physical network into a  hypervisor  or  con‐
19       tainer  platform, bridging VMs or containers into the physical network.
20       An OVN logical network is a network implemented in software that is in‐
21       sulated  from  physical (and thus virtual) networks by tunnels or other
22       encapsulations. This allows IP and other address spaces used in logical
23       networks  to overlap with those used on physical networks without caus‐
24       ing conflicts. Logical network topologies can be arranged  without  re‐
25       gard  for  the  topologies  of the physical networks on which they run.
26       Thus, VMs that are part of a logical network can migrate from one phys‐
27       ical  machine  to  another without network disruption. See Logical Net‐
28       works, below, for more information.
29
30       The encapsulation layer prevents VMs and containers connected to a log‐
31       ical  network  from  communicating with nodes on physical networks. For
32       clustering VMs and containers, this can be acceptable  or  even  desir‐
33       able,  but  in  many  cases  VMs and containers do need connectivity to
34       physical networks. OVN provides multiple forms  of  gateways  for  this
35       purpose. See Gateways, below, for more information.
36
37       An OVN deployment consists of several components:
38
39              •      A  Cloud Management System (CMS), which is OVN’s ultimate
40                     client (via its users and administrators).  OVN  integra‐
41                     tion  requires  installing  a CMS-specific plugin and re‐
42                     lated software (see below). OVN initially  targets  Open‐
43                     Stack as CMS.
44
45                     We  generally  speak  of ``the’’ CMS, but one can imagine
46                     scenarios in which multiple CMSes manage different  parts
47                     of an OVN deployment.
48
49              •      An OVN Database physical or virtual node (or, eventually,
50                     cluster) installed in a central location.
51
52              •      One or more (usually many) hypervisors. Hypervisors  must
53                     run Open vSwitch and implement the interface described in
54                     Documentation/topics/integration.rst in the Open  vSwitch
55                     source  tree.  Any  hypervisor platform supported by Open
56                     vSwitch is acceptable.
57
58              •      Zero or more gateways. A gateway extends  a  tunnel-based
59                     logical  network  into a physical network by bidirection‐
60                     ally forwarding packets between tunnels  and  a  physical
61                     Ethernet  port.  This  allows non-virtualized machines to
62                     participate in logical networks. A gateway may be a phys‐
63                     ical  host,  a virtual machine, or an ASIC-based hardware
64                     switch that supports the vtep(5) schema.
65
66                     Hypervisors and gateways are  together  called  transport
67                     node or chassis.
68
69       The  diagram  below  shows  how the major components of OVN and related
70       software interact. Starting at the top of the diagram, we have:
71
72              •      The Cloud Management System, as defined above.
73
74              •      The OVN/CMS Plugin is the component of the CMS  that  in‐
75                     terfaces  to OVN. In OpenStack, this is a Neutron plugin.
76                     The plugin’s main purpose is to translate the  CMS’s  no‐
77                     tion  of  logical  network  configuration,  stored in the
78                     CMS’s configuration database in  a  CMS-specific  format,
79                     into an intermediate representation understood by OVN.
80
81                     This  component  is  necessarily  CMS-specific,  so a new
82                     plugin needs to be developed for each CMS that  is  inte‐
83                     grated  with OVN. All of the components below this one in
84                     the diagram are CMS-independent.
85
86              •      The OVN Northbound  Database  receives  the  intermediate
87                     representation  of  logical  network configuration passed
88                     down by the OVN/CMS Plugin. The database schema is  meant
89                     to  be  ``impedance matched’’ with the concepts used in a
90                     CMS, so that it  directly  supports  notions  of  logical
91                     switches, routers, ACLs, and so on. See ovn-nb(5) for de‐
92                     tails.
93
94                     The OVN Northbound Database has  only  two  clients:  the
95                     OVN/CMS Plugin above it and ovn-northd below it.
96
97ovn-northd(8)  connects  to  the  OVN Northbound Database
98                     above it and the OVN Southbound  Database  below  it.  It
99                     translates  the logical network configuration in terms of
100                     conventional network concepts, taken from the OVN  North‐
101                     bound  Database,  into  logical datapath flows in the OVN
102                     Southbound Database below it.
103
104              •      The OVN Southbound Database is the center of the  system.
105                     Its  clients  are  ovn-northd(8)  above  it  and ovn-con‐
106                     troller(8) on every transport node below it.
107
108                     The OVN Southbound Database contains three kinds of data:
109                     Physical  Network  (PN)  tables that specify how to reach
110                     hypervisor and other nodes, Logical Network  (LN)  tables
111                     that  describe  the logical network in terms of ``logical
112                     datapath flows,’’ and Binding tables  that  link  logical
113                     network  components’  locations  to the physical network.
114                     The hypervisors populate the PN and Port_Binding  tables,
115                     whereas ovn-northd(8) populates the LN tables.
116
117                     OVN  Southbound  Database performance must scale with the
118                     number of transport nodes. This will likely require  some
119                     work  on  ovsdb-server(1)  as  we  encounter bottlenecks.
120                     Clustering for availability may be needed.
121
122       The remaining components are replicated onto each hypervisor:
123
124ovn-controller(8) is OVN’s agent on each  hypervisor  and
125                     software  gateway.  Northbound,  it  connects  to the OVN
126                     Southbound Database to learn about OVN configuration  and
127                     status  and to populate the PN table and the Chassis col‐
128                     umn in Binding table with the hypervisor’s status. South‐
129                     bound, it connects to ovs-vswitchd(8) as an OpenFlow con‐
130                     troller, for control over network traffic, and to the lo‐
131                     cal  ovsdb-server(1)  to  allow it to monitor and control
132                     Open vSwitch configuration.
133
134ovs-vswitchd(8) and ovsdb-server(1) are conventional com‐
135                     ponents of Open vSwitch.
136
137                                         CMS
138                                          |
139                                          |
140                              +-----------|-----------+
141                              |           |           |
142                              |     OVN/CMS Plugin    |
143                              |           |           |
144                              |           |           |
145                              |   OVN Northbound DB   |
146                              |           |           |
147                              |           |           |
148                              |       ovn-northd      |
149                              |           |           |
150                              +-----------|-----------+
151                                          |
152                                          |
153                                +-------------------+
154                                | OVN Southbound DB |
155                                +-------------------+
156                                          |
157                                          |
158                       +------------------+------------------+
159                       |                  |                  |
160         HV 1          |                  |    HV n          |
161       +---------------|---------------+  .  +---------------|---------------+
162       |               |               |  .  |               |               |
163       |        ovn-controller         |  .  |        ovn-controller         |
164       |         |          |          |  .  |         |          |          |
165       |         |          |          |     |         |          |          |
166       |  ovs-vswitchd   ovsdb-server  |     |  ovs-vswitchd   ovsdb-server  |
167       |                               |     |                               |
168       +-------------------------------+     +-------------------------------+
169
170
171   Information Flow in OVN
172       Configuration  data  in OVN flows from north to south. The CMS, through
173       its  OVN/CMS  plugin,  passes  the  logical  network  configuration  to
174       ovn-northd  via  the  northbound database. In turn, ovn-northd compiles
175       the configuration into a lower-level form and passes it to all  of  the
176       chassis via the southbound database.
177
178       Status information in OVN flows from south to north. OVN currently pro‐
179       vides only a few forms of status information. First,  ovn-northd  popu‐
180       lates  the  up column in the northbound Logical_Switch_Port table: if a
181       logical port’s chassis column in the southbound Port_Binding  table  is
182       nonempty,  it  sets up to true, otherwise to false. This allows the CMS
183       to detect when a VM’s networking has come up.
184
185       Second, OVN provides feedback to the CMS on the realization of its con‐
186       figuration,  that is, whether the configuration provided by the CMS has
187       taken effect. This feature requires the CMS to  participate  in  a  se‐
188       quence number protocol, which works the following way:
189
190              1.  When  the  CMS  updates  the configuration in the northbound
191                  database, as part of the same transaction, it increments the
192                  value  of the nb_cfg column in the NB_Global table. (This is
193                  only necessary if the CMS wants to know when the  configura‐
194                  tion has been realized.)
195
196              2.  When  ovn-northd  updates the southbound database based on a
197                  given snapshot of the northbound database, it copies  nb_cfg
198                  from  northbound  NB_Global  into  the  southbound  database
199                  SB_Global table, as part of the same transaction. (Thus,  an
200                  observer  monitoring  both  databases can determine when the
201                  southbound database is caught up with the northbound.)
202
203              3.  After ovn-northd receives confirmation from  the  southbound
204                  database  server that its changes have committed, it updates
205                  sb_cfg in the northbound NB_Global table to the nb_cfg  ver‐
206                  sion  that  was  pushed  down. (Thus, the CMS or another ob‐
207                  server can determine when the southbound database is  caught
208                  up without a connection to the southbound database.)
209
210              4.  The  ovn-controller process on each chassis receives the up‐
211                  dated southbound database, with  the  updated  nb_cfg.  This
212                  process  in turn updates the physical flows installed in the
213                  chassis’s Open vSwitch instances. When it receives confirma‐
214                  tion from Open vSwitch that the physical flows have been up‐
215                  dated, it updates nb_cfg in its own Chassis  record  in  the
216                  southbound database.
217
218              5.  ovn-northd  monitors the nb_cfg column in all of the Chassis
219                  records in the southbound database. It keeps  track  of  the
220                  minimum  value  among all the records and copies it into the
221                  hv_cfg column in the northbound NB_Global table. (Thus,  the
222                  CMS or another observer can determine when all of the hyper‐
223                  visors have caught up to the northbound configuration.)
224
225   Chassis Setup
226       Each chassis in an OVN deployment  must  be  configured  with  an  Open
227       vSwitch  bridge dedicated for OVN’s use, called the integration bridge.
228       System startup  scripts  may  create  this  bridge  prior  to  starting
229       ovn-controller  if desired. If this bridge does not exist when ovn-con‐
230       troller starts, it will be created automatically with the default  con‐
231       figuration  suggested  below.  The  ports on the integration bridge in‐
232       clude:
233
234              •      On any chassis, tunnel ports that OVN  uses  to  maintain
235                     logical  network  connectivity.  ovn-controller adds, up‐
236                     dates, and removes these tunnel ports.
237
238              •      On a hypervisor, any VIFs that are to be attached to log‐
239                     ical  networks.  For instances connected through software
240                     emulated ports such as TUN/TAP or VETH pairs, the  hyper‐
241                     visor  itself  will  normally  create ports and plug them
242                     into the  integration  bridge.  For  instances  connected
243                     through  representor  ports, typically used with hardware
244                     offload, the ovn-controller may on CMS direction  consult
245                     a  VIF plug provider for representor port lookup and plug
246                     them into the integration bridge (please refer  to  Docu‐
247                     mentation/top‐
248                     ics/vif-plug-providers/vif-plug-providers.rst
249                      for more information). In both cases the conventions de‐
250                     scribed  in  Documentation/topics/integration.rst  in the
251                     Open vSwitch source tree is followed  to  ensure  mapping
252                     between  OVN  logical port and VIF. (This is pre-existing
253                     integration work that has already been done  on  hypervi‐
254                     sors that support OVS.)
255
256              •      On  a gateway, the physical port used for logical network
257                     connectivity. System startup scripts add this port to the
258                     bridge  prior  to  starting ovn-controller. This can be a
259                     patch port to another bridge, instead of a physical port,
260                     in more sophisticated setups.
261
262       Other  ports  should not be attached to the integration bridge. In par‐
263       ticular, physical ports attached to the underlay network (as opposed to
264       gateway  ports,  which are physical ports attached to logical networks)
265       must not be attached to the integration bridge. Underlay physical ports
266       should instead be attached to a separate Open vSwitch bridge (they need
267       not be attached to any bridge at all, in fact).
268
269       The integration bridge should be configured as described below. The ef‐
270       fect    of    each    of    these    settings    is    documented    in
271       ovs-vswitchd.conf.db(5):
272
273              fail-mode=secure
274                     Avoids switching packets between  isolated  logical  net‐
275                     works  before  ovn-controller  starts  up. See Controller
276                     Failure Settings in ovs-vsctl(8) for more information.
277
278              other-config:disable-in-band=true
279                     Suppresses in-band  control  flows  for  the  integration
280                     bridge.  It  would  be  unusual for such flows to show up
281                     anyway, because OVN uses a local controller (over a  Unix
282                     domain  socket) instead of a remote controller. It’s pos‐
283                     sible, however, for some other bridge in the same  system
284                     to  have  an  in-band remote controller, and in that case
285                     this suppresses the flows that in-band control would  or‐
286                     dinarily  set up. Refer to the documentation for more in‐
287                     formation.
288
289       The customary name for the integration bridge is  br-int,  but  another
290       name may be used.
291
292   Logical Networks
293       Logical  network  concepts  in OVN include logical switches and logical
294       routers, the logical version of Ethernet switches and IP  routers,  re‐
295       spectively.  Like  their physical cousins, logical switches and routers
296       can be connected into sophisticated topologies.  Logical  switches  and
297       routers  are  ordinarily purely logical entities, that is, they are not
298       associated or bound to any physical location, and they are  implemented
299       in a distributed manner at each hypervisor that participates in OVN.
300
301       Logical  switch ports (LSPs) are points of connectivity into and out of
302       logical switches. There are many kinds of  logical  switch  ports.  The
303       most  ordinary  kind represent VIFs, that is, attachment points for VMs
304       or containers. A VIF logical port is associated with the physical loca‐
305       tion  of  its VM, which might change as the VM migrates. (A VIF logical
306       port can be associated with a VM that is  powered  down  or  suspended.
307       Such a logical port has no location and no connectivity.)
308
309       Logical  router ports (LRPs) are points of connectivity into and out of
310       logical routers. A LRP connects a logical router either  to  a  logical
311       switch  or  to  another logical router. Logical routers only connect to
312       VMs, containers, and other network nodes  indirectly,  through  logical
313       switches.
314
315       Logical  switches  and  logical  routers have distinct kinds of logical
316       ports, so properly speaking  one  should  usually  talk  about  logical
317       switch ports or logical router ports. However, an unqualified ``logical
318       port’’ usually refers to a logical switch port.
319
320       When a VM sends a packet to a VIF logical switch port, the Open vSwitch
321       flow  tables  simulate the packet’s journey through that logical switch
322       and any other logical routers and logical switches that  it  might  en‐
323       counter. This happens without transmitting the packet across any physi‐
324       cal medium: the flow tables implement all of the switching and  routing
325       decisions  and behavior. If the flow tables ultimately decide to output
326       the packet at a logical port attached to another hypervisor (or another
327       kind  of  transport node), then that is the time at which the packet is
328       encapsulated for physical network transmission and sent.
329
330     Logical Switch Port Types
331
332       OVN supports a number of kinds of logical switch ports. VIF ports  that
333       connect  to  VMs  or containers, described above, are the most ordinary
334       kind of LSP. In the OVN northbound database, VIF ports  have  an  empty
335       string  for  their  type. This section describes some of the additional
336       port types.
337
338       A router logical switch port connects a logical  switch  to  a  logical
339       router, designating a particular LRP as its peer.
340
341       A  localnet  logical switch port bridges a logical switch to a physical
342       VLAN. A logical switch may have one or more localnet ports. Such a log‐
343       ical switch is used in two scenarios:
344
345              •      With  one  or more router logical switch ports, to attach
346                     L3 gateway routers and distributed gateways to a physical
347                     network.
348
349              •      With  one or more VIF logical switch ports, to attach VMs
350                     or containers directly to a  physical  network.  In  this
351                     case,  the logical switch is not really logical, since it
352                     is bridged to the physical network rather than  insulated
353                     from  it, and therefore cannot have independent but over‐
354                     lapping IP address namespaces, etc.  A  deployment  might
355                     nevertheless  choose  such a configuration to take advan‐
356                     tage of the OVN control plane and features such  as  port
357                     security and ACLs.
358
359       When  a  logical switch contains multiple localnet ports, the following
360       is assumed.
361
362              •      Each chassis has a bridge mapping for one of the localnet
363                     physical networks only.
364
365              •      To  facilitate interconnectivity between VIF ports of the
366                     switch that are located on different chassis with differ‐
367                     ent  physical network connectivity, the fabric implements
368                     L3 routing between these adjacent physical  network  seg‐
369                     ments.
370
371       Note:  nothing  said  above implies that a chassis cannot be plugged to
372       multiple  physical  networks  as  long  as  they  belong  to  different
373       switches.
374
375       A localport logical switch port is a special kind of VIF logical switch
376       port. These ports are present in every chassis, not bound to  any  par‐
377       ticular  one.  Traffic to such a port will never be forwarded through a
378       tunnel, and traffic from such a port is expected to be destined only to
379       the same chassis, typically in response to a request it received. Open‐
380       Stack Neutron uses a localport port to serve metadata to VMs.  A  meta‐
381       data  proxy  process is attached to this port on every host and all VMs
382       within the same network will reach it at the same IP/MAC address  with‐
383       out  any traffic being sent over a tunnel. For further details, see the
384       OpenStack documentation for networking-ovn.
385
386       LSP types vtep and l2gateway are used for gateways. See  Gateways,  be‐
387       low, for more information.
388
389     Implementation Details
390
391       These  concepts  are details of how OVN is implemented internally. They
392       might still be of interest to users and administrators.
393
394       Logical datapaths are an implementation detail of logical  networks  in
395       the  OVN southbound database. ovn-northd translates each logical switch
396       or router in the northbound database into a  logical  datapath  in  the
397       southbound database Datapath_Binding table.
398
399       For  the most part, ovn-northd also translates each logical switch port
400       in the OVN northbound database into a record in the southbound database
401       Port_Binding  table. The latter table corresponds roughly to the north‐
402       bound Logical_Switch_Port table. It has multiple types of logical  port
403       bindings,  of  which  many  types correspond directly to northbound LSP
404       types. LSP types handled this way include VIF (empty string), localnet,
405       localport, vtep, and l2gateway.
406
407       The  Port_Binding table has some types of port binding that do not cor‐
408       respond directly to logical switch port types. The common is patch port
409       bindings,  known as logical patch ports. These port bindings always oc‐
410       cur in pairs, and a packet that enters on either side comes out on  the
411       other.  ovn-northd  connects  logical  switches and logical routers to‐
412       gether using logical patch ports.
413
414       Port bindings with types vtep, l2gateway, l3gateway,  and  chassisredi‐
415       rect are used for gateways. These are explained in Gateways, below.
416
417   Gateways
418       Gateways  provide  limited  connectivity  between  logical networks and
419       physical ones. They can also provide connectivity between different OVN
420       deployments. This section will focus on the former, and the latter will
421       be described in details in section OVN Deployments Interconnection.
422
423       OVN support multiple kinds of gateways.
424
425     VTEP Gateways
426
427       A ``VTEP gateway’’ connects an OVN logical network to  a  physical  (or
428       virtual)  switch that implements the OVSDB VTEP schema that accompanies
429       Open vSwitch. (The ``VTEP gateway’’ term is a misnomer, since a VTEP is
430       just  a  VXLAN Tunnel Endpoint, but it is a well established name.) See
431       Life Cycle of a VTEP gateway, below, for more information.
432
433       The main intended use case for VTEP  gateways  is  to  attach  physical
434       servers  to  an OVN logical network using a physical top-of-rack switch
435       that supports the OVSDB VTEP schema.
436
437     L2 Gateways
438
439       A L2 gateway simply attaches a designated physical L2 segment available
440       on  some chassis to a logical network. The physical network effectively
441       becomes part of the logical network.
442
443       To set up a L2 gateway, the CMS adds an l2gateway LSP to an appropriate
444       logical  switch,  setting  LSP  options to name the chassis on which it
445       should be bound. ovn-northd copies this configuration into a southbound
446       Port_Binding record. On the designated chassis, ovn-controller forwards
447       packets appropriately to and from the physical segment.
448
449       L2 gateway ports have features in common with localnet ports.  However,
450       with  a  localnet  port, the physical network becomes the transport be‐
451       tween hypervisors. With an L2 gateway, packets  are  still  transported
452       between  hypervisors  over  tunnels and the l2gateway port is only used
453       for the packets that are on the physical network. The  application  for
454       L2  gateways is similar to that for VTEP gateways, e.g. to add non-vir‐
455       tualized machines to a logical network, but L2 gateways do not  require
456       special support from top-of-rack hardware switches.
457
458     L3 Gateway Routers
459
460       As described above under Logical Networks, ordinary OVN logical routers
461       are distributed: they are not implemented in a single place but  rather
462       in  every  hypervisor  chassis. This is a problem for stateful services
463       such as SNAT and DNAT, which need to be implemented  in  a  centralized
464       manner.
465
466       To  allow  for  this  kind  of  functionality,  OVN supports L3 gateway
467       routers, which are OVN logical routers that are implemented in a desig‐
468       nated  chassis.  Gateway routers are typically used between distributed
469       logical routers and physical networks. The distributed  logical  router
470       and the logical switches behind it, to which VMs and containers attach,
471       effectively reside on each hypervisor. The distributed router  and  the
472       gateway  router  are connected by another logical switch, sometimes re‐
473       ferred to as a ``join’’ logical switch. (OVN  logical  routers  may  be
474       connected  to  one another directly, without an intervening switch, but
475       the OVN implementation only supports gateway logical routers  that  are
476       connected to logical switches. Using a join logical switch also reduces
477       the number of IP addresses needed on the distributed  router.)  On  the
478       other  side, the gateway router connects to another logical switch that
479       has a localnet port connecting to the physical network.
480
481       The following diagram shows a typical situation. One  or  more  logical
482       switches LS1, ..., LSn connect to distributed logical router LR1, which
483       in turn connects through LSjoin to gateway logical  router  GLR,  which
484       also connects to logical switch LSlocal, which includes a localnet port
485       to attach to the physical network.
486
487                                       LSlocal
488                                          |
489                                         GLR
490                                          |
491                                       LSjoin
492                                          |
493                                         LR1
494                                          |
495                                     +----+----+
496                                     |    |    |
497                                    LS1  ...  LSn
498
499
500       To configure an L3 gateway router, the CMS sets options:chassis in  the
501       router’s  northbound Logical_Router to the chassis’s name. In response,
502       ovn-northd uses a special l3gateway port binding (instead  of  a  patch
503       binding)  in  the  southbound database to connect the logical router to
504       its neighbors. In turn, ovn-controller tunnels  packets  to  this  port
505       binding  to  the  designated  L3 gateway chassis, instead of processing
506       them locally.
507
508       DNAT and SNAT rules may be associated with a gateway router, which pro‐
509       vides  a central location that can handle one-to-many SNAT (aka IP mas‐
510       querading). Distributed gateway ports, described  below,  also  support
511       NAT.
512
513     Distributed Gateway Ports
514
515       A  distributed  gateway port is a logical router port that is specially
516       configured to designate one distinguished chassis, called  the  gateway
517       chassis,  for centralized processing. A distributed gateway port should
518       connect to a logical switch that has an LSP that  connects  externally,
519       that  is,  either a localnet LSP or a connection to another OVN deploy‐
520       ment (see OVN Deployments Interconnection). Packets that  traverse  the
521       distributed  gateway  port  are processed without involving the gateway
522       chassis when they can be, but when needed they do  take  an  extra  hop
523       through it.
524
525       The  following  diagram  illustrates  the  use of a distributed gateway
526       port. A number of logical switches LS1, ..., LSn connect to distributed
527       logical  router  LR1,  which  in  turn connects through the distributed
528       gateway port to logical switch LSlocal that includes a localnet port to
529       attach to the physical network.
530
531                                       LSlocal
532                                          |
533                                         LR1
534                                          |
535                                     +----+----+
536                                     |    |    |
537                                    LS1  ...  LSn
538
539
540       ovn-northd  creates  two southbound Port_Binding records to represent a
541       distributed gateway port, instead of the usual one. One of these  is  a
542       patch port binding named for the LRP, which is used for as much traffic
543       as it can. The other one is a port binding with  type  chassisredirect,
544       named  cr-port.  The  chassisredirect  port binding has one specialized
545       job: when a packet is output to it, the flow table causes it to be tun‐
546       neled to the gateway chassis, at which point it is automatically output
547       to the patch port binding. Thus, the flow table can output to this port
548       binding  in  cases where a particular task has to happen on the gateway
549       chassis. The chassisredirect port binding is not  otherwise  used  (for
550       example, it never receives packets).
551
552       The  CMS  may configure distributed gateway ports three different ways.
553       See  Distributed  Gateway  Ports  in  the   documentation   for   Logi‐
554       cal_Router_Port in ovn-nb(5) for details.
555
556       Distributed gateway ports support high availability. When more than one
557       chassis is specified, OVN only uses one at a time as the gateway  chas‐
558       sis. OVN uses BFD to monitor gateway connectivity, preferring the high‐
559       est-priority gateway that is online.
560
561       A logical router can have multiple distributed gateway ports, each con‐
562       necting  different  external  networks.  Load balancing is not yet sup‐
563       ported for logical routers with more than one distributed gateway  port
564       configured.
565
566       Physical VLAN MTU Issues
567
568       Consider the preceding diagram again:
569
570                                       LSlocal
571                                          |
572                                         LR1
573                                          |
574                                     +----+----+
575                                     |    |    |
576                                    LS1  ...  LSn
577
578
579       Suppose that each logical switch LS1, ..., LSn is bridged to a physical
580       VLAN-tagged network attached to a localnet port on LSlocal, over a dis‐
581       tributed  gateway  port  on LR1. If a packet originating on LSi is des‐
582       tined to the external network, OVN sends it to the gateway chassis over
583       a  tunnel.  There,  the packet traverses LR1’s logical router pipeline,
584       possibly undergoes NAT, and eventually ends up  at  LSlocal’s  localnet
585       port.  If  all  of the physical links in the network have the same MTU,
586       then the packet’s transit across a tunnel causes an MTU problem: tunnel
587       overhead  prevents a packet that uses the full physical MTU from cross‐
588       ing the tunnel to the gateway chassis (without fragmentation).
589
590       OVN offers two solutions to this problem, the  reside-on-redirect-chas‐
591       sis  and  redirect-type  options.  Both  solutions require each logical
592       switch LS1, ..., LSn to include a localnet  logical  switch  port  LN1,
593       ...,  LNn  respectively,  that  is  present on each chassis. Both cause
594       packets to be sent over the localnet ports  instead  of  tunnels.  They
595       differ  in which packets-some or all-are sent this way. The most promi‐
596       nent tradeoff between these options is that  reside-on-redirect-chassis
597       is easier to configure and that redirect-type performs better for east-
598       west traffic.
599
600       The first solution is the reside-on-redirect-chassis option for logical
601       router  ports. Setting this option on a LRP from (e.g.) LS1 to LR1 dis‐
602       ables forwarding from LS1 to LR1 except  on  the  gateway  chassis.  On
603       chassis  other  than the gateway chassis, this single change means that
604       packets that would otherwise have been forwarded  to  LR1  are  instead
605       forwarded  to  LN1. The instance of LN1 on the gateway chassis then re‐
606       ceives the packet and forwards it to LR1. The packet traverses the  LR1
607       logical router pipeline, possibly undergoes NAT, and eventually ends up
608       at LSlocal’s localnet port. The packet never traverses a tunnel, avoid‐
609       ing the MTU issue.
610
611       This option has the further consequence of centralizing ``distributed’’
612       logical router LR1, since no packets are forwarded from LS1 to  LR1  on
613       any  chassis other than the gateway chassis. Therefore, east-west traf‐
614       fic passes through the gateway  chassis,  not  just  north-south.  (The
615       naive  ``fix’’  of  allowing east-west traffic to flow directly between
616       chassis over LN1 does not work because routing sets the Ethernet source
617       address to LR1’s source address. Seeing this single Ethernet source ad‐
618       dress originate from all of  the  chassis  will  confuse  the  physical
619       switch.)
620
621       Do not set the reside-on-redirect-chassis option on a distributed gate‐
622       way port. In the diagram above, it would be set on the LRPs  connecting
623       LS1, ..., LSn to LR1.
624
625       The second solution is the redirect-type option for distributed gateway
626       ports. Setting this option to bridged causes  packets  that  are  redi‐
627       rected  to the gateway chassis to go over the localnet ports instead of
628       being tunneled. This option does not change how OVN treats packets  not
629       redirected to the gateway chassis.
630
631       The  redirect-type option requires the administrator or the CMS to con‐
632       figure each participating chassis with a unique  Ethernet  address  for
633       the  logical  router  by  setting  ovn-chassis-mac-mappings in the Open
634       vSwitch database, for use by ovn-controller. This makes it more  diffi‐
635       cult to configure than reside-on-redirect-chassis.
636
637       Set the redirect-type option on a distributed gateway port.
638
639       Using Distributed Gateway Ports For Scalability
640
641       Although  the  primary  goal of distributed gateway ports is to provide
642       connectivity to external networks, there is  a  special  use  case  for
643       scalability.
644
645       In  some  deployments,  such  as the ones using ovn-kubernetes, logical
646       switches are bound to individual chassises, and are connected by a dis‐
647       tributed logical router. In such deployments, the chassis level logical
648       switches are centralized on the chassis instead of  distributed,  which
649       means  the ovn-controller on each chassis doesn’t need to process flows
650       and ports of logical switches on other chassises. However, without  any
651       specific  hint,  ovn-controller  would  still  process  all the logical
652       switches as if they are fully distributed. In  this  case,  distributed
653       gateway port can be very useful. The chassis level logical switches can
654       be connected to the distributed router using distributed gateway ports,
655       by setting the gateway chassis (or HA chassis groups with only a single
656       chassis in it) to the chassis that each logical  switch  is  bound  to.
657       ovn-controller  would  then skip processing the logical switches on all
658       the other chassises, largely improving the scalability, especially when
659       there are a big number of chassises.
660
661   Life Cycle of a VIF
662       Tables and their schemas presented in isolation are difficult to under‐
663       stand. Here’s an example.
664
665       A VIF on a hypervisor is a virtual network interface attached either to
666       a  VM  or a container running directly on that hypervisor (This is dif‐
667       ferent from the interface of a container running inside a VM).
668
669       The steps in this example refer often to details of  the  OVN  and  OVN
670       Northbound  database  schemas.  Please see ovn-sb(5) and ovn-nb(5), re‐
671       spectively, for the full story on these databases.
672
673              1.  A VIF’s life cycle begins when a CMS administrator creates a
674                  new VIF using the CMS user interface or API and adds it to a
675                  switch (one implemented by OVN as a logical switch). The CMS
676                  updates  its  own  configuration.  This includes associating
677                  unique, persistent identifier vif-id  and  Ethernet  address
678                  mac with the VIF.
679
680              2.  The  CMS  plugin  updates the OVN Northbound database to in‐
681                  clude  the  new  VIF,  by  adding  a  row   to   the   Logi‐
682                  cal_Switch_Port  table.  In the new row, name is vif-id, mac
683                  is mac, switch points to  the  OVN  logical  switch’s  Logi‐
684                  cal_Switch  record, and other columns are initialized appro‐
685                  priately.
686
687              3.  ovn-northd receives the OVN Northbound database  update.  In
688                  turn,  it  makes the corresponding updates to the OVN South‐
689                  bound database, by adding rows to the OVN  Southbound  data‐
690                  base  Logical_Flow table to reflect the new port, e.g. add a
691                  flow to recognize that packets destined to  the  new  port’s
692                  MAC  address  should be delivered to it, and update the flow
693                  that delivers broadcast and multicast packets to include the
694                  new  port. It also creates a record in the Binding table and
695                  populates all its columns except the column that  identifies
696                  the chassis.
697
698              4.  On  every  hypervisor,  ovn-controller  receives  the  Logi‐
699                  cal_Flow table updates that ovn-northd made in the  previous
700                  step.  As  long  as the VM that owns the VIF is powered off,
701                  ovn-controller cannot do much; it cannot, for  example,  ar‐
702                  range  to  send  packets to or receive packets from the VIF,
703                  because the VIF does not actually exist anywhere.
704
705              5.  Eventually, a user powers on the VM that owns  the  VIF.  On
706                  the  hypervisor  where the VM is powered on, the integration
707                  between the hypervisor and Open vSwitch (described in  Docu‐
708                  mentation/topics/integration.rst  in the Open vSwitch source
709                  tree) adds the VIF to the OVN integration bridge and  stores
710                  vif-id  in external_ids:iface-id to indicate that the inter‐
711                  face is an instantiation of the new VIF. (None of this  code
712                  is  new  in  OVN; this is pre-existing integration work that
713                  has already been done on hypervisors that support OVS.)
714
715              6.  On the hypervisor where the VM is powered on, ovn-controller
716                  notices  external_ids:iface-id  in the new Interface. In re‐
717                  sponse, in the OVN Southbound DB, it updates the Binding ta‐
718                  ble’s chassis column for the row that links the logical port
719                  from external_ids: iface-id to  the  hypervisor.  Afterward,
720                  ovn-controller  updates  the local hypervisor’s OpenFlow ta‐
721                  bles so that packets to and from the VIF are  properly  han‐
722                  dled.
723
724              7.  Some CMS systems, including OpenStack, fully start a VM only
725                  when its networking is ready. To  support  this,  ovn-northd
726                  notices  the  chassis  column updated for the row in Binding
727                  table and pushes this upward by updating the  up  column  in
728                  the  OVN  Northbound database’s Logical_Switch_Port table to
729                  indicate that the VIF is now up. The CMS, if  it  uses  this
730                  feature,  can  then  react by allowing the VM’s execution to
731                  proceed.
732
733              8.  On every hypervisor but  the  one  where  the  VIF  resides,
734                  ovn-controller  notices  the completely populated row in the
735                  Binding table. This provides ovn-controller the physical lo‐
736                  cation  of  the  logical  port, so each instance updates the
737                  OpenFlow tables of its switch  (based  on  logical  datapath
738                  flows  in  the OVN DB Logical_Flow table) so that packets to
739                  and from the VIF can be properly handled via tunnels.
740
741              9.  Eventually, a user powers off the VM that owns the  VIF.  On
742                  the  hypervisor  where  the  VM  was powered off, the VIF is
743                  deleted from the OVN integration bridge.
744
745              10. On the hypervisor where the VM  was  powered  off,  ovn-con‐
746                  troller  notices  that  the VIF was deleted. In response, it
747                  removes the Chassis column content in the Binding table  for
748                  the logical port.
749
750              11. On  every hypervisor, ovn-controller notices the empty Chas‐
751                  sis column in the Binding table’s row for the logical  port.
752                  This  means that ovn-controller no longer knows the physical
753                  location of the logical port, so each instance  updates  its
754                  OpenFlow table to reflect that.
755
756              12. Eventually,  when  the  VIF  (or its entire VM) is no longer
757                  needed by anyone, an administrator deletes the VIF using the
758                  CMS  user interface or API. The CMS updates its own configu‐
759                  ration.
760
761              13. The CMS plugin removes the VIF from the OVN Northbound data‐
762                  base, by deleting its row in the Logical_Switch_Port table.
763
764              14. ovn-northd  receives  the  OVN Northbound update and in turn
765                  updates the OVN Southbound database accordingly, by removing
766                  or  updating the rows from the OVN Southbound database Logi‐
767                  cal_Flow table and Binding table that were  related  to  the
768                  now-destroyed VIF.
769
770              15. On  every  hypervisor,  ovn-controller  receives  the  Logi‐
771                  cal_Flow table updates that ovn-northd made in the  previous
772                  step.  ovn-controller updates OpenFlow tables to reflect the
773                  update, although there may not be much to do, since the  VIF
774                  had  already become unreachable when it was removed from the
775                  Binding table in a previous step.
776
777   Life Cycle of a Container Interface Inside a VM
778       OVN provides virtual network  abstractions  by  converting  information
779       written in OVN_NB database to OpenFlow flows in each hypervisor. Secure
780       virtual networking for multi-tenants can only be provided if  OVN  con‐
781       troller  is the only entity that can modify flows in Open vSwitch. When
782       the Open vSwitch integration bridge resides in the hypervisor, it is  a
783       fair assumption to make that tenant workloads running inside VMs cannot
784       make any changes to Open vSwitch flows.
785
786       If the infrastructure provider trusts the applications inside the  con‐
787       tainers  not  to break out and modify the Open vSwitch flows, then con‐
788       tainers can be run in hypervisors. This is also the case when  contain‐
789       ers  are  run  inside  the VMs and Open vSwitch integration bridge with
790       flows added by OVN controller resides in the  same  VM.  For  both  the
791       above  cases,  the workflow is the same as explained with an example in
792       the previous section ("Life Cycle of a VIF").
793
794       This section talks about the life cycle of a container interface  (CIF)
795       when containers are created in the VMs and the Open vSwitch integration
796       bridge resides inside the hypervisor. In this case, even if a container
797       application breaks out, other tenants are not affected because the con‐
798       tainers running inside the VMs cannot modify  the  flows  in  the  Open
799       vSwitch integration bridge.
800
801       When  multiple  containers  are created inside a VM, there are multiple
802       CIFs associated with them. The network traffic  associated  with  these
803       CIFs  need  to reach the Open vSwitch integration bridge running in the
804       hypervisor for OVN to support virtual network abstractions. OVN  should
805       also be able to distinguish network traffic coming from different CIFs.
806       There are two ways to distinguish network traffic of CIFs.
807
808       One way is to provide one VIF for every CIF  (1:1  model).  This  means
809       that  there  could  be a lot of network devices in the hypervisor. This
810       would slow down OVS because of all the additional CPU cycles needed for
811       the management of all the VIFs. It would also mean that the entity cre‐
812       ating the containers in a VM should also be able to create  the  corre‐
813       sponding VIFs in the hypervisor.
814
815       The  second  way  is  to  provide a single VIF for all the CIFs (1:many
816       model). OVN could then distinguish network traffic coming from  differ‐
817       ent CIFs via a tag written in every packet. OVN uses this mechanism and
818       uses VLAN as the tagging mechanism.
819
820              1.  A CIF’s life cycle begins when a container is spawned inside
821                  a  VM  by  the  either the same CMS that created the VM or a
822                  tenant that owns that VM or even a  container  Orchestration
823                  System that is different than the CMS that initially created
824                  the VM. Whoever the entity is, it will need to know the vif-
825                  id  that  is associated with the network interface of the VM
826                  through which the container interface’s network  traffic  is
827                  expected  to  go  through.  The entity that creates the con‐
828                  tainer interface will also need to choose an unused VLAN in‐
829                  side that VM.
830
831              2.  The  container  spawning  entity (either directly or through
832                  the CMS that manages the underlying infrastructure)  updates
833                  the  OVN  Northbound  database  to  include  the new CIF, by
834                  adding a row to the Logical_Switch_Port table.  In  the  new
835                  row,  name is any unique identifier, parent_name is the vif-
836                  id of the VM through which the CIF’s network traffic is  ex‐
837                  pected  to go through and the tag is the VLAN tag that iden‐
838                  tifies the network traffic of that CIF.
839
840              3.  ovn-northd receives the OVN Northbound database  update.  In
841                  turn,  it  makes the corresponding updates to the OVN South‐
842                  bound database, by adding rows to the OVN  Southbound  data‐
843                  base’s  Logical_Flow  table to reflect the new port and also
844                  by creating a new row in the Binding  table  and  populating
845                  all  its columns except the column that identifies the chas‐
846                  sis.
847
848              4.  On  every  hypervisor,  ovn-controller  subscribes  to   the
849                  changes  in  the Binding table. When a new row is created by
850                  ovn-northd that includes a value in  parent_port  column  of
851                  Binding  table,  the  ovn-controller in the hypervisor whose
852                  OVN integration bridge has that same value in vif-id in  ex‐
853                  ternal_ids:iface-id  updates the local hypervisor’s OpenFlow
854                  tables so that packets to and from the VIF with the particu‐
855                  lar  VLAN tag are properly handled. Afterward it updates the
856                  chassis column of the Binding to reflect the physical  loca‐
857                  tion.
858
859              5.  One  can only start the application inside the container af‐
860                  ter the  underlying  network  is  ready.  To  support  this,
861                  ovn-northd notices the updated chassis column in Binding ta‐
862                  ble and updates the up column in the  OVN  Northbound  data‐
863                  base’s Logical_Switch_Port table to indicate that the CIF is
864                  now up. The entity responsible to start the container appli‐
865                  cation queries this value and starts the application.
866
867              6.  Eventually  the  entity  that  created  and started the con‐
868                  tainer, stops it. The entity, through the CMS (or  directly)
869                  deletes its row in the Logical_Switch_Port table.
870
871              7.  ovn-northd  receives  the  OVN Northbound update and in turn
872                  updates the OVN Southbound database accordingly, by removing
873                  or  updating the rows from the OVN Southbound database Logi‐
874                  cal_Flow table that were related to the  now-destroyed  CIF.
875                  It also deletes the row in the Binding table for that CIF.
876
877              8.  On  every  hypervisor,  ovn-controller  receives  the  Logi‐
878                  cal_Flow table updates that ovn-northd made in the  previous
879                  step.  ovn-controller updates OpenFlow tables to reflect the
880                  update.
881
882   Architectural Physical Life Cycle of a Packet
883       This section describes how a packet travels from one virtual machine or
884       container to another through OVN. This description focuses on the phys‐
885       ical treatment of a packet; for a description of the logical life cycle
886       of a packet, please refer to the Logical_Flow table in ovn-sb(5).
887
888       This  section  mentions  several  data and metadata fields, for clarity
889       summarized here:
890
891              tunnel key
892                     When OVN encapsulates a packet in Geneve or another  tun‐
893                     nel,  it attaches extra data to it to allow the receiving
894                     OVN instance to process it correctly. This takes  differ‐
895                     ent  forms depending on the particular encapsulation, but
896                     in each case we refer to it here as the  ``tunnel  key.’’
897                     See Tunnel Encapsulations, below, for details.
898
899              logical datapath field
900                     A field that denotes the logical datapath through which a
901                     packet is being processed. OVN uses the field that  Open‐
902                     Flow  1.1+ simply (and confusingly) calls ``metadata’’ to
903                     store the logical datapath. (This field is passed  across
904                     tunnels as part of the tunnel key.)
905
906              logical input port field
907                     A  field  that  denotes  the  logical port from which the
908                     packet entered the logical datapath. OVN stores  this  in
909                     Open vSwitch extension register number 14.
910
911                     Geneve  and  STT  tunnels  pass this field as part of the
912                     tunnel key. Ramp switch VXLAN tunnels do  not  explicitly
913                     carry  a  logical  input port, but since they are used to
914                     communicate with gateways  that  from  OVN’s  perspective
915                     consist  of  only  a single logical port, so that OVN can
916                     set the logical input port field to this one  on  ingress
917                     to  the  OVN  logical pipeline. As for regular VXLAN tun‐
918                     nels, they don’t carry input port field at all. This puts
919                     additional  limitations  on cluster capabilities that are
920                     described in Tunnel Encapsulations section.
921
922              logical output port field
923                     A field that denotes the  logical  port  from  which  the
924                     packet  will leave the logical datapath. This is initial‐
925                     ized to 0 at the beginning of the logical  ingress  pipe‐
926                     line.  OVN stores this in Open vSwitch extension register
927                     number 15.
928
929                     Geneve, STT and regular VXLAN tunnels pass this field  as
930                     part  of the tunnel key. Ramp switch VXLAN tunnels do not
931                     transmit the logical output port field, and since they do
932                     not  carry a logical output port field in the tunnel key,
933                     when a packet is received from ramp switch  VXLAN  tunnel
934                     by  an OVN hypervisor, the packet is resubmitted to table
935                     8 to  determine  the  output  port(s);  when  the  packet
936                     reaches  table 39, these packets are resubmitted to table
937                     40 for local delivery  by  checking  a  MLF_RCV_FROM_RAMP
938                     flag,  which  is  set when the packet arrives from a ramp
939                     tunnel.
940
941              conntrack zone field for logical ports
942                     A field that denotes the  connection  tracking  zone  for
943                     logical  ports. The value only has local significance and
944                     is not meaningful between chassis. This is initialized to
945                     0  at  the beginning of the logical ingress pipeline. OVN
946                     stores this in Open vSwitch extension register number 13.
947
948              conntrack zone fields for routers
949                     Fields that denote  the  connection  tracking  zones  for
950                     routers.  These  values  only have local significance and
951                     are not meaningful between chassis. OVN stores  the  zone
952                     information  for  north to south traffic (for DNATting or
953                     ECMP symmetric replies) in Open vSwitch extension  regis‐
954                     ter  number  11  and  zone information for south to north
955                     traffic (for SNATing) in Open vSwitch extension  register
956                     number 12.
957
958              logical flow flags
959                     The  logical flags are intended to handle keeping context
960                     between tables in order to decide which rules  in  subse‐
961                     quent  tables  are  matched. These values only have local
962                     significance and are not meaningful between chassis.  OVN
963                     stores the logical flags in Open vSwitch extension regis‐
964                     ter number 10.
965
966              VLAN ID
967                     The VLAN ID is used as an interface between OVN and  con‐
968                     tainers nested inside a VM (see Life Cycle of a container
969                     interface inside a VM, above, for more information).
970
971       Initially, a VM or container on the ingress hypervisor sends  a  packet
972       on a port attached to the OVN integration bridge. Then:
973
974              1.  OpenFlow  table  0 performs physical-to-logical translation.
975                  It matches the packet’s ingress port. Its  actions  annotate
976                  the  packet  with  logical  metadata, by setting the logical
977                  datapath field to identify the  logical  datapath  that  the
978                  packet  is  traversing  and  the logical input port field to
979                  identify the ingress port. Then it resubmits to table  8  to
980                  enter the logical ingress pipeline.
981
982                  Packets  that  originate from a container nested within a VM
983                  are treated in a slightly  different  way.  The  originating
984                  container  can  be  distinguished  based on the VIF-specific
985                  VLAN ID, so the physical-to-logical translation flows  addi‐
986                  tionally  match  on  VLAN  ID and the actions strip the VLAN
987                  header. Following this step, OVN treats  packets  from  con‐
988                  tainers just like any other packets.
989
990                  Table  0 also processes packets that arrive from other chas‐
991                  sis. It distinguishes them from  other  packets  by  ingress
992                  port,  which  is a tunnel. As with packets just entering the
993                  OVN pipeline, the actions annotate these packets with  logi‐
994                  cal  datapath  metadata.  For  tunnel types that support it,
995                  they are also annotated with logical ingress port  metadata.
996                  In  addition, the actions set the logical output port field,
997                  which is available because in OVN tunneling occurs after the
998                  logical  output  port  is known. These pieces of information
999                  are obtained from the  tunnel  encapsulation  metadata  (see
1000                  Tunnel  Encapsulations  for  encoding details). Then the ac‐
1001                  tions resubmit to table 38 to enter the logical egress pipe‐
1002                  line.
1003
1004              2.  OpenFlow  tables  8  through  31 execute the logical ingress
1005                  pipeline from the Logical_Flow table in the  OVN  Southbound
1006                  database.  These  tables  are expressed entirely in terms of
1007                  logical concepts like logical ports and logical datapaths. A
1008                  big  part  of ovn-controller’s job is to translate them into
1009                  equivalent OpenFlow (in particular it translates  the  table
1010                  numbers:  Logical_Flow  tables  0 through 23 become OpenFlow
1011                  tables 8 through 31).
1012
1013                  Each logical flow maps to one or more OpenFlow flows. An ac‐
1014                  tual  packet  ordinarily matches only one of these, although
1015                  in some cases it can match more  than  one  of  these  flows
1016                  (which  is  not  a problem because all of them have the same
1017                  actions). ovn-controller uses the first 32 bits of the logi‐
1018                  cal  flow’s  UUID  as  the  cookie  for its OpenFlow flow or
1019                  flows. (This is not necessarily unique, since the  first  32
1020                  bits of a logical flow’s UUID is not necessarily unique.)
1021
1022                  Some logical flows can map to the Open vSwitch ``conjunctive
1023                  match’’ extension (see ovs-fields(7)). Flows with a conjunc‐
1024                  tion  action  use  an OpenFlow cookie of 0, because they can
1025                  correspond to multiple logical flows. The OpenFlow flow  for
1026                  a conjunctive match includes a match on conj_id.
1027
1028                  Some  logical  flows  may not be represented in the OpenFlow
1029                  tables on a given hypervisor, if they could not be  used  on
1030                  that  hypervisor. For example, if no VIF in a logical switch
1031                  resides on a given hypervisor, and the logical switch is not
1032                  otherwise  reachable  on that hypervisor (e.g. over a series
1033                  of hops through logical switches and routers starting from a
1034                  VIF  on  the  hypervisor),  then the logical flow may not be
1035                  represented there.
1036
1037                  Most OVN actions  have  fairly  obvious  implementations  in
1038                  OpenFlow (with OVS extensions), e.g. next; is implemented as
1039                  resubmit, field = constant; as set_field. A  few  are  worth
1040                  describing in more detail:
1041
1042                  output:
1043                         Implemented  by  resubmitting the packet to table 37.
1044                         If the pipeline executes more than one output action,
1045                         then  each one is separately resubmitted to table 37.
1046                         This can be used  to  send  multiple  copies  of  the
1047                         packet to multiple ports. (If the packet was not mod‐
1048                         ified between the output actions,  and  some  of  the
1049                         copies  are destined to the same hypervisor, then us‐
1050                         ing a logical multicast output port would save  band‐
1051                         width between hypervisors.)
1052
1053                  get_arp(P, A);
1054                  get_nd(P, A);
1055                       Implemented  by storing arguments into OpenFlow fields,
1056                       then resubmitting to  table  66,  which  ovn-controller
1057                       populates with flows generated from the MAC_Binding ta‐
1058                       ble in the OVN Southbound database. If there is a match
1059                       in  table  66,  then its actions store the bound MAC in
1060                       the Ethernet destination address field.
1061
1062                       (The OpenFlow actions save  and  restore  the  OpenFlow
1063                       fields  used for the arguments, so that the OVN actions
1064                       do not have to be aware of this temporary use.)
1065
1066                  put_arp(P, A, E);
1067                  put_nd(P, A, E);
1068                       Implemented by  storing  the  arguments  into  OpenFlow
1069                       fields,  then  outputting  a  packet to ovn-controller,
1070                       which updates the MAC_Binding table.
1071
1072                       (The OpenFlow actions save  and  restore  the  OpenFlow
1073                       fields  used for the arguments, so that the OVN actions
1074                       do not have to be aware of this temporary use.)
1075
1076                  R = lookup_arp(P, A, M);
1077                  R = lookup_nd(P, A, M);
1078                       Implemented by storing arguments into OpenFlow  fields,
1079                       then  resubmitting  to  table  67, which ovn-controller
1080                       populates with flows generated from the MAC_Binding ta‐
1081                       ble in the OVN Southbound database. If there is a match
1082                       in table 67, then its actions set the logical flow flag
1083                       MLF_LOOKUP_MAC.
1084
1085                       (The  OpenFlow  actions  save  and restore the OpenFlow
1086                       fields used for the arguments, so that the OVN  actions
1087                       do not have to be aware of this temporary use.)
1088
1089              3.  OpenFlow tables 37 through 41 implement the output action in
1090                  the logical ingress pipeline. Specifically, table 37  serves
1091                  as  an  entry  point to egress pipeline. Table 37 detects IP
1092                  packets that are too big for a corresponding interface.  Ta‐
1093                  ble  38  produces ICMPv4 Fragmentation Needed (or ICMPv6 Too
1094                  Big) errors and deliver them back to the offending port. ta‐
1095                  ble  39 handles packets to remote hypervisors, table 40 han‐
1096                  dles packets to the local hypervisor, and  table  41  checks
1097                  whether  packets  whose  logical ingress and egress port are
1098                  the same should be discarded.
1099
1100                  Logical patch ports are a special case. Logical patch  ports
1101                  do  not  have  a physical location and effectively reside on
1102                  every hypervisor. Thus, flow table 40, for output  to  ports
1103                  on the local hypervisor, naturally implements output to uni‐
1104                  cast logical patch ports too.  However,  applying  the  same
1105                  logic to a logical patch port that is part of a logical mul‐
1106                  ticast group yields packet duplication, because each  hyper‐
1107                  visor  that  contains  a logical port in the multicast group
1108                  will also output the packet to the logical patch port. Thus,
1109                  multicast  groups implement output to logical patch ports in
1110                  table 39.
1111
1112                  Each flow in table 39 matches on a logical output  port  for
1113                  unicast  or  multicast  logical ports that include a logical
1114                  port on a remote hypervisor. Each flow’s  actions  implement
1115                  sending a packet to the port it matches. For unicast logical
1116                  output ports on remote hypervisors, the actions set the tun‐
1117                  nel  key  to  the correct value, then send the packet on the
1118                  tunnel port to the correct hypervisor. (When the remote  hy‐
1119                  pervisor  receives  the packet, table 0 there will recognize
1120                  it as a tunneled packet and pass it along to table 40.)  For
1121                  multicast logical output ports, the actions send one copy of
1122                  the packet to each remote hypervisor, in the same way as for
1123                  unicast  destinations. If a multicast group includes a logi‐
1124                  cal port or ports on the local hypervisor, then its  actions
1125                  also resubmit to table 40. Table 39 also includes:
1126
1127                  •      A higher-priority rule to match packets received from
1128                         ramp switch tunnels, based on flag MLF_RCV_FROM_RAMP,
1129                         and  resubmit these packets to table 40 for local de‐
1130                         livery. Packets received  from  ramp  switch  tunnels
1131                         reach  here  because of a lack of logical output port
1132                         field in the tunnel key and thus these packets needed
1133                         to  be  submitted  to table 8 to determine the output
1134                         port.
1135
1136                  •      A higher-priority rule to match packets received from
1137                         ports  of  type localport, based on the logical input
1138                         port, and resubmit these packets to table 40 for  lo‐
1139                         cal  delivery. Ports of type localport exist on every
1140                         hypervisor and by  definition  their  traffic  should
1141                         never go out through a tunnel.
1142
1143                  •      A higher-priority rule to match packets that have the
1144                         MLF_LOCAL_ONLY logical flow flag set, and whose  des‐
1145                         tination  is a multicast address. This flag indicates
1146                         that the packet should not be delivered to remote hy‐
1147                         pervisors, even if the multicast destination includes
1148                         ports on remote hypervisors. This flag is  used  when
1149                         ovn-controller  is  the  originator  of the multicast
1150                         packet. Since each ovn-controller instance is  origi‐
1151                         nating these packets, the packets only need to be de‐
1152                         livered to local ports.
1153
1154                  •      A fallback flow that resubmits to table 40  if  there
1155                         is no other match.
1156
1157                  Flows in table 40 resemble those in table 39 but for logical
1158                  ports that reside locally rather than remotely. For  unicast
1159                  logical  output  ports  on the local hypervisor, the actions
1160                  just resubmit to table 41. For multicast output  ports  that
1161                  include  one  or more logical ports on the local hypervisor,
1162                  for each such logical port P, the actions change the logical
1163                  output port to P, then resubmit to table 41.
1164
1165                  A  special  case  is that when a localnet port exists on the
1166                  datapath, remote port is connected by switching to  the  lo‐
1167                  calnet port. In this case, instead of adding a flow in table
1168                  39 to reach the remote port, a flow is added in table 40  to
1169                  switch  the logical outport to the localnet port, and resub‐
1170                  mit to table 40 as if it were unicasted to a logical port on
1171                  the local hypervisor.
1172
1173                  Table 41 matches and drops packets for which the logical in‐
1174                  put and output ports are the same and the MLF_ALLOW_LOOPBACK
1175                  flag  is  not  set. It also drops MLF_LOCAL_ONLY packets di‐
1176                  rected to a localnet port. It resubmits other packets to ta‐
1177                  ble 42.
1178
1179              4.  OpenFlow  tables  42  through  62 execute the logical egress
1180                  pipeline from the Logical_Flow table in the  OVN  Southbound
1181                  database.  The  egress pipeline can perform a final stage of
1182                  validation before packet delivery. Eventually, it  may  exe‐
1183                  cute  an  output  action, which ovn-controller implements by
1184                  resubmitting to table 64. A packet for  which  the  pipeline
1185                  never  executes  output  is effectively dropped (although it
1186                  may have been transmitted through a tunnel across a physical
1187                  network).
1188
1189                  The egress pipeline cannot change the logical output port or
1190                  cause further tunneling.
1191
1192              5.  Table 64 bypasses OpenFlow loopback when  MLF_ALLOW_LOOPBACK
1193                  is  set. Logical loopback was handled in table 41, but Open‐
1194                  Flow by default  also  prevents  loopback  to  the  OpenFlow
1195                  ingress port. Thus, when MLF_ALLOW_LOOPBACK is set, OpenFlow
1196                  table 64 saves the OpenFlow ingress port, sets it  to  zero,
1197                  resubmits  to  table  65 for logical-to-physical transforma‐
1198                  tion, and then restores the OpenFlow  ingress  port,  effec‐
1199                  tively  disabling  OpenFlow  loopback prevents. When MLF_AL‐
1200                  LOW_LOOPBACK is unset, table 64 flow simply resubmits to ta‐
1201                  ble 65.
1202
1203              6.  OpenFlow  table 65 performs logical-to-physical translation,
1204                  the opposite of table 0. It  matches  the  packet’s  logical
1205                  egress  port.  Its actions output the packet to the port at‐
1206                  tached to the OVN integration bridge  that  represents  that
1207                  logical  port.  If  the  logical  egress port is a container
1208                  nested with a VM, then before sending the packet the actions
1209                  push on a VLAN header with an appropriate VLAN ID.
1210
1211   Logical Routers and Logical Patch Ports
1212       Typically  logical routers and logical patch ports do not have a physi‐
1213       cal location and effectively reside on every hypervisor.  This  is  the
1214       case  for  logical  patch  ports  between  logical  routers and logical
1215       switches behind those logical routers, to which VMs (and VIFs) attach.
1216
1217       Consider a packet sent from one virtual machine or container to another
1218       VM  or  container  that  resides on a different subnet. The packet will
1219       traverse tables 0 to 65 as described in the previous section  Architec‐
1220       tural  Physical Life Cycle of a Packet, using the logical datapath rep‐
1221       resenting the logical switch that the sender is attached to.  At  table
1222       39, the packet will use the fallback flow that resubmits locally to ta‐
1223       ble 40 on the same hypervisor. In this case, all of the processing from
1224       table 0 to table 65 occurs on the hypervisor where the sender resides.
1225
1226       When  the packet reaches table 65, the logical egress port is a logical
1227       patch port. ovn-controller implements output to the  logical  patch  is
1228       packet  by cloning and resubmitting directly to the first OpenFlow flow
1229       table in the ingress pipeline, setting the logical ingress port to  the
1230       peer  logical patch port, and using the peer logical patch port’s logi‐
1231       cal datapath (that represents the logical router).
1232
1233       The packet re-enters the ingress pipeline in order to traverse tables 8
1234       to 65 again, this time using the logical datapath representing the log‐
1235       ical router. The processing continues as described in the previous sec‐
1236       tion  Architectural  Physical  Life  Cycle of a Packet. When the packet
1237       reaches table 65, the logical egress port will once again be a  logical
1238       patch  port.  In the same manner as described above, this logical patch
1239       port will cause the packet to be resubmitted to OpenFlow  tables  8  to
1240       65,  this  time  using  the  logical  datapath representing the logical
1241       switch that the destination VM or container is attached to.
1242
1243       The packet traverses tables 8 to 65 a third and final time. If the des‐
1244       tination  VM or container resides on a remote hypervisor, then table 39
1245       will send the packet on a tunnel port from the sender’s  hypervisor  to
1246       the remote hypervisor. Finally table 65 will output the packet directly
1247       to the destination VM or container.
1248
1249       The following sections describe two exceptions, where  logical  routers
1250       and/or logical patch ports are associated with a physical location.
1251
1252     Gateway Routers
1253
1254       A  gateway router is a logical router that is bound to a physical loca‐
1255       tion. This includes all of the  logical  patch  ports  of  the  logical
1256       router,  as  well  as  all  of  the peer logical patch ports on logical
1257       switches. In the OVN Southbound database, the Port_Binding entries  for
1258       these  logical patch ports use the type l3gateway rather than patch, in
1259       order to distinguish that these logical patch  ports  are  bound  to  a
1260       chassis.
1261
1262       When a hypervisor processes a packet on a logical datapath representing
1263       a logical switch, and the logical egress port is a l3gateway port  rep‐
1264       resenting  connectivity  to  a  gateway router, the packet will match a
1265       flow in table 39 that sends the packet on a tunnel port to the  chassis
1266       where  the  gateway router resides. This processing in table 39 is done
1267       in the same manner as for VIFs.
1268
1269     Distributed Gateway Ports
1270
1271       This section provides additional details on distributed gateway  ports,
1272       outlined earlier.
1273
1274       The  primary  design  goal  of distributed gateway ports is to allow as
1275       much traffic as possible to be handled locally on the hypervisor  where
1276       a  VM  or  container resides. Whenever possible, packets from the VM or
1277       container to the outside world should be processed completely  on  that
1278       VM’s  or  container’s hypervisor, eventually traversing a localnet port
1279       instance or a tunnel to the physical network or a different OVN deploy‐
1280       ment. Whenever possible, packets from the outside world to a VM or con‐
1281       tainer should be directed through the physical network directly to  the
1282       VM’s or container’s hypervisor.
1283
1284       In  order  to allow for the distributed processing of packets described
1285       in the paragraph above, distributed gateway ports need  to  be  logical
1286       patch  ports  that  effectively reside on every hypervisor, rather than
1287       l3gateway ports that are bound to a particular  chassis.  However,  the
1288       flows  associated with distributed gateway ports often need to be asso‐
1289       ciated with physical locations, for the following reasons:
1290
1291              •      The physical network that the localnet port  is  attached
1292                     to  typically uses L2 learning. Any Ethernet address used
1293                     over the distributed gateway port must be restricted to a
1294                     single  physical location so that upstream L2 learning is
1295                     not confused. Traffic sent out  the  distributed  gateway
1296                     port  towards  the localnet port with a specific Ethernet
1297                     address must be sent out one  specific  instance  of  the
1298                     distributed gateway port on one specific chassis. Traffic
1299                     received from the localnet port (or from  a  VIF  on  the
1300                     same logical switch as the localnet port) with a specific
1301                     Ethernet address must be directed to the logical switch’s
1302                     patch port instance on that specific chassis.
1303
1304                     Due  to the implications of L2 learning, the Ethernet ad‐
1305                     dress and IP address of the distributed gateway port need
1306                     to  be restricted to a single physical location. For this
1307                     reason, the user must specify one chassis associated with
1308                     the  distributed gateway port. Note that traffic travers‐
1309                     ing the distributed gateway port using other Ethernet ad‐
1310                     dresses and IP addresses (e.g. one-to-one NAT) is not re‐
1311                     stricted to this chassis.
1312
1313                     Replies to ARP and ND requests must be  restricted  to  a
1314                     single  physical  location, where the Ethernet address in
1315                     the reply resides. This includes ARP and ND  replies  for
1316                     the IP address of the distributed gateway port, which are
1317                     restricted to the chassis that the user  associated  with
1318                     the distributed gateway port.
1319
1320              •      In  order  to support one-to-many SNAT (aka IP masquerad‐
1321                     ing), where multiple logical IP addresses  spread  across
1322                     multiple  chassis  are mapped to a single external IP ad‐
1323                     dress, it will be necessary to handle some of the logical
1324                     router  processing on a specific chassis in a centralized
1325                     manner. Since the SNAT external IP address  is  typically
1326                     the distributed gateway port IP address, and for simplic‐
1327                     ity, the same chassis  associated  with  the  distributed
1328                     gateway port is used.
1329
1330       The  details  of flow restrictions to specific chassis are described in
1331       the ovn-northd documentation.
1332
1333       While most of the physical location dependent  aspects  of  distributed
1334       gateway  ports  can  be  handled  by restricting some flows to specific
1335       chassis, one additional mechanism is required. When a packet leaves the
1336       ingress pipeline and the logical egress port is the distributed gateway
1337       port, one of two different sets of actions is required at table 39:
1338
1339              •      If the packet can be handled locally on the sender’s  hy‐
1340                     pervisor  (e.g.  one-to-one NAT traffic), then the packet
1341                     should just be resubmitted locally to table  40,  in  the
1342                     normal manner for distributed logical patch ports.
1343
1344              •      However, if the packet needs to be handled on the chassis
1345                     associated with the distributed gateway port  (e.g.  one-
1346                     to-many  SNAT  traffic or non-NAT traffic), then table 39
1347                     must send the packet on a tunnel port to that chassis.
1348
1349       In order to trigger the second set of actions, the chassisredirect type
1350       of  southbound  Port_Binding has been added. Setting the logical egress
1351       port to the type chassisredirect logical port is simply a way to  indi‐
1352       cate  that  although the packet is destined for the distributed gateway
1353       port, it needs to be redirected to a different chassis.  At  table  39,
1354       packets  with  this logical egress port are sent to a specific chassis,
1355       in the same way that table 39 directs packets whose logical egress port
1356       is a VIF or a type l3gateway port to different chassis. Once the packet
1357       arrives at that chassis, table 40 resets the logical egress port to the
1358       value  representing  the distributed gateway port. For each distributed
1359       gateway port, there is one type chassisredirect port,  in  addition  to
1360       the distributed logical patch port representing the distributed gateway
1361       port.
1362
1363     High Availability for Distributed Gateway Ports
1364
1365       OVN allows you to specify a prioritized list of chassis for a  distrib‐
1366       uted gateway port. This is done by associating multiple Gateway_Chassis
1367       rows with a Logical_Router_Port in the OVN_Northbound database.
1368
1369       When multiple chassis have been specified for a  gateway,  all  chassis
1370       that may send packets to that gateway will enable BFD on tunnels to all
1371       configured gateway chassis. The current master chassis for the  gateway
1372       is the highest priority gateway chassis that is currently viewed as ac‐
1373       tive based on BFD status.
1374
1375       For more information on L3 gateway high availability, please  refer  to
1376       http://docs.ovn.org/en/latest/topics/high-availability.html.
1377
1378     Restrictions of Distributed Gateway Ports
1379
1380       Distributed  gateway  ports are used to connect to an external network,
1381       which can be a physical network modeled by a logical switch with a  lo‐
1382       calnet  port,  and can also be a logical switch that interconnects dif‐
1383       ferent OVN deployments (see OVN Deployments  Interconnection).  Usually
1384       there  can be many logical routers connected to the same external logi‐
1385       cal switch, as shown in below diagram.
1386
1387                                     +--LS-EXT-+
1388                                     |    |    |
1389                                     |    |    |
1390                                    LR1  ...  LRn
1391
1392
1393       In this diagram, there are n logical routers  connected  to  a  logical
1394       switch  LS-EXT,  each  with a distributed gateway port, so that traffic
1395       sent to external world is redirected to the gateway chassis that is as‐
1396       signed to the distributed gateway port of respective logical router.
1397
1398       In the logical topology, nothing can prevent an user to add a route be‐
1399       tween the logical routers via the connected distributed  gateway  ports
1400       on  LS-EXT.  However,  the route works only if the LS-EXT is a physical
1401       network (modeled by a logical switch with a  localnet  port).  In  that
1402       case the packet will be delivered between the gateway chassises through
1403       the localnet port via physical network. If the LS-EXT is a regular log‐
1404       ical switch (backed by tunneling only, as in the use case of OVN inter‐
1405       connection), then the packet will be  dropped  on  the  source  gateway
1406       chassis.  The limitation is due the fact that distributed gateway ports
1407       are tied to physical location, and without physical network connection,
1408       we  will end up with either dropping the packet or transferring it over
1409       the tunnels which could cause bigger problems such as broadcast packets
1410       being redirect repeatedly by different gateway chassises.
1411
1412       With  the limitation in mind, if a user do want the direct connectivity
1413       between the logical routers, it is better to create an internal logical
1414       switch  connected  to  the  logical routers with regular logical router
1415       ports, which are completely distributed and the packets don’t  have  to
1416       leave  a  chassis  unless necessary, which is more optimal than routing
1417       via the distributed gateway ports.
1418
1419     ARP request and ND NS packet processing
1420
1421       Due to the fact that ARP requests and ND NA packets are usually  broad‐
1422       cast  packets,  for  performance  reasons, OVN deals with requests that
1423       target OVN owned IP addresses (i.e., IP  addresses  configured  on  the
1424       router  ports,  VIPs, NAT IPs) in a specific way and only forwards them
1425       to the logical router that owns the target IP address. This behavior is
1426       different  than  that  of  traditional  switches and implies that other
1427       routers/hosts connected to the logical switch will not learn the MAC/IP
1428       binding from the request packet.
1429
1430       All other ARP and ND packets are flooded in the L2 broadcast domain and
1431       to all attached logical patch ports.
1432
1433     VIFs on the logical switch connected by a distributed gateway port
1434
1435       Typically the logical switch connected by a distributed gateway port is
1436       for  external connectivity, usually to a physical network through a lo‐
1437       calnet port on the logical  switch,  or  to  a  remote  OVN  deployment
1438       through  OVN  Interconnection. In these cases there is no VIF ports re‐
1439       quired on the logical switch.
1440
1441       While not very common, it is still possible to create VIF ports on  the
1442       logical  switch connected by a distributed gateway port, but there is a
1443       limitation that the logical ports need to reside on the gateway chassis
1444       where the distributed gateway port resides to get connectivity to other
1445       logical switches through the distributed gateway port. There is no lim‐
1446       itation  for  the  VIFs to connect within the logical switch, or beyond
1447       the logical switch through other  regular  distributed  logical  router
1448       ports.
1449
1450       A  special case is when using distributed gateway ports for scalability
1451       purpose, as mentioned earlier in this document.  The  logical  switches
1452       connected  by  distributed  gateway  ports are not for connectivity but
1453       just for regular VIFs. However, the above limitation usually  does  not
1454       matter  because in this use case all the VIFs on the logical switch are
1455       located on the same chassis with the distributed gateway port that con‐
1456       nects the logical switch.
1457
1458   Multiple localnet logical switches connected to a Logical Router
1459       It  is  possible to have multiple logical switches each with a localnet
1460       port (representing physical networks) connected to a logical router, in
1461       which one localnet logical switch may provide the external connectivity
1462       via a distributed  gateway  port  and  rest  of  the  localnet  logical
1463       switches  use VLAN tagging in the physical network. It is expected that
1464       ovn-bridge-mappings is configured appropriately on the chassis for  all
1465       these localnet networks.
1466
1467     East West routing
1468
1469       East-West  routing  between these localnet VLAN tagged logical switches
1470       work almost the same way as normal logical switches. When the VM  sends
1471       such a packet, then:
1472
1473              1.  It  first enters the ingress pipeline, and then egress pipe‐
1474                  line of the source localnet logical switch datapath. It then
1475                  enters  the  ingress pipeline of the logical router datapath
1476                  via the logical router port in the source chassis.
1477
1478              2.  Routing decision is taken.
1479
1480              3.  From the router datapath, packet enters the ingress pipeline
1481                  and then egress pipeline of the destination localnet logical
1482                  switch datapath and goes out of the  integration  bridge  to
1483                  the  provider  bridge ( belonging to the destination logical
1484                  switch) via the localnet port. While sending the  packet  to
1485                  provider  bridge,  we also replace router port MAC as source
1486                  MAC with a chassis unique MAC.
1487
1488                  This chassis unique MAC is configured as global  ovs  config
1489                  on each chassis (eg. via "ovs-vsctl set open . external-ids:
1490                  ovn-chassis-mac-mappings="phys:aa:bb:cc:dd:ee:$i$i"").   For
1491                  more details, see ovn-controller(8).
1492
1493                  If the above is not configured, then source MAC would be the
1494                  router port MAC. This could create problem if we  have  more
1495                  than  one chassis. This is because, since the router port is
1496                  distributed, the same (MAC,VLAN) tuple will seen by physical
1497                  network  from other chassis as well, which could cause these
1498                  issues:
1499
1500                  •      Continuous MAC moves in top-of-rack switch (ToR).
1501
1502                  •      ToR dropping the traffic, which is causing continuous
1503                         MAC moves.
1504
1505                  •      ToR  blocking the ports from which MAC moves are hap‐
1506                         pening.
1507
1508              4.  The destination chassis receives the packet via the localnet
1509                  port and sends it to the integration bridge. Before entering
1510                  the integration bridge the source mac of the packet will  be
1511                  replaced  with  router port mac again. The packet enters the
1512                  ingress pipeline and then egress pipeline of the destination
1513                  localnet  logical  switch  and finally gets delivered to the
1514                  destination VM port.
1515
1516     External traffic
1517
1518       The following happens when a VM sends an external  traffic  (which  re‐
1519       quires  NATting) and the chassis hosting the VM doesn’t have a distrib‐
1520       uted gateway port.
1521
1522              1.  The packet first  enters  the  ingress  pipeline,  and  then
1523                  egress  pipeline of the source localnet logical switch data‐
1524                  path. It then enters the ingress  pipeline  of  the  logical
1525                  router  datapath  via  the logical router port in the source
1526                  chassis.
1527
1528              2.  Routing decision is taken. Since the gateway router  or  the
1529                  distributed  gateway port doesn’t reside in the source chas‐
1530                  sis, the traffic is redirected to the  gateway  chassis  via
1531                  the tunnel port.
1532
1533              3.  The  gateway chassis receives the packet via the tunnel port
1534                  and the packet enters the egress  pipeline  of  the  logical
1535                  router datapath. NAT rules are applied here. The packet then
1536                  enters the ingress pipeline and then egress pipeline of  the
1537                  localnet  logical  switch  datapath  which provides external
1538                  connectivity and finally goes out via the localnet  port  of
1539                  the logical switch which provides external connectivity.
1540
1541       Although  this  works,  the  VM traffic is tunnelled when sent from the
1542       compute chassis to the gateway chassis. In order for it to  work  prop‐
1543       erly,  the  MTU of the localnet logical switches must be lowered to ac‐
1544       count for the tunnel encapsulation.
1545
1546   Centralized routing for localnet VLAN tagged logical switches connected  to
1547       a Logical Router
1548       To  overcome the tunnel encapsulation problem described in the previous
1549       section, OVN supports the option of enabling  centralized  routing  for
1550       localnet VLAN tagged logical switches. CMS can configure the option op‐
1551       tions:reside-on-redirect-chassis to true for  each  Logical_Router_Port
1552       which  connects  to  the  localnet  VLAN  tagged logical switches. This
1553       causes the gateway chassis (hosting the distributed  gateway  port)  to
1554       handle  all  the  routing for these networks, making it centralized. It
1555       will reply to the ARP requests for the logical router port IPs.
1556
1557       If the logical router doesn’t have a distributed gateway port  connect‐
1558       ing  to  the localnet logical switch which provides external connectiv‐
1559       ity, or if it has more than one distributed gateway  ports,  then  this
1560       option is ignored by OVN.
1561
1562       The  following happens when a VM sends an east-west traffic which needs
1563       to be routed:
1564
1565              1.  The packet first  enters  the  ingress  pipeline,  and  then
1566                  egress  pipeline of the source localnet logical switch data‐
1567                  path and is sent out via a localnet port of the  source  lo‐
1568                  calnet logical switch (instead of sending it to router pipe‐
1569                  line).
1570
1571              2.  The gateway chassis receives the packet via a localnet  port
1572                  of  the  source  localnet logical switch and sends it to the
1573                  integration bridge. The packet then enters the ingress pipe‐
1574                  line,  and then egress pipeline of the source localnet logi‐
1575                  cal switch datapath and enters the ingress pipeline  of  the
1576                  logical router datapath.
1577
1578              3.  Routing decision is taken.
1579
1580              4.  From the router datapath, packet enters the ingress pipeline
1581                  and then egress pipeline of the destination localnet logical
1582                  switch  datapath. It then goes out of the integration bridge
1583                  to the provider bridge ( belonging to the destination  logi‐
1584                  cal switch) via a localnet port.
1585
1586              5.  The  destination  chassis receives the packet via a localnet
1587                  port and sends it to the integration bridge. The packet  en‐
1588                  ters  the  ingress  pipeline and then egress pipeline of the
1589                  destination localnet logical switch and finally delivered to
1590                  the destination VM port.
1591
1592       The  following  happens  when  a VM sends an external traffic which re‐
1593       quires NATting:
1594
1595              1.  The packet first  enters  the  ingress  pipeline,  and  then
1596                  egress  pipeline of the source localnet logical switch data‐
1597                  path and is sent out via a localnet port of the  source  lo‐
1598                  calnet logical switch (instead of sending it to router pipe‐
1599                  line).
1600
1601              2.  The gateway chassis receives the packet via a localnet  port
1602                  of  the  source  localnet logical switch and sends it to the
1603                  integration bridge. The packet then enters the ingress pipe‐
1604                  line,  and then egress pipeline of the source localnet logi‐
1605                  cal switch datapath and enters the ingress pipeline  of  the
1606                  logical router datapath.
1607
1608              3.  Routing decision is taken and NAT rules are applied.
1609
1610              4.  From the router datapath, packet enters the ingress pipeline
1611                  and then egress pipeline  of  the  localnet  logical  switch
1612                  datapath  which provides external connectivity. It then goes
1613                  out of the integration bridge to the  provider  bridge  (be‐
1614                  longing  to  the logical switch which provides external con‐
1615                  nectivity) via a localnet port.
1616
1617       The following happens for the reverse external traffic.
1618
1619              1.  The gateway chassis receives the packet from a localnet port
1620                  of  the logical switch which provides external connectivity.
1621                  The packet then enters the ingress pipeline and then  egress
1622                  pipeline  of the localnet logical switch (which provides ex‐
1623                  ternal connectivity). The packet  then  enters  the  ingress
1624                  pipeline of the logical router datapath.
1625
1626              2.  The  ingress pipeline of the logical router datapath applies
1627                  the unNATting rules. The  packet  then  enters  the  ingress
1628                  pipeline  and  then  egress  pipeline of the source localnet
1629                  logical switch. Since the source VM doesn’t  reside  in  the
1630                  gateway  chassis, the packet is sent out via a localnet port
1631                  of the source logical switch.
1632
1633              3.  The source chassis receives the packet via a  localnet  port
1634                  and  sends  it  to the integration bridge. The packet enters
1635                  the ingress pipeline and then egress pipeline of the  source
1636                  localnet  logical  switch  and finally gets delivered to the
1637                  source VM port.
1638
1639       As an alternative to  reside-on-redirect-chassis,  OVN  supports  VLAN-
1640       based  redirection.  Whereas reside-on-redirect-chassis centralizes all
1641       router functionality, VLAN-based redirection only changes how OVN redi‐
1642       rects  packets to the gateway chassis. By setting options:redirect-type
1643       to bridged on a distributed gateway port, OVN redirects packets to  the
1644       gateway  chassis  using  the localnet port of the router’s peer logical
1645       switch, instead of a tunnel.
1646
1647       If the logical router doesn’t have a distributed gateway port  connect‐
1648       ing  to  the localnet logical switch which provides external connectiv‐
1649       ity, or if it has more than one distributed gateway  ports,  then  this
1650       option is ignored by OVN.
1651
1652       Following happens for bridged redirection:
1653
1654              1.  On  compute  chassis,  packet passes though logical router’s
1655                  ingress pipeline.
1656
1657              2.  If logical outport is gateway chassis attached  router  port
1658                  then  packet  is  "redirected" to gateway chassis using peer
1659                  logical switch’s localnet port.
1660
1661              3.  This redirected packet has destination mac  as  router  port
1662                  mac (the one to which gateway chassis is attached). Its VLAN
1663                  id is that of localnet port (peer logical switch of the log‐
1664                  ical router port).
1665
1666              4.  On  the gateway chassis packet will enter the logical router
1667                  pipeline again and this  time  it  will  passthrough  egress
1668                  pipeline as well.
1669
1670              5.  Reverse traffic packet flows stays the same.
1671
1672       Some guidelines and expections with bridged redirection:
1673
1674              1.  Since router port mac is destination mac, hence it has to be
1675                  ensured that physical network learns it  on  ONLY  from  the
1676                  gateway  chassis.  Which means that ovn-chassis-mac-mappings
1677                  should be configure on all the compute nodes, so that physi‐
1678                  cal network never learn router port mac from compute nodes.
1679
1680              2.  Since  packet  enters  logical router ingress pipeline twice
1681                  (once on compute chassis  and  again  on  gateway  chassis),
1682                  hence ttl will be decremented twice.
1683
1684              3.  Default  redirection  type continues to be overlay. User can
1685                  switch the redirect-type  between  bridged  and  overlay  by
1686                  changing the value of options:redirect-type
1687
1688   Life Cycle of a VTEP gateway
1689       A  gateway  is  a chassis that forwards traffic between the OVN-managed
1690       part of a logical network and a physical VLAN, extending a tunnel-based
1691       logical network into a physical network.
1692
1693       The  steps  below  refer  often to details of the OVN and VTEP database
1694       schemas. Please see ovn-sb(5), ovn-nb(5) and vtep(5), respectively, for
1695       the full story on these databases.
1696
1697              1.  A  VTEP  gateway’s  life cycle begins with the administrator
1698                  registering the VTEP gateway as a Physical_Switch table  en‐
1699                  try  in the VTEP database. The ovn-controller-vtep connected
1700                  to this VTEP database, will recognize the new  VTEP  gateway
1701                  and  create  a  new  Chassis  table  entry  for  it  in  the
1702                  OVN_Southbound database.
1703
1704              2.  The administrator can then create a new Logical_Switch table
1705                  entry,  and  bind a particular vlan on a VTEP gateway’s port
1706                  to any VTEP logical switch. Once a VTEP  logical  switch  is
1707                  bound to a VTEP gateway, the ovn-controller-vtep will detect
1708                  it and add its name to the vtep_logical_switches  column  of
1709                  the  Chassis table in the OVN_Southbound database. Note, the
1710                  tunnel_key column of VTEP logical switch is  not  filled  at
1711                  creation.  The  ovn-controller-vtep will set the column when
1712                  the corresponding vtep logical switch is  bound  to  an  OVN
1713                  logical network.
1714
1715              3.  Now, the administrator can use the CMS to add a VTEP logical
1716                  switch to the OVN logical network. To do that, the CMS  must
1717                  first  create  a  new Logical_Switch_Port table entry in the
1718                  OVN_Northbound database. Then, the type column of this entry
1719                  must  be  set  to  "vtep". Next, the vtep-logical-switch and
1720                  vtep-physical-switch keys in the options column must also be
1721                  specified,  since  multiple  VTEP gateways can attach to the
1722                  same VTEP logical switch. Next, the addresses column of this
1723                  logical  port must be set to "unknown", it will add a prior‐
1724                  ity 0 entry  in  "ls_in_l2_lkup"  stage  of  logical  switch
1725                  ingress  pipeline.  So,  traffic  with unrecorded mac by OVN
1726                  would go through the Logical_Switch_Port  to  physical  net‐
1727                  work.
1728
1729              4.  The  newly  created logical port in the OVN_Northbound data‐
1730                  base and its  configuration  will  be  passed  down  to  the
1731                  OVN_Southbound  database  as a new Port_Binding table entry.
1732                  The ovn-controller-vtep will recognize the change  and  bind
1733                  the  logical port to the corresponding VTEP gateway chassis.
1734                  Configuration of binding the same VTEP logical switch  to  a
1735                  different  OVN logical networks is not allowed and a warning
1736                  will be generated in the log.
1737
1738              5.  Beside binding to the VTEP  gateway  chassis,  the  ovn-con‐
1739                  troller-vtep  will  update the tunnel_key column of the VTEP
1740                  logical switch to the corresponding  Datapath_Binding  table
1741                  entry’s tunnel_key for the bound OVN logical network.
1742
1743              6.  Next, the ovn-controller-vtep will keep reacting to the con‐
1744                  figuration change in the Port_Binding in the  OVN_Northbound
1745                  database,  and  updating  the Ucast_Macs_Remote table in the
1746                  VTEP database. This allows the VTEP  gateway  to  understand
1747                  where  to  forward  the  unicast traffic coming from the ex‐
1748                  tended external network.
1749
1750              7.  Eventually, the VTEP gateway’s life cycle ends when the  ad‐
1751                  ministrator unregisters the VTEP gateway from the VTEP data‐
1752                  base. The ovn-controller-vtep will recognize the  event  and
1753                  remove  all  related configurations (Chassis table entry and
1754                  port bindings) in the OVN_Southbound database.
1755
1756              8.  When the ovn-controller-vtep is terminated, all related con‐
1757                  figurations  in  the  OVN_Southbound  database  and the VTEP
1758                  database will be cleaned, including  Chassis  table  entries
1759                  for  all  registered  VTEP gateways and their port bindings,
1760                  and  all  Ucast_Macs_Remote  table  entries  and  the  Logi‐
1761                  cal_Switch tunnel keys.
1762
1763   OVN Deployments Interconnection
1764       It is not uncommon for an operator to deploy multiple OVN clusters, for
1765       two main reasons. Firstly, an operator may prefer  to  deploy  one  OVN
1766       cluster for each availability zone, e.g. in different physical regions,
1767       to avoid single point of failure. Secondly, there is  always  an  upper
1768       limit for a single OVN control plane to scale.
1769
1770       Although  the  control  planes of the different availability zone (AZ)s
1771       are independent from each other, the workloads from different  AZs  may
1772       need  to  communicate across the zones. The OVN interconnection feature
1773       provides a native way to  interconnect  different  AZs  by  L3  routing
1774       through  transit  overlay networks between logical routers of different
1775       AZs.
1776
1777       A global OVN Interconnection Northbound database is introduced for  the
1778       operator  (probably  through  CMS systems) to configure transit logical
1779       switches that connect logical routers from  different  AZs.  A  transit
1780       switch  is  similar to a regular logical switch, but it is used for in‐
1781       terconnection purpose only. Typically, each transit switch can be  used
1782       to  connect  all  logical routers that belong to same tenant across all
1783       AZs.
1784
1785       A dedicated daemon process ovn-ic, OVN interconnection  controller,  in
1786       each  AZ  will  consume  this  data  and populate corresponding logical
1787       switches to their own northbound databases for each AZ, so that logical
1788       routers  can  be connected to the transit switch by creating patch port
1789       pairs in their northbound databases. Any router ports connected to  the
1790       transit  switches  are  considered interconnection ports, which will be
1791       exchanged between AZs.
1792
1793       Physically, when workloads from different AZs communicate, packets need
1794       to  go  through multiple hops: source chassis, source gateway, destina‐
1795       tion gateway and destination chassis.  All  these  hops  are  connected
1796       through  tunnels  so  that  the packets never leave overlay networks. A
1797       distributed gateway port is required to connect the logical router to a
1798       transit  switch,  with a gateway chassis specified, so that the traffic
1799       can be forwarded through the gateway chassis.
1800
1801       A global OVN Interconnection Southbound database is introduced for  ex‐
1802       changing  control  plane  information between the AZs. The data in this
1803       database is populated and consumed by the ovn-ic, of each AZ. The  main
1804       information in this database includes:
1805
1806              •      Datapath bindings for transit switches, which mainly con‐
1807                     tains the tunnel keys generated for each transit  switch.
1808                     Separate  key ranges are reserved for transit switches so
1809                     that they will never conflict with any  tunnel  keys  lo‐
1810                     cally assigned for datapaths within each AZ.
1811
1812              •      Availability  zones,  which are registered by ovn-ic from
1813                     each AZ.
1814
1815              •      Gateways. Each AZ specifies chassises that  are  supposed
1816                     to  work as interconnection gateways, and the ovn-ic will
1817                     populate this information to the  interconnection  south‐
1818                     bound  DB.  The  ovn-ic from all the other AZs will learn
1819                     the gateways and populate to their own southbound DB as a
1820                     chassis.
1821
1822              •      Port  bindings  for  logical  switch ports created on the
1823                     transit switch. Each AZ maintains their logical router to
1824                     transit  switch connections independently, but ovn-ic au‐
1825                     tomatically populates  local  port  bindings  on  transit
1826                     switches to the global interconnection southbound DB, and
1827                     learns remote port bindings from other AZs  back  to  its
1828                     own  northbound and southbound DBs, so that logical flows
1829                     can be produced and then translated to OVS flows locally,
1830                     which finally enables data plane communication.
1831
1832              •      Routes  that are advertised between different AZs. If en‐
1833                     abled, routes are automatically exchanged by ovn-ic. Both
1834                     static  routes  and directly connected subnets are adver‐
1835                     tised. Options in options column of the  NB_Global  table
1836                     of  OVN_NB  database control the behavior of route adver‐
1837                     tisement, such as enable/disable the advertising/learning
1838                     routes,  whether  default  routes are advertised/learned,
1839                     and blacklisted CIDRs. See ovn-nb(5) for more details.
1840
1841       The tunnel keys for transit switch datapaths and related port  bindings
1842       must  be agreed across all AZs. This is ensured by generating and stor‐
1843       ing the keys in the global  interconnection  southbound  database.  Any
1844       ovn-ic from any AZ can allocate the key, but race conditions are solved
1845       by enforcing unique index for the column in the database.
1846
1847       Once each AZ’s NB and SB databases are populated  with  interconnection
1848       switches  and ports, and agreed upon the tunnel keys, data plane commu‐
1849       nication between the AZs are established.
1850
1851       When VXLAN tunneling is enabled in an OVN cluster, due to  the  limited
1852       range available for VNIs, Interconnection feature is not supported.
1853
1854     A day in the life of a packet crossing AZs
1855
1856              1.  An IP packet is sent out from a VIF on a hypervisor (HV1) of
1857                  AZ1, with destination IP belonging to a VIF in AZ2.
1858
1859              2.  In HV1’s OVS flow tables, the packet  goes  through  logical
1860                  switch and logical router pipelines, and in a logical router
1861                  pipeline, the routing stage finds out the next hop  for  the
1862                  destination  IP,  which  belongs  to a remote logical router
1863                  port in AZ2, and the output port, which is  a  chassis-redi‐
1864                  rect  port  located  on  an  interconnection gateway (GW1 in
1865                  AZ1), so HV1 sends the packet to GW1 through tunnel.
1866
1867              3.  On GW1, it continues with the logical router pipe  line  and
1868                  switches  to  the transit switch’s pipeline through the peer
1869                  port of the chassis redirect port. In the  transit  switch’s
1870                  pipeline  it outputs to the remote logical port which is lo‐
1871                  cated on a gateway (GW2) in AZ2, so the GW1 sends the packet
1872                  to GW2 in tunnel.
1873
1874              4.  On  GW2,  it  continues with the transit switch pipeline and
1875                  switches to the logical router  pipeline  through  the  peer
1876                  port,  which  is  a chassis redirect port that is located on
1877                  GW2. The logical router pipeline then forwards the packet to
1878                  relevant  logical  pipelines according to the destination IP
1879                  address, and figures out the MAC and location of the  desti‐
1880                  nation VIF port - a hypervisor (HV2). The GW2 then sends the
1881                  packet to HV2 in tunnel.
1882
1883              5.  On HV2, the packet is delivered to the final destination VIF
1884                  port  by  the  logical switch egress pipeline, just the same
1885                  way as for intra-AZ communications.
1886
1887   Native OVN services for external logical ports
1888       To support OVN native services (like DHCP/IPv6 RA/DNS  lookup)  to  the
1889       cloud  resources  which  are  external,  OVN  supports external logical
1890       ports.
1891
1892       Below are some of the use cases where external ports can be used.
1893
1894              •      VMs connected to SR-IOV nics - Traffic from these VMs  by
1895                     passes  the  kernel stack and local ovn-controller do not
1896                     bind these ports and cannot serve the native services.
1897
1898              •      When CMS supports provisioning baremetal servers.
1899
1900       OVN will provide the native services if CMS has done the below configu‐
1901       ration in the OVN Northbound Database.
1902
1903              •      A  row is created in Logical_Switch_Port, configuring the
1904                     addresses column and setting the type to external.
1905
1906ha_chassis_group column is configured.
1907
1908              •      The HA chassis which belongs to the HA chassis group  has
1909                     the ovn-bridge-mappings configured and has proper L2 con‐
1910                     nectivity so that it can receive the DHCP and  other  re‐
1911                     lated request packets from these external resources.
1912
1913              •      The Logical_Switch of this port has a localnet port.
1914
1915              •      Native  OVN  services are enabled by configuring the DHCP
1916                     and other options like the way it is done for the  normal
1917                     logical ports.
1918
1919       It is recommended to use the same HA chassis group for all the external
1920       ports of a logical switch. Otherwise, the physical switch might see MAC
1921       flap  issue when different chassis provide the native services. For ex‐
1922       ample when supporting native DHCPv4 service, DHCPv4 server mac (config‐
1923       ured  in  options:server_mac  column in table DHCP_Options) originating
1924       from different ports can cause MAC flap issue. The MAC of  the  logical
1925       router  IP(s) can also flap if the same HA chassis group is not set for
1926       all the external ports of a logical switch.
1927

SECURITY

1929   Role-Based Access Controls for the Southbound DB
1930       In order to provide additional security against the possibility  of  an
1931       OVN  chassis becoming compromised in such a way as to allow rogue soft‐
1932       ware to make arbitrary modifications to the southbound  database  state
1933       and  thus  disrupt  the  OVN  network,  role-based access controls (see
1934       ovsdb-server(1) for additional details) are provided for the southbound
1935       database.
1936
1937       The  implementation  of  role-based access controls (RBAC) requires the
1938       addition of two tables to an OVSDB schema: the RBAC_Role  table,  which
1939       is  indexed  by  role name and maps the the names of the various tables
1940       that may be modifiable for a given role to individual rows in a permis‐
1941       sions  table  containing detailed permission information for that role,
1942       and the permission table itself which consists of rows  containing  the
1943       following information:
1944
1945              Table Name
1946                     The name of the associated table. This column exists pri‐
1947                     marily as an aid for humans reading the contents of  this
1948                     table.
1949
1950              Auth Criteria
1951                     A set of strings containing the names of columns (or col‐
1952                     umn:key pairs for columns containing string:string maps).
1953                     The contents of at least one of the columns or column:key
1954                     values in a row to be modified, inserted, or deleted must
1955                     be equal to the ID of the client attempting to act on the
1956                     row in order for the authorization check to pass. If  the
1957                     authorization  criteria  is empty, authorization checking
1958                     is disabled and all clients for the role will be  treated
1959                     as authorized.
1960
1961              Insert/Delete
1962                     Row insertion/deletion permission; boolean value indicat‐
1963                     ing whether insertion and deletion of rows is allowed for
1964                     the  associated table. If true, insertion and deletion of
1965                     rows is allowed for authorized clients.
1966
1967              Updatable Columns
1968                     A set of strings containing the names of columns or  col‐
1969                     umn:key  pairs  that  may be updated or mutated by autho‐
1970                     rized clients. Modifications to columns within a row  are
1971                     only  permitted  when  the  authorization  check  for the
1972                     client passes and all columns to be modified are included
1973                     in this set of modifiable columns.
1974
1975       RBAC  configuration  for  the  OVN southbound database is maintained by
1976       ovn-northd. With RBAC enabled, modifications are only permitted for the
1977       Chassis,  Encap,  Port_Binding,  and  MAC_Binding  tables,  and are re‐
1978       stricted as follows:
1979
1980              Chassis
1981                     Authorization: client ID must match the chassis name.
1982
1983                     Insert/Delete: authorized row insertion and deletion  are
1984                     permitted.
1985
1986                     Update:  The  columns  nb_cfg,  external_ids, encaps, and
1987                     vtep_logical_switches may be modified when authorized.
1988
1989              Encap  Authorization: client ID must match the chassis name.
1990
1991                     Insert/Delete: row insertion and row deletion are permit‐
1992                     ted.
1993
1994                     Update:  The  columns  type, options, and ip can be modi‐
1995                     fied.
1996
1997              Port_Binding
1998                     Authorization: disabled (all clients are  considered  au‐
1999                     thorized.  A  future enhancement may add columns (or keys
2000                     to external_ids) in order to control  which  chassis  are
2001                     allowed to bind each port.
2002
2003                     Insert/Delete:  row  insertion/deletion are not permitted
2004                     (ovn-northd maintains rows in this table.
2005
2006                     Update: Only modifications to the chassis column are per‐
2007                     mitted.
2008
2009              MAC_Binding
2010                     Authorization: disabled (all clients are considered to be
2011                     authorized).
2012
2013                     Insert/Delete: row insertion/deletion are permitted.
2014
2015                     Update: The columns logical_port, ip, mac,  and  datapath
2016                     may be modified by ovn-controller.
2017
2018              IGMP_Group
2019                     Authorization: disabled (all clients are considered to be
2020                     authorized).
2021
2022                     Insert/Delete: row insertion/deletion are permitted.
2023
2024                     Update: The columns address, chassis, datapath, and ports
2025                     may be modified by ovn-controller.
2026
2027       Enabling RBAC for ovn-controller connections to the southbound database
2028       requires the following steps:
2029
2030              1.  Creating SSL certificates for each chassis with the certifi‐
2031                  cate  CN  field  set to the chassis name (e.g. for a chassis
2032                  with  external-ids:system-id=chassis-1,  via   the   command
2033                  "ovs-pki -u req+sign chassis-1 switch").
2034
2035              2.  Configuring  each  ovn-controller to use SSL when connecting
2036                  to the southbound database (e.g. via "ovs-vsctl set  open  .
2037                  external-ids:ovn-remote=ssl:x.x.x.x:6642").
2038
2039              3.  Configuring  a southbound database SSL remote with "ovn-con‐
2040                  troller"   role   (e.g.   via   "ovn-sbctl    set-connection
2041                  role=ovn-controller pssl:6642").
2042
2043   Encrypt Tunnel Traffic with IPsec
2044       OVN  tunnel  traffic  goes through physical routers and switches. These
2045       physical devices could be untrusted  (devices  in  public  network)  or
2046       might  be  compromised.  Enabling  encryption to the tunnel traffic can
2047       prevent the traffic data from being monitored and manipulated.
2048
2049       The tunnel traffic is encrypted with IPsec. The CMS sets the ipsec col‐
2050       umn in the northbound NB_Global table to enable or disable IPsec encry‐
2051       tion. If ipsec is true, all OVN tunnels will be encrypted. If ipsec  is
2052       false, no OVN tunnels will be encrypted.
2053
2054       When  CMS  updates  the ipsec column in the northbound NB_Global table,
2055       ovn-northd copies the value to  the  ipsec  column  in  the  southbound
2056       SB_Global table. ovn-controller in each chassis monitors the southbound
2057       database and sets the options of the OVS tunnel interface  accordingly.
2058       OVS  tunnel  interface  options  are monitored by the ovs-monitor-ipsec
2059       daemon which configures IKE daemon to set up IPsec connections.
2060
2061       Chassis authenticates each other by using certificate. The  authentica‐
2062       tion  succeeds if the other end in tunnel presents a certificate signed
2063       by a trusted CA and the common name (CN) matches the  expected  chassis
2064       name.  The  SSL  certificates used in role-based access controls (RBAC)
2065       can be used in IPsec. Or use ovs-pki to create different  certificates.
2066       The  certificate  is  required to be x.509 version 3, and with CN field
2067       and subjectAltName field being set to the chassis name.
2068
2069       The CA certificate, chassis certificate and private key are required to
2070       be  installed  in  each  chassis  before  enabling  IPsec.  Please  see
2071       ovs-vswitchd.conf.db(5) for setting up CA based IPsec authentication.
2072

DESIGN DECISIONS

2074   Tunnel Encapsulations
2075       In general, OVN annotates logical network packets that  it  sends  from
2076       one  hypervisor to another with the following three pieces of metadata,
2077       which are encoded in an encapsulation-specific fashion:
2078
2079              •      24-bit logical datapath identifier, from  the  tunnel_key
2080                     column in the OVN Southbound Datapath_Binding table.
2081
2082              •      15-bit  logical ingress port identifier. ID 0 is reserved
2083                     for internal use within OVN. IDs 1 through 32767,  inclu‐
2084                     sive,  may  be  assigned  to  logical ports (see the tun‐
2085                     nel_key column in the OVN Southbound Port_Binding table).
2086
2087              •      16-bit logical egress  port  identifier.  IDs  0  through
2088                     32767 have the same meaning as for logical ingress ports.
2089                     IDs 32768 through 65535, inclusive, may  be  assigned  to
2090                     logical  multicast  groups  (see the tunnel_key column in
2091                     the OVN Southbound Multicast_Group table).
2092
2093       When VXLAN is enabled on any hypervisor  in  a  cluster,  datapath  and
2094       egress  port identifier ranges are reduced to 12-bits. This is done be‐
2095       cause only STT and Geneve provide the large space for metadata (over 32
2096       bits per packet). To accommodate for VXLAN, 24 bits available are split
2097       as follows:
2098
2099              •      12-bit logical datapath identifier, derived from the tun‐
2100                     nel_key column in the OVN Southbound Datapath_Binding ta‐
2101                     ble.
2102
2103              •      12-bit logical egress port identifier. IDs 0 through 2047
2104                     are used for unicast output ports. IDs 2048 through 4095,
2105                     inclusive, may be assigned to  logical  multicast  groups
2106                     (see  the  tunnel_key column in the OVN Southbound Multi‐
2107                     cast_Group table). For multicast  group  tunnel  keys,  a
2108                     special  mapping  scheme  is used to internally transform
2109                     from internal OVN 16-bit keys  to  12-bit  values  before
2110                     sending  packets  through  a  VXLAN tunnel, and back from
2111                     12-bit tunnel keys to 16-bit values when receiving  pack‐
2112                     ets from a VXLAN tunnel.
2113
2114              •      No logical ingress port identifier.
2115
2116       The limited space available for metadata when VXLAN tunnels are enabled
2117       in a cluster put the following  functional  limitations  onto  features
2118       available to users:
2119
2120              •      The maximum number of networks is reduced to 4096.
2121
2122              •      The  maximum  number  of  ports per network is reduced to
2123                     2048.
2124
2125              •      ACLs matching against logical  ingress  port  identifiers
2126                     are not supported.
2127
2128              •      OVN interconnection feature is not supported.
2129
2130       In  addition  to  functional limitations described above, the following
2131       should be considered before enabling it in your cluster:
2132
2133              •      STT and Geneve use randomized UDP  or  TCP  source  ports
2134                     that  allows  efficient distribution among multiple paths
2135                     in environments that use ECMP in their underlay.
2136
2137              •      NICs are available to offload STT and  Geneve  encapsula‐
2138                     tion and decapsulation.
2139
2140       Due to its flexibility, the preferred encapsulation between hypervisors
2141       is Geneve. For Geneve encapsulation, OVN transmits the logical datapath
2142       identifier  in  the  Geneve  VNI. OVN transmits the logical ingress and
2143       logical egress ports in a TLV with  class  0x0102,  type  0x80,  and  a
2144       32-bit value encoded as follows, from MSB to LSB:
2145
2146         1       15          16
2147       +---+------------+-----------+
2148       |rsv|ingress port|egress port|
2149       +---+------------+-----------+
2150         0
2151
2152
2153       Environments  whose  NICs lack Geneve offload may prefer STT encapsula‐
2154       tion for performance reasons. For STT encapsulation,  OVN  encodes  all
2155       three  pieces  of  logical metadata in the STT 64-bit tunnel ID as fol‐
2156       lows, from MSB to LSB:
2157
2158           9          15          16         24
2159       +--------+------------+-----------+--------+
2160       |reserved|ingress port|egress port|datapath|
2161       +--------+------------+-----------+--------+
2162           0
2163
2164
2165       For connecting to gateways, in addition to Geneve and STT, OVN supports
2166       VXLAN,  because  only  VXLAN  support  is  common  on top-of-rack (ToR)
2167       switches. Currently, gateways have a feature set that matches the capa‐
2168       bilities  as  defined by the VTEP schema, so fewer bits of metadata are
2169       necessary. In the future, gateways that do not  support  encapsulations
2170       with  large  amounts of metadata may continue to have a reduced feature
2171       set.
2172
2173
2174
2175OVN 23.09.2                    OVN Architecture            ovn-architecture(7)
Impressum