ovn-nbctl: Display and accept Neutron network, router, port names.

The names of these neutron:* keys in external_ids are unfortunate, but
they are the keys that the OVN utilities need to support if we want users
to be able to work with OpenStack in a convenient fashion rather than
having to cut and paste UUIDs everywhere.

This commit documents the meaning of these keys, in the hopes that other
CMS integrations will simply use them instead of inventing new ones.
Perhaps at some point we can clean this up, since bad names are a bad idea,
but it also would take a lot of coordination and probably multiple
releases.

Port names are slightly less useful in practice than switch or router names
because Neutron doesn't by default give names to ports.  (You can add them
with "openstack port set --name", though.)

Signed-off-by: Ben Pfaff <blp@ovn.org>
Acked-by: Andy Zhou <azhou@ovn.org>

2 files changed, 87 insertions, 31 deletions

diff --git a/ovn/ovn-nb.xml b/ovn/ovn-nb.xml
index e145e7b11..f127d0df8 100644
--- a/ovn/ovn-nb.xml
+++ b/ovn/ovn-nb.xml
@@ -101,15 +101,6 @@
       address <code>unknown</code>.
     </p>
 
-    <column name="name">
-      <p>
-        A name for the logical switch.  This name has no special meaning or purpose
-        other than to provide convenience for human interaction with the ovn-nb
-        database.  There is no requirement for the name to be unique.  The
-        logical switch's UUID should be used as the unique identifier.
-      </p>
-    </column>
-
     <column name="ports">
       <p>
         The logical ports connected to the logical switch.
@@ -140,6 +131,33 @@
       Please see the <ref table="DNS"/> table.
     </column>
 
+    <group title="Naming">
+      <p>
+        These columns provide names for the logical switch.  From OVN's
+        perspective, these names have no special meaning or purpose other than
+        to provide convenience for human interaction with the  database.
+        There is no requirement for the name to be unique.  (For a unique
+        identifier for a logical switch, use its row UUID.)
+      </p>
+
+      <p>
+        (Originally, <ref column="name"/> was intended to serve the purpose of
+        a human-friendly name, but the Neutron integration used it to uniquely
+        identify its own switch object, in the format
+        <code>neutron-<var>uuid</var></code>.  Later on, Neutron started
+        propagating the friendly name of a switch as <ref column="external_ids"
+        key="neutron:network_name"/>.  Perhaps this can be cleaned up someday.)
+      </p>
+
+      <column name="name">
+        A name for the logical switch.
+      </column>
+
+      <column name="external_ids" key="neutron:network_name">
+        Another name for the logical switch.
+      </column>
+    </group>
+
     <group title="IP Address Assignment">
       <p>
         These options control automatic IP address management (IPAM) for ports
@@ -1014,15 +1032,6 @@
       Each row represents one L3 logical router.
     </p>
 
-    <column name="name">
-      <p>
-        A name for the logical router.  This name has no special meaning or purpose
-        other than to provide convenience for human interaction with the ovn-nb
-        database.  There is no requirement for the name to be unique.  The
-        logical router's UUID should be used as the unique identifier.
-      </p>
-    </column>
-
     <column name="ports">
       The router's ports.
     </column>
@@ -1049,6 +1058,33 @@
       addresses.  Load balancer rules only work on the Gateway routers.
     </column>
 
+    <group title="Naming">
+      <p>
+        These columns provide names for the logical router.  From OVN's
+        perspective, these names have no special meaning or purpose other than
+        to provide convenience for human interaction with the northbound
+        database.  There is no requirement for the name to be unique.  (For a
+        unique identifier for a logical router, use its row UUID.)
+      </p>
+
+      <p>
+        (Originally, <ref column="name"/> was intended to serve the purpose of
+        a human-friendly name, but the Neutron integration used it to uniquely
+        identify its own router object, in the format
+        <code>neutron-<var>uuid</var></code>.  Later on, Neutron started
+        propagating the friendly name of a router as <ref column="external_ids"
+        key="neutron:router_name"/>.  Perhaps this can be cleaned up someday.)
+      </p>
+
+      <column name="name">
+        A name for the logical router.
+      </column>
+
+      <column name="external_ids" key="neutron:router_name">
+        Another name for the logical router.
+      </column>
+    </group>
+
     <group title="Options">
       <p>
         Additional options for the logical router.
@@ -1174,8 +1210,8 @@
 
       <p>
         In addition to provide convenience for human interaction with the
-        ovn-nb database, this column is used as reference by its patch port in
-        <ref table="Logical_Switch_Port"/> or another logical router port in
+        northbound database, this column is used as reference by its patch port
+        in <ref table="Logical_Switch_Port"/> or another logical router port in
         <ref table="Logical_Router_Port"/>.
       </p>
     </column>
diff --git a/ovn/utilities/ovn-nbctl.c b/ovn/utilities/ovn-nbctl.c
index cfa1c525f..8ec5389f6 100644
--- a/ovn/utilities/ovn-nbctl.c
+++ b/ovn/utilities/ovn-nbctl.c
@@ -564,13 +564,24 @@ lb_by_name_or_uuid(struct ctl_context *ctx, const char *id, bool must_exist)
     return lb;
 }
 
+static void
+print_alias(const struct smap *external_ids, const char *key, struct ds *s)
+{
+    const char *alias = smap_get(external_ids, key);
+    if (alias && alias[0]) {
+        ds_put_format(s, " (aka %s)", alias);
+    }
+}
+
 /* Given pointer to logical router, this routine prints the router
  * information.  */
 static void
 print_lr(const struct nbrec_logical_router *lr, struct ds *s)
 {
-    ds_put_format(s, "router "UUID_FMT" (%s)\n",
+    ds_put_format(s, "router "UUID_FMT" (%s)",
                   UUID_ARGS(&lr->header_.uuid), lr->name);
+    print_alias(&lr->external_ids, "neutron:router_name", s);
+    ds_put_char(s, '\n');
 
     for (size_t i = 0; i < lr->n_ports; i++) {
         const struct nbrec_logical_router_port *lrp = lr->ports[i];
@@ -606,13 +617,18 @@ print_lr(const struct nbrec_logical_router *lr, struct ds *s)
 static void
 print_ls(const struct nbrec_logical_switch *ls, struct ds *s)
 {
-    ds_put_format(s, "switch "UUID_FMT" (%s)\n",
+    ds_put_format(s, "switch "UUID_FMT" (%s)",
                   UUID_ARGS(&ls->header_.uuid), ls->name);
+    print_alias(&ls->external_ids, "neutron:network_name", s);
+    ds_put_char(s, '\n');
 
     for (size_t i = 0; i < ls->n_ports; i++) {
         const struct nbrec_logical_switch_port *lsp = ls->ports[i];
 
-        ds_put_format(s, "    port %s\n", lsp->name);
+        ds_put_format(s, "    port %s", lsp->name);
+        print_alias(&lsp->external_ids, "neutron:port_name", s);
+        ds_put_char(s, '\n');
+
         if (lsp->type[0]) {
             ds_put_format(s, "        type: %s\n", lsp->type);
         }
@@ -3057,14 +3073,18 @@ cmd_set_ssl(struct ctl_context *ctx)
 }
 
 static const struct ctl_table_class tables[NBREC_N_TABLES] = {
-    [NBREC_TABLE_LOGICAL_SWITCH].row_ids[0]
-    = {&nbrec_logical_switch_col_name, NULL, NULL},
-
-    [NBREC_TABLE_LOGICAL_SWITCH_PORT].row_ids[0]
-    = {&nbrec_logical_switch_port_col_name, NULL, NULL},
-
-    [NBREC_TABLE_LOGICAL_ROUTER].row_ids[0]
-    = {&nbrec_logical_router_col_name, NULL, NULL},
+    [NBREC_TABLE_LOGICAL_SWITCH].row_ids
+    = {{&nbrec_logical_switch_col_name, NULL, NULL},
+       {&nbrec_logical_switch_col_external_ids, "neutron:network_name", NULL}},
+
+    [NBREC_TABLE_LOGICAL_SWITCH_PORT].row_ids
+    = {{&nbrec_logical_switch_port_col_name, NULL, NULL},
+       {&nbrec_logical_switch_port_col_external_ids,
+        "neutron:port_name", NULL}},
+
+    [NBREC_TABLE_LOGICAL_ROUTER].row_ids
+    = {{&nbrec_logical_router_col_name, NULL, NULL},
+       {&nbrec_logical_router_col_external_ids, "neutron:router_name", NULL}},
 
     [NBREC_TABLE_LOGICAL_ROUTER_PORT].row_ids[0]
     = {&nbrec_logical_router_port_col_name, NULL, NULL},