OpenStack git URLs and the retired networking-ovn reference,
fix the wrong program name (ovn-dpctl -> ovs-dpctl) and a
field name typo in the OpenStack tutorial, and add notes that
sample outputs are version-specific.
Document the transit router feature that was missing from
both the interconnection tutorial and the ovn-ic-nbctl man
page: add a new section covering tr-add, tr-list, trp-add,
and trp-del, and add the corresponding Transit Router
Commands section to ovn-ic-nbctl(8).
Assisted-by: Claude Opus 5, Claude Code
Reported-at: https://redhat.atlassian.net/browse/FDP-3049
Signed-off-by: Mairtin O'Loingsigh <[email protected]>
---
.../tutorials/ovn-interconnection.rst | 74 +++++++++++++++++--
Documentation/tutorials/ovn-ipsec.rst | 2 +-
Documentation/tutorials/ovn-openstack.rst | 35 +++++----
Documentation/tutorials/ovn-ovsdb-relay.rst | 14 ++--
Documentation/tutorials/ovn-sandbox.rst | 7 ++
utilities/ovn-ic-nbctl.8.xml | 65 ++++++++++++++++
6 files changed, 167 insertions(+), 30 deletions(-)
diff --git a/Documentation/tutorials/ovn-interconnection.rst
b/Documentation/tutorials/ovn-interconnection.rst
index dbb8439e0..8925a7a44 100644
--- a/Documentation/tutorials/ovn-interconnection.rst
+++ b/Documentation/tutorials/ovn-interconnection.rst
@@ -25,13 +25,13 @@
OVN Interconnection
===================
-This document provides a guide for interconnecting multiple OVN deployements
-with OVN managed tunneling. More details about the OVN Interconnectiong design
+This document provides a guide for interconnecting multiple OVN deployments
+with OVN managed tunneling. More details about the OVN Interconnection design
can be found in ``ovn-architecture``\(7) manpage.
-This document assumes two or more OVN deployments are setup and runs normally,
-possibly at different data-centers, and the gateway chassises of each OVN
-are with IP addresses that are reachable between each other.
+This document assumes two or more OVN deployments are setup and running
+normally, possibly at different data-centers, and the gateway chassis of each
+OVN are with IP addresses that are reachable between each other.
Setup Interconnection Databases
-------------------------------
@@ -40,7 +40,7 @@ To interconnect different OVNs, you need to create global
OVSDB databases that
store interconnection data. The databases can be setup on any nodes that are
accessible from all the central nodes of each OVN deployment. It is
recommended that the global databases are setup with HA, with nodes in
-different avaialbility zones, to avoid single point of failure.
+different availability zones, to avoid single point of failure.
1. Install OVN packages on each global database node.
@@ -93,7 +93,7 @@ DB connection method specified in options ::
Configure Gateways
------------------
-For each OVN deployment, specify some chassises as interconnection gateways.
+For each OVN deployment, specify some chassis as interconnection gateways.
The number of gateways you need depends on the scale and bandwidth you need
for
the traffic between the OVN deployments.
@@ -166,6 +166,64 @@ The ports connected to transit switches will be automatically populated to
$ ovn-ic-sbctl show
+Create Transit Logical Routers
+------------------------------
+
+Transit Logical Routers, or Transit Routers, are virtual routers that are
+shared across OVN deployments. While transit switches provide L2 connectivity
+between logical routers in different availability zones (requiring manual
+router port and switch port creation in each AZ), transit routers provide a
+centrally managed L3 interconnection point. When a transit router is created,
+``ovn-ic`` automatically mirrors it as a ``Logical_Router`` in each
+availability zone's Northbound database.
+
+Create a transit router ::
+
+ $ ovn-ic-nbctl tr-add <name>
+
+After creating a transit router, it can be seen from each OVN deployment's
+Northbound database ::
+
+ $ ovn-nbctl find logical_router options:interconn-tr=<name>
+
+You will also see it with ``ovn-nbctl lr-list``.
+
+To list all transit routers ::
+
+ $ ovn-ic-nbctl tr-list
+
+Connect Ports to Transit Routers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Add ports to a transit router using ``ovn-ic-nbctl``. Each port requires a
+MAC address and optionally one or more network addresses (CIDR notation).
+Unlike transit switches, there is no need to manually create logical router
+ports in each AZ -- ``ovn-ic`` creates the corresponding
+``Logical_Router_Port`` entries automatically.
+
+For example, to add a port to transit router ``tr1`` ::
+
+ $ ovn-ic-nbctl trp-add tr1 trp-tr1-east aa:aa:aa:aa:aa:01 \
+ 169.254.200.1/24
+
+Optionally, a port can be bound to a specific chassis ::
+
+ $ ovn-ic-nbctl trp-add tr1 trp-tr1-west aa:aa:aa:aa:aa:02 \
+ 169.254.200.2/24 chassis=gw-west
+
+When ``chassis`` is set, the port is bound to that chassis. When omitted, the
+port is distributed -- every availability zone instantiates it as a
+distributed router port of its own copy of the transit router.
+
+To delete a port ::
+
+ $ ovn-ic-nbctl trp-del trp-tr1-east
+
+The transit router ports are automatically populated to the ``IC-SB``
+database, which can be verified by ::
+
+ $ ovn-ic-sbctl show
+
Create Static Routes
--------------------
@@ -212,4 +270,4 @@ In ovn-west you will see ::
Static routes configured in the routers can be advertised and learned as well.
For more details of router advertisement and its configure options, please
-see <code>ovn-nb</code>(5).
+see ``ovn-nb``\(5).
diff --git a/Documentation/tutorials/ovn-ipsec.rst
b/Documentation/tutorials/ovn-ipsec.rst
index 249d3230a..4da45ec54 100644
--- a/Documentation/tutorials/ovn-ipsec.rst
+++ b/Documentation/tutorials/ovn-ipsec.rst
@@ -113,7 +113,7 @@ For strongswan backends::
.. note::
- Support for this feature is only availably when OVN is used together with
+ Support for this feature is only available when OVN is used together with
OVS releases that accept IPsec custom tunnel options.
Troubleshooting
diff --git a/Documentation/tutorials/ovn-openstack.rst
b/Documentation/tutorials/ovn-openstack.rst
index 93341d58c..133a20c38 100644
--- a/Documentation/tutorials/ovn-openstack.rst
+++ b/Documentation/tutorials/ovn-openstack.rst
@@ -26,12 +26,18 @@ OVN OpenStack Tutorial
======================
This tutorial demonstrates how OVN works in an OpenStack "DevStack"
-environment. It was tested with the "master" branches of DevStack and
-Open vSwitch near the beginning of May 2017. Anyone using an earlier
-version is likely to encounter some differences. In particular, we
-noticed some shortcomings in OVN utilities while writing the tutorial
-and pushed out some improvements, so it's best to use recent Open
-vSwitch at least from that point of view.
+environment. It was originally written and tested with the "master"
+branches of DevStack and Open vSwitch near the beginning of May 2017.
+Anyone using a different version is likely to encounter some
+differences.
+
+.. note::
+
+ The logical flow table numbers, stage names, and sample outputs shown
+ in this tutorial reflect the OVN version at the time of writing and
+ will differ from current OVN. The concepts and tools demonstrated
+ remain valid; follow along with your own output rather than expecting
+ an exact match.
The goal of this tutorial is to demonstrate OVN in an end-to-end way,
that is, to show how it works from the cloud management system at the
@@ -366,13 +372,14 @@ and the software components that connect them are:
We will use OpenStack's ``openstack`` utility to observe and modify
Neutron and other OpenStack configuration.
-* networking-ovn, the Neutron driver that interfaces with OVN and
- translates the internal Neutron representation of the virtual
- network into OVN's representation and pushes that representation
- down the OVN northbound database.
+* The ML2/OVN driver (formerly known as networking-ovn), the Neutron
+ mechanism driver that interfaces with OVN and translates the internal
+ Neutron representation of the virtual network into OVN's
+ representation and pushes that representation down the OVN northbound
+ database.
In this tutorial it's rarely worth distinguishing Neutron from
- networking-ovn, so we usually don't break out this layer separately.
+ ML2/OVN, so we usually don't break out this layer separately.
* The OVN Northbound database, aka NB DB. This is an instance of
OVSDB, a simple general-purpose database that is used for multiple
@@ -380,7 +387,7 @@ and the software components that connect them are:
networking concepts such as switches and routers. The NB DB serves
the purpose that in other systems might be filled by some kind of
API; for example, in place of calling an API to create or delete a
- logical switch, networking-ovn performs these operations by
+ logical switch, ML2/OVN performs these operations by
inserting or deleting a row in the NB DB's Logical_Switch table.
We will use OVN's ``ovn-nbctl`` utility to observe the NB DB. (We
@@ -527,7 +534,7 @@ or router::
tunnel_key : 2
This output lists the NB DB UUIDs in external_ids:logical-switch and
-Neutron UUIDs in externals_ids:uuid. We can dive in deeper by viewing
+Neutron UUIDs in external_ids:name. We can dive in deeper by viewing
the OVN logical flows that implement a logical switch. Our new
logical switch is a simple and almost pathological example given that
it doesn't yet have any ports attached to it. We'll look at the
@@ -990,7 +997,7 @@ Now go back to your DevStack session and run::
$ sudo watch ovs-dpctl dump-flows
-We're working with a new program. ovn-dpctl is an interface to Open
+We're working with a new program. ovs-dpctl is an interface to Open
vSwitch datapaths, in this case to the Linux kernel datapath. Its
``dump-flows`` command displays the contents of the in-kernel flow
cache, and by running it under the ``watch`` program we see a new
diff --git a/Documentation/tutorials/ovn-ovsdb-relay.rst
b/Documentation/tutorials/ovn-ovsdb-relay.rst
index e0f7d1957..5877261a2 100644
--- a/Documentation/tutorials/ovn-ovsdb-relay.rst
+++ b/Documentation/tutorials/ovn-ovsdb-relay.rst
@@ -54,7 +54,7 @@ repeated multiple times horizontally (multiple groups
connected to one group)
and/or vertically (multiple groups connected one-by-one in a chain).
OVN Southbound OVSDB cluster must be configured with at least one remote, which
-allows OVSDB Relay servers to connnect to it. This remote must not have
+allows OVSDB Relay servers to connect to it. This remote must not have
configured RBAC rules. RBAC rules can be configured to be checked on the
OVSDB
Relay servers, which are used to connect to ovn-controller and
ovn-controller-vtep.
@@ -110,7 +110,7 @@ To use **TCP** between ovn-controller and OVSDB Relay:
-- --remote=ptcp:6642
# start ovn-controller and connect to OVSDB Relay
- ovs-vsctl set external_ids:ovn-remote="tcp:127.0.0.1:6642"
+ ovs-vsctl set open_vswitch . external_ids:ovn-remote="tcp:127.0.0.1:6642"
/usr/share/ovn/scripts/ovn-ctl start_controller
To use **SSL/TLS** between ovn-controller and OVSDB Relay:
@@ -126,7 +126,7 @@ To use **SSL/TLS** between ovn-controller and OVSDB Relay:
-- --remote=pssl:6642
# start ovn-controller and connect to OVSDB Relay
- ovs-vsctl set external_ids:ovn-remote="ssl:127.0.0.1:6642"
+ ovs-vsctl set open_vswitch . external_ids:ovn-remote="ssl:127.0.0.1:6642"
ovs-vsctl set-ssl <...>
/usr/share/ovn/scripts/ovn-ctl start_controller
@@ -145,7 +145,7 @@ To use **SSL/TLS with RBAC** between ovn-controller and OVSDB Relay:
--ovn-sb-relay-db-ssl-ca-cert=/path/to/ovsdb/relay/ssl-ca-cert.pem
# start ovn-controller and connect to OVSDB Relay
- ovs-vsctl set external_ids:ovn-remote="ssl:127.0.0.1:6642"
+ ovs-vsctl set open_vswitch . external_ids:ovn-remote="ssl:127.0.0.1:6642"
/usr/share/ovn/scripts/ovn-ctl start_controller
This is the most simple deployment, which can be used even in small-scale
@@ -193,8 +193,8 @@ Group 2:
ovs-vsctl set open . external_ids:ovn-remote=ssl:10.0.0.20:6642,ssl:10.0.0.21:6642
-And so on. It is adviced to configure at least two OVSDB Relay servers for
-ovn-controller if high-avalability is important.
+And so on. It is advised to configure at least two OVSDB Relay servers for
+ovn-controller if high-availability is important.
.. _two_tier_multi_group:
@@ -253,7 +253,7 @@ To use **SSL/TLS with RBAC** between ovn-controller and OVSDB Relay:
--ovn-sb-relay-db-ssl-ca-cert=/path/to/ovsdb/relay/ssl-ca-cert.pem
# start ovn-controller and connect to appropriate OVSDB Relay servers
- ovs-vsctl set external_ids:ovn-remote="ssl:127.0.0.1:6642"
+ ovs-vsctl set open_vswitch . external_ids:ovn-remote="ssl:127.0.0.1:6642"
/usr/share/ovn/scripts/ovn-ctl start_controller
.. warning::
diff --git a/Documentation/tutorials/ovn-sandbox.rst
b/Documentation/tutorials/ovn-sandbox.rst
index ff519c986..9829e1ea9 100644
--- a/Documentation/tutorials/ovn-sandbox.rst
+++ b/Documentation/tutorials/ovn-sandbox.rst
@@ -73,6 +73,13 @@ Additional flags exist for launching the debugger for the
OVN programs::
Creating OVN Resources
----------------------
+.. note::
+
+ The sample command outputs shown below (UUIDs, table numbers, stage
+ names) are illustrative and will differ from what you see. In
+ particular, logical flow table numbers and stage names change between
+ OVN releases as the pipeline evolves.
+
Once you have ``ovn-sandbox`` running, you can start using OVN utilities to
create resources. As an example, we will create an environment that has two
logical switches connected by a logical router.
diff --git a/utilities/ovn-ic-nbctl.8.xml b/utilities/ovn-ic-nbctl.8.xml
index 308debd8e..8f6544cec 100644
--- a/utilities/ovn-ic-nbctl.8.xml
+++ b/utilities/ovn-ic-nbctl.8.xml
@@ -108,6 +108,71 @@
</dd>
</dl>
+ <h1>Transit Router Commands</h1>
+
+ <dl>
+ <dt>[<code>--may-exist</code>] <code>tr-add</code> <var>router</var></dt>
+ <dd>
+ <p>
+ Creates a new transit router named <var>router</var>.
+ </p>
+
+ <p>
+ Transit router names must be unique. Adding a duplicated name results
+ in error. With <code>--may-exist</code>, adding a duplicate name
+ succeeds but does not create a new transit router.
+ </p>
+ </dd>
+
+ <dt>[<code>--if-exists</code>] <code>tr-del</code> <var>router</var></dt>
+ <dd>
+ Deletes <var>router</var>. It is an error if <var>router</var> does
+ not exist, unless <code>--if-exists</code> is specified.
+ </dd>
+
+ <dt><code>tr-list</code></dt>
+ <dd>
+ Lists all existing transit routers on standard output, one per line.
+ </dd>
+
+ <dt>[<code>--may-exist</code>] <code>trp-add</code> <var>router</var>
+ <var>port</var> <var>mac</var> [<var>network</var>]...
+
[<var>column</var>[<code>:</code><var>key</var>]<code>=</code><var>value</var>]...</dt>
+ <dd>
+ <p>
+ Creates a new transit router port named <var>port</var> with Ethernet
+ address <var>mac</var> on <var>router</var>.
+ </p>
+
+ <p>
+ <var>network</var> arguments specify the IP addresses and netmasks of
+ the router port in CIDR notation (e.g. <code>192.168.0.1/24</code>).
+ Multiple addresses may be given.
+ </p>
+
+ <p>
+ Additional column settings may be specified as
+ <var>column</var><code>=</code><var>value</var> pairs. For example,
+ <code>chassis=</code><var>name</var> binds the port to a specific
+ chassis. If <code>chassis</code> is not set, the port is distributed
+ across all availability zones.
+ </p>
+
+ <p>
+ Transit router port names must be unique. Adding a duplicated name
+ results in an error. With <code>--may-exist</code>, adding a
+ duplicate name succeeds provided the existing port has the same
+ <var>mac</var> and <var>network</var> arguments.
+ </p>
+ </dd>
+
+ <dt>[<code>--if-exists</code>] <code>trp-del</code> <var>port</var></dt>
+ <dd>
+ Deletes <var>port</var>. It is an error if <var>port</var> does
+ not exist, unless <code>--if-exists</code> is specified.
+ </dd>
+ </dl>
+
<h1>Database Commands</h1>
<p>These commands query and modify the contents of <code>ovsdb</code>
tables.
They are a slight abstraction of the <code>ovsdb</code> interface and
