This commit conducts the following documentation changes:
* add a description in ovn-architecture manual for
the life cycle about VTEP gateway.
* add TODOs related to ovn-controller-vtep.
* refine the ovn-sb, ovn-nb schema manual to require
logical 'port' type and 'options' configuration.
Signed-off-by: Alex Wang <ee07b...@gmail.com>
Acked-by: Russell Bryant <rbry...@redhat.com>
---
V9->V10
- fix gramma errors pointed out by Justin.
- fix underscore notation of option keys (vtep-logical-switch,
vtep-physical-switch).
- rebase to master and convert 'localnet' related document to
bulletin point.
- refine documentation as suggested by Justin.
V8->V9:
- rebase.
V7->V8:
- rebase.
V6->V7:
- adopt suggestions from Russell.
- leave out the documentation of feature that has not been implemented yet.
V5->V6:
- add description in ovn-architecture.
V5: new patch.
---
ovn/TODO | 21 ++++++
ovn/ovn-architecture.7.xml | 95 +++++++++++++++++++++++++++
ovn/ovn-nb.xml | 64 ++++++++++++------
ovn/ovn-sb.xml | 157 +++++++++++++++++++++++++++++----------------
4 files changed, 262 insertions(+), 75 deletions(-)
diff --git a/ovn/TODO b/ovn/TODO
index 356b3ba..6f625ce 100644
--- a/ovn/TODO
+++ b/ovn/TODO
@@ -80,3 +80,24 @@
So far, both ovn-controller and ovn-controller-vtep only allow
chassis to have one tunnel encapsulation entry. We should extend
the implementation to support multiple tunnel encapsulations.
+
+** Update learned MAC addresses from VTEP to OVN
+
+ The VTEP gateway stores all MAC addresses learned from its
+ physical interfaces in the 'Ucast_Macs_Local' and the
+ 'Mcast_Macs_Local' tables. ovn-controller-vtep should be
+ able to update that information back to ovn-sb database,
+ so that other chassis know where to send packets destined
+ to the extended external network instead of broadcasting.
+
+** Translate ovn-sb Multicast_Group table into VTEP config
+
+ The ovn-controller-vtep daemon should be able to translate
+ the Multicast_Group table entry in ovn-sb database into
+ Mcast_Macs_Remote table configuration in VTEP database.
+
+* Use BFD as tunnel monitor.
+
+ Both ovn-controller and ovn-contorller-vtep should use BFD to
+ monitor the tunnel liveness. Both ovs-vswitchd schema and
+ VTEP schema supports BFD.
\ No newline at end of file
diff --git a/ovn/ovn-architecture.7.xml b/ovn/ovn-architecture.7.xml
index b4e6d10..deb9969 100644
--- a/ovn/ovn-architecture.7.xml
+++ b/ovn/ovn-architecture.7.xml
@@ -817,6 +817,101 @@
</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 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>
diff --git a/ovn/ovn-nb.xml b/ovn/ovn-nb.xml
index ba1cec1..a864785 100644
--- a/ovn/ovn-nb.xml
+++ b/ovn/ovn-nb.xml
@@ -111,32 +111,60 @@
<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"/>:vtep-physical-switch
+ and <ref column="options" table="Logical_Port"/>:vtep-logical-switch
+ 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">
@@ -279,7 +307,7 @@
<column name="action">
<p>The action to take when the ACL rule matches:</p>
-
+
<ul>
<li>
<code>allow</code>: Forward the packet.
diff --git a/ovn/ovn-sb.xml b/ovn/ovn-sb.xml
index 74631f9..76f4b1a 100644
--- a/ovn/ovn-sb.xml
+++ b/ovn/ovn-sb.xml
@@ -10,8 +10,8 @@
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>
@@ -115,13 +115,14 @@
<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>
@@ -129,8 +130,9 @@
<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>
@@ -167,12 +169,19 @@
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"/>:vtep-physical-switch
+ equal <ref table="Chassis"/> <ref column="name" table="Chassis"/>,
+ and <ref column="options" table="Port_Binding"/>:vtep-logical-switch
+ value in <ref table="Chassis"/>
+ <ref column="vtep_logical_switches" table="Chassis"/>, will be
+ associated with this <ref table="Chassis"/>.
</column>
</group>
</table>
@@ -182,9 +191,10 @@
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">
@@ -927,12 +937,13 @@
</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>
@@ -941,8 +952,9 @@
(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">
@@ -959,48 +971,79 @@
<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"/>:vtep-physical-switch
+ and <ref column="options" table="Port_Binding"/>:vtep-logical-switch
+ 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">
@@ -1034,7 +1077,7 @@
<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">
--
1.9.1
_______________________________________________
dev mailing list
dev@openvswitch.org
http://openvswitch.org/mailman/listinfo/dev
