</li>
</ol>
+ <h2>Life Cycle of a VTEP gateway</h2>
+
+ <p>
+ A gateway is a chassis that forwards traffic between the OVN-managed
+ part of a logical network and a physical VLAN, extending a
+ tunnel-based logical network into a physical network.
+ </p>
+
+ <p>
+ The steps below refer often to details of the OVN and VTEP database
+ schemas. Please see <code>ovn-sb</code>(5), <code>ovn-nb</code>(5)
+ and <code>vtep</code>(5), respectively, for the full story on these
+ databases.
+ </p>
+
+ <ol>
+ <li>
+ A VTEP gateway's life cycle begins with the administrator registering
+ the VTEP gateway as a <code>Physical_Switch</code> table entry in the
+ <code>VTEP</code> database. The <code>ovn-controller-vtep</code>
+ connected to this VTEP database, will recognize the new VTEP gateway
+ and create a new <code>Chassis</code> table entry for it in the
+ <code>OVN_Southbound</code> database.
+ </li>
+
+ <li>
+ The administrator can then create a new <code>Logical_Switch</code>
+ table entry, and bind a particular vlan on a VTEP gateway's port to
+ any VTEP logical switch. Once a VTEP logical switch is bound to
+ a VTEP gateway, the <code>ovn-controller-vtep</code> will detect
+ it and add its name to the <var>vtep_logical_switches</var>
+ column of the <code>Chassis</code> table in the <code>
+ OVN_Southbound</code> database. Note, the <var>tunnel_key</var>
+ column of VTEP logical switch is not filled at creation. The
+ <code>ovn-controller-vtep</code> will set the column when the
+ correponding vtep logical switch is bound to an OVN logical network.
+ </li>
+
+ <li>
+ Now, the administrator can use the CMS to add a VTEP logical switch
+ to the OVN logical network. To do that, the CMS must first create a
+ new <code>Logical_Port</code> table entry in the <code>
+ OVN_Northbound</code> database. Then, the <var>type</var> column
+ of this entry must be set to "vtep". Next, the <var>
+ vtep-logical-switch</var> and <var>vtep-physical-switch</var> keys
+ in the <var>options</var> column must also be specified, since
+ multiple VTEP gateways can attach to the same VTEP logical switch.
+ </li>
+
+ <li>
+ The newly created logical port in the <code>OVN_Northbound</code>
+ database and its configuration will be passed down to the <code>
+ OVN_Southbound</code> database as a new <code>Port_Binding</code>
+ table entry. The <code>ovn-controller-vtep</code> will recognize the
+ change and bind the logical port to the corresponding VTEP gateway
+ chassis. Configuration of binding the same VTEP logical switch to
+ a different OVN logical networks is not allowed and a warning will be
+ generated in the log.
+ </li>
+
+ <li>
+ Beside binding to the VTEP gateway chassis, the <code>
+ ovn-controller-vtep</code> will update the <var>tunnel_key</var>
+ column of the VTEP logical switch to the corresponding <code>
+ Datapath_Binding</code> table entry's <var>tunnel_key</var> for the
+ bound OVN logical network.
+ </li>
+
+ <li>
+ Next, the <code>ovn-controller-vtep</code> will keep reacting to the
+ configuration change in the <code>Port_Binding</code> in the
+ <code>OVN_Northbound</code> database, and updating the
+ <code>Ucast_Macs_Remote</code> table in the <code>VTEP</code> database.
+ This allows the VTEP gateway to understand where to forward the unicast
+ traffic coming from the extended external network.
+ </li>
+
+ <li>
+ Eventually, the VTEP gateway's life cycle ends when the administrator
+ unregisters the VTEP gateway from the <code>VTEP</code> database.
+ The <code>ovn-controller-vtep</code> will recognize the event and
+ remove all related configurations (<code>Chassis</code> table entry
+ and port bindings) in the <code>OVN_Southbound</code> database.
+ </li>
+
+ <li>
+ When the <code>ovn-controller-vtep</code> is terminated, all related
+ configurations in the <code>OVN_Southbound</code> database and
+ the <code>VTEP</code> database will be cleaned, including
+ <code>Chassis</code> table entries for all registered VTEP gateways
+ and their port bindings, and all <code>Ucast_Macs_Remote</code> table
+ entries and the <code>Logical_Switch</code> tunnel keys.
+ </li>
+ </ol>
+
<h1>Design Decisions</h1>
<h2>Tunnel Encapsulations</h2>
<column name="type">
<p>
Specify a type for this logical port. Logical ports can be used to model
- other types of connectivity into an OVN logical switch. Leaving this column
- blank maintains the default logical port behavior.
+ other types of connectivity into an OVN logical switch. Leaving this
+ column blank maintains the default logical port behavior, which is
+ for a VM (or VIF) interface. The following other types are defined:
</p>
- <p>
- When this column is set to <code>localnet</code>, this logical port
- represents a connection to a locally accessible network from each
- <code>ovn-controller</code> instance. A logical switch can only have a
- single <code>localnet</code> port attached and at most one regular
- logical port. This is used to model direct connectivity to an existing
- network.
- </p>
+ <dl>
+ <dt><code>localnet</code></dt>
+ <dd>A connection to a locally accessible network from each
+ <code>ovn-controller</code> instance. A logical switch can only
+ have a single <code>localnet</code> port attached and at most one
+ regular logical port. This is used to model direct connectivity
+ to an existing network.</dd>
+ </dl>
+
+ <dl>
+ <dt><code>vtep</code></dt>
+ <dd>A port to a logical switch on a VTEP gateway. In order
+ to get this port correctly recognized by the OVN controller, the
+ <ref column="options" table="Logical_Port"/>:<code>vtep-physical-switch</code>
+ and <ref column="options" table="Logical_Port"/>:<code>vtep-logical-switch</code>
+ must also be defined.</dd>
+ </dl>
</column>
<column name="options">
<p>
This column provides key/value settings specific to the logical port
- <ref column="type"/>.
+ <ref column="type"/>. The following options are defined:
</p>
- <p>
- When <ref column="type"/> is set to <code>localnet</code>, you must set
- the option <code>network_name</code>. <code>ovn-controller</code> uses
- local configuration to determine exactly how to connect to this locally
- accessible network.
- </p>
+ <dl>
+ <dt><code>network_name</code></dt>
+ <dd>
+ Must be set when <ref column="type"/> is <code>localnet</code>.
+ <code>ovn-controller</code> uses local configuration to determine
+ exactly how to connect to this locally accessible network.
+ </dd>
+ </dl>
+
+ <dl>
+ <dt><code>vtep-physical-switch</code></dt>
+ <dd>
+ The name of the VTEP gateway. Must be set when
+ <ref column="type"/> is <code>vtep</code>.
+ </dd>
+ </dl>
+
+ <dl>
+ <dt><code>vtep-logical-switch</code></dt>
+ <dd>
+ A logical switch name connected by the VTEP gateway. Must be
+ set when <ref column="type"/> is <code>vtep</code>.
+ </dd>
+ </dl>
</column>
<column name="parent_name">
<column name="action">
<p>The action to take when the ACL rule matches:</p>
-
<ul>
<li>
<code>allow</code>: Forward the packet.
The OVN Southbound database sits at the center of the OVN
architecture. It is the one component that speaks both southbound
directly to all the hypervisors and gateways, via
- <code>ovn-controller</code>, and northbound to the Cloud Management
- System, via <code>ovn-northd</code>:
+ <code>ovn-controller</code>/<code>ovn-controller-vtep</code>, and
+ northbound to the Cloud Management System, via <code>ovn-northd</code>:
</p>
<h2>Database Structure</h2>
<dt><code>external_ids</code>: map of string-string pairs</dt>
<dd>
Key-value pairs for use by the software that manages the OVN Southbound
- database rather than by <code>ovn-controller</code>. In particular,
- <code>ovn-northd</code> can use key-value pairs in this column to relate
- entities in the southbound database to higher-level entities (such as
- entities in the OVN Northbound database). Individual key-value pairs in
- this column may be documented in some cases to aid in understanding and
- troubleshooting, but the reader should not mistake such documentation as
- comprehensive.
+ database rather than by
+ <code>ovn-controller</code>/<code>ovn-controller-vtep</code>. In
+ particular, <code>ovn-northd</code> can use key-value pairs in this
+ column to relate entities in the southbound database to higher-level
+ entities (such as entities in the OVN Northbound database). Individual
+ key-value pairs in this column may be documented in some cases to aid
+ in understanding and troubleshooting, but the reader should not mistake
+ such documentation as comprehensive.
</dd>
</dl>
<p>
Each row in this table represents a hypervisor or gateway (a chassis) in
the physical network (PN). Each chassis, via
- <code>ovn-controller</code>, adds and updates its own row, and keeps a
- copy of the remaining rows to determine how to reach other hypervisors.
+ <code>ovn-controller</code>/<code>ovn-controller-vtep</code>, adds
+ and updates its own row, and keeps a copy of the remaining rows to
+ determine how to reach other hypervisors.
</p>
<p>
A <dfn>gateway</dfn> is a chassis that forwards traffic between the
OVN-managed part of a logical network and a physical VLAN, extending a
tunnel-based logical network into a physical network. Gateways are
- typically dedicated nodes that do not host VMs.
+ typically dedicated nodes that do not host VMs and will be controlled
+ by <code>ovn-controller-vtep</code>.
</p>
<column name="vtep_logical_switches">
- Stores all vtep logical switch names connected by this gateway
- chassis.
+ Stores all VTEP logical switch names connected by this gateway
+ chassis. The <ref table="Port_Binding"/> table entry with
+ <ref column="options" table="Port_Binding"/>:<code>vtep-physical-switch</code>
+ equal <ref table="Chassis"/> <ref column="name" table="Chassis"/>, and
+ <ref column="options" table="Port_Binding"/>:<code>vtep-logical-switch</code>
+ value in <ref table="Chassis"/>
+ <ref column="vtep_logical_switches" table="Chassis"/>, will be
+ associated with this <ref table="Chassis"/>.
</column>
</group>
</table>
The <ref column="encaps" table="Chassis"/> column in the <ref
table="Chassis"/> table refers to rows in this table to identify
how OVN may transmit logical dataplane packets to this chassis.
- Each chassis, via <code>ovn-controller</code>(8), adds and updates
- its own rows and keeps a copy of the remaining rows to determine
- how to reach other chassis.
+ Each chassis, via <code>ovn-controller</code>(8) or
+ <code>ovn-controller-vtep</code>(8), adds and updates its own rows
+ and keeps a copy of the remaining rows to determine how to reach
+ other chassis.
</p>
<column name="type">
</p>
<p>
- <code>ovn-controller</code> populates the <code>chassis</code> column
- for the records that identify the logical ports that are located on its
- hypervisor, which <code>ovn-controller</code> in turn finds out by
- monitoring the local hypervisor's Open_vSwitch database, which
- identifies logical ports via the conventions described in
- <code>IntegrationGuide.md</code>.
+ <code>ovn-controller</code>/<code>ovn-controller-vtep</code>
+ populates the <code>chassis</code> column for the records that
+ identify the logical ports that are located on its hypervisor/gateway,
+ which <code>ovn-controller</code>/<code>ovn-controller-vtep</code> in
+ turn finds out by monitoring the local hypervisor's Open_vSwitch
+ database, which identifies logical ports via the conventions described
+ in <code>IntegrationGuide.md</code>.
</p>
<p>
(This is not critical because resources hosted on the chassis are equally
unreachable regardless of whether their rows are present.) To handle the
case where a VM is shut down abruptly on one chassis, then brought up
- again on a different one, <code>ovn-controller</code> must overwrite the
- <code>chassis</code> column with new information.
+ again on a different one,
+ <code>ovn-controller</code>/<code>ovn-controller-vtep</code> must
+ overwrite the <code>chassis</code> column with new information.
</p>
<column name="datapath">
<column name="type">
<p>
A type for this logical port. Logical ports can be used to model
- other types of connectivity into an OVN logical switch. Leaving this column
- blank maintains the default logical port behavior.
+ other types of connectivity into an OVN logical switch. Leaving this
+ column blank maintains the default logical port behavior, which
+ is for a VM (or VIF) interface. The following other types are defined:
</p>
- <p>
- When this column is set to <code>localnet</code>, this logical port
- represents a connection to a locally accessible network from each
- ovn-controller instance. A logical switch can only have a single
- <code>localnet</code> port attached and at most one regular logical
- port. This is used to model direct connectivity to an existing
- network.
- </p>
+ <dl>
+ <dt><code>localnet</code></dt>
+ <dd>A connection to a locally accessible network from each
+ <code>ovn-controller</code> instance. A logical switch can only
+ have a single <code>localnet</code> port attached and at most one
+ regular logical port. This is used to model direct connectivity
+ to an existing network.</dd>
+ </dl>
+
+ <dl>
+ <dt><code>vtep</code></dt>
+ <dd>A port to a logical switch on a VTEP gateway chassis. In order
+ to get this port correctly recognized by the OVN controller, the
+ <ref column="options" table="Port_Binding"/>:<code>vtep-physical-switch</code>
+ and <ref column="options" table="Port_Binding"/>:<code>vtep-logical-switch</code>
+ must also be defined.</dd>
+ </dl>
</column>
<column name="options">
<p>
This column provides key/value settings specific to the logical port
- <ref column="type"/>.
+ <ref column="type"/>. The following options are defined:
</p>
- <p>
- When <ref column="type"/> is set to <code>localnet</code>, you must set
- the option <code>network_name</code>. <code>ovn-controller</code> uses
- the configuration entry <code>ovn-bridge-mappings</code> to determine
- how to connect to this network. <code>ovn-bridge-mappings</code> is a
- list of network names mapped to a local OVS bridge that provides access
- to that network. An example of configuring
- <code>ovn-bridge-mappings</code> would be:
- </p>
+ <dl>
+ <dt><code>network_name</code></dt>
+ <dd>
+ Must be set when <ref column="type"/> is <code>localnet</code>.
+ <code>ovn-controller</code> uses the configuration entry
+ <code>ovn-bridge-mappings</code> to determine how to connect to
+ this network. <code>ovn-bridge-mappings</code> is a list of
+ network names mapped to a local OVS bridge that provides access
+ to that network. An example of configuring
+ <code>ovn-bridge-mappings</code> would be:
- <p>
- <code>$ ovs-vsctl set open
- . external-ids:ovn-bridge-mappings=physnet1:br-eth0,physnet2:br-eth1</code>
- </p>
+ <p>
+ <code>$ ovs-vsctl set open
+ . external-ids:ovn-bridge-mappings=physnet1:br-eth0,physnet2:br-eth1</code>
+ </p>
- <p>
- Also note that when a logical switch has a <code>localnet</code> port
- attached, every chassis that may have a local vif attached to that
- logical switch must have a bridge mapping configured to reach that
- <code>localnet</code>. Traffic that arrives on a <code>localnet</code>
- port is never forwarded over a tunnel to another chassis.
- </p>
+ <p>
+ Also note that when a logical switch has a <code>localnet</code>
+ port attached, every chassis that may have a local vif attached
+ to that logical switch must have a bridge mapping configured to
+ reach that <code>localnet</code>. Traffic that arrives on a
+ <code>localnet</code> port is never forwarded over a tunnel to
+ another chassis.
+ </p>
+ </dd>
+ </dl>
+
+ <dl>
+ <dt><code>vtep-physical-switch</code></dt>
+ <dd>
+ The name of the VTEP gateway. Must be set when
+ <ref column="type"/> is <code>vtep</code>.
+ </dd>
+ </dl>
+
+ <dl>
+ <dt><code>vtep-logical-switch</code></dt>
+ <dd>
+ A logical switch name connected by the VTEP gateway. Must be
+ set when <ref column="type"/> is <code>vtep</code>.
+ </dd>
+ </dl>
</column>
<column name="tunnel_key">
<column name="chassis">
The physical location of the logical port. To successfully identify a
chassis, this column must be a <ref table="Chassis"/> record. This is
- populated by <code>ovn-controller</code>.
+ populated by <code>ovn-controller</code>/<code>ovn-controller-vtep</code>.
</column>
<column name="mac">