Implement node rank in graph definition files (ipspace#2711)

The 'graph.rank' node attribute allows you to group nodes into layers
in GraphViz graphs, and to ensure the node positioning is more closely
aligned with the network topology in D2 graphs (D2 does not have a
shape rank concept)

Author: ipspace

docs/outputs/d2.md

@@ -26,12 +26,21 @@ You can use the **d2** link and node attributes to change the style of individua
 * **d2.fill** -- fill color (*fill* in D2 lingo)
 * **d2.width** -- line width (*stroke-width* in D2 lingo)
 
-You can also use the **d2.linkorder** link attribute to change the order of links in the D2 graph description file, which can sometimes improve the diagrams' appearance. Links with lower **d2.linkorder** values (default: 100) appear earlier in the list of links.
-
 ```{tip}
 The generic link- and node attributes can also be specified as **graph._attribute_** (for example, **graph.color**) values to use the same settings for GraphViz and D2 graphs.
 ```
 
+(outputs-d2-layout)=
+## Influencing the Graph Layout
+
+_netlab_ uses the node **graph.rank** attribute to sort nodes in link definitions to ensure the graph edges are always defined as going from nodes with a lower rank to nodes with a higher rank. The order of nodes in the graph edges influences the D2 layout engine.
+
+The default value of the **graph.rank** attribute is 100, allowing you to push some nodes (with rank below 100) toward the top of the graph and others (with rank above 100) toward the bottom.
+
+You can also use the **graph.rank** on links to influence how GraphViz draws multi-access links.
+
+Finally, the link/interface **graph.linkorder** attribute allows you to specify the node order in individual links. The default **graph.linkorder** value is 50 for interfaces and 100 for subnets (multi-access links), resulting in subnets being "below" nodes unless you change the link- or interface **graph.linkorder** value.
+
 (outputs-d2-graph-appearance)=
 ## Modifying Graph Appearance
 
@@ -116,8 +125,6 @@ vrf:
 _netlab_ releases 25.07 and older specified D2 style attributes in the **‌defaults.outputs.d2** dictionary. The style attributes recognized by those releases are automatically migrated into the **‌defaults.outputs.d2.styles** dictionary.
 ```
 
-## Specifying D2 Attributes
-
 You could specify D2 attributes in your [topology file](defaults-topology) (where you would have to prefix them with **defaults**), in [per-user topology defaults](defaults-user-file), or with [environment variables](defaults-env) (even [more details](../defaults.md)). You could also specify them with the `-s` parameter of the **[netlab create](netlab-create)** command, yet again prefixed with **defaults** ([more details](netlab-create-set)).
 
 Use the **netlab show defaults outputs.d2** [command](netlab-show-defaults) to show the current D2 defaults, including topology file defaults and user defaults.

docs/outputs/graph.md

@@ -9,7 +9,7 @@ The *graph* output module is invoked with the **[netlab graph](netlab-graph)** c
 
 A single formatting modifier can be used to specify the graph type:
 
-* **topology** (default) -- Display inter-node links, multi-access- and stub subnets. When the network topology contains BGP information, the graph groups nodes into autonomous systems. Alternatively, you could set **defaults.outputs.graph.groups** attribute to use topology **[groups](topo-groups)** to group graph nodes.
+* **topology** (default) -- Display inter-node links, multi-access-, and stub subnets. When the network topology contains BGP information, the graph groups nodes into autonomous systems. Alternatively, you could set **defaults.outputs.graph.groups** attribute to use topology **[groups](topo-groups)** to group graph nodes.
 * **bgp** -- Include autonomous systems, nodes, and BGP sessions. The formatting modifier can include [BGP formatting parameters](outputs-graph-bgp-parameters). For example, `netlab create -o graph:bgp:rr` draws RR-client sessions as directed arrows.
 * **isis** -- Create a diagram of IS-IS routing, including areas, color-coded circuit types, and edge subnets (does not work with IS-IS running over VLANs)
 
@@ -24,10 +24,22 @@ You can use the **graph** link and node attributes to change the style of indivi
 * **graph.fill** -- fill color (*fillcolor* GraphViz attribute)
 * **graph.width** -- line width (*penwidth* GraphViz attribute)
 
-You can also use the **graph.linkorder** link attribute to change the order of links in the D2 graph description file, which can sometimes improve the diagrams' appearance. Links with lower **graph.linkorder** values (default: 100) appear earlier in the list of links.
-
 [^XS]: You can extend the GraphViz styling capabilities and add new **graph** attributes. See [](outputs-d2-styles) for details.
 
+(outputs-graph-layout)=
+## Influencing the Graph Layout
+
+_netlab_ uses the node **graph.rank** attribute to:
+
+1. Tell GraphViz that nodes with the same **graph.rank** should be at the same rank (vertical position) in the graph
+2. Sort nodes in link definitions to ensure the graph edges are always defined as going from nodes with a lower rank to nodes with a higher rank. The order of nodes in the graph edges influences the GraphViz layout engine.
+
+The default value of the **graph.rank** attribute is 100, allowing you to push some nodes (with rank below 100) toward the top of the graph and others (with rank above 100) toward the bottom.
+
+You can also use the **graph.rank** on links to influence how GraphViz draws multi-access links.
+
+Finally, the link/interface **graph.linkorder** attribute allows you to specify the node order in individual links. The default **graph.linkorder** value is 50 for interfaces and 100 for subnets (multi-access links), resulting in subnets being "below" nodes unless you change the link- or interface **graph.linkorder** value.
+
 (outputs-graph-appearance)=
 ## Modifying Graph Appearance
 

netsim/outputs/_graph.py

@@ -153,9 +153,16 @@ def append_edge(graph: Box, if_a: Box, if_b: Box, g_type: str) -> None:
 """
 Append a LAN segment to the graph
 """
-def append_segment(graph: Box,link: Box, g_type: str) -> None:
+LINK_DEFAULTS: dict = { 'graph.rank': 100, 'graph.linkorder': 100 }
+
+def append_segment(graph: Box,link: Box, g_type: str, topology: Box) -> None:
   link.node = link.get('bridge',f'{link.type}_{link.linkindex}')
   link.name = link.node
+  link.device = 'link'
+  for dk,dv in LINK_DEFAULTS.items():
+    if dk not in link:
+      link[dk] = dv
+
   graph.nodes[link.node] = link
   for af in ['ipv4','ipv6']:
     if af in link.prefix:
@@ -164,8 +171,8 @@ def append_segment(graph: Box,link: Box, g_type: str) -> None:
 
   for intf in link.interfaces:
     e_data = [ intf, link ]
-    if get_attr(intf,g_type,'linkorder',100) > get_attr(link,g_type,'linkorder',101):
-      e_data = [ link, intf ]
+    e_data.sort(key = lambda x: x.get('graph.rank',topology.nodes[intf.node].get('graph.rank',100)))
+    e_data.sort(key = lambda x: get_attr(x,g_type,'linkorder',50))
     append_edge(graph,e_data[0],e_data[1],g_type)
 
 def topo_edges(graph: Box, topology: Box, settings: Box,g_type: str) -> None:
@@ -174,9 +181,11 @@ def topo_edges(graph: Box, topology: Box, settings: Box,g_type: str) -> None:
     propagate_link_attributes(link,g_type,['linkorder','type'])
 
     if len(link.interfaces) == 2 and link.get('graph.type','') != 'lan':
-      append_edge(graph,link.interfaces[0],link.interfaces[1],g_type)
+      intf_list = sorted(link.interfaces,key=lambda intf: topology.nodes[intf.node].get('graph.rank',100))
+      intf_list.sort(key = lambda x: get_attr(x,g_type,'linkorder',50))
+      append_edge(graph,intf_list[0],intf_list[1],g_type)
     else:
-      append_segment(graph,link,g_type)
+      append_segment(graph,link,g_type,topology)
 
 def topology_graph(topology: Box, settings: Box,g_type: str) -> Box:
   set_shared_attributes(topology)
@@ -191,6 +200,7 @@ def bgp_sessions(graph: Box, topology: Box, settings: Box, g_type: str) -> None:
   no_vrf = settings.get('bgp.novrf',None)
   add_vrf = settings.get('bgp.vrf',None)
   bgp_af = settings.get('bgp.af')
+  node_order = list(topology.nodes.keys())
   for n_name,n_data in topology.nodes.items():
     if 'bgp' not in n_data:
       continue
@@ -217,6 +227,9 @@ def bgp_sessions(graph: Box, topology: Box, settings: Box, g_type: str) -> None:
         elif neighbor.get('rr',False) and not n_data.get('rr',False):
           dir = '->'
           e_1, e_2 = e_2, e_1
+        else:
+          (e_1, e_2) = sorted([e_1, e_2],key=lambda x: node_order.index(x.node))
+          (e_1, e_2) = sorted([e_1, e_2],key=lambda x: topology.nodes[x.node].get('graph.rank',100))
 
       if rr_sessions:
         e_1[g_type].dir = dir
@@ -289,7 +302,7 @@ def isis_edges(topology: Box, graph: Box, g_type: str) -> None:
       append_edge(graph,link.interfaces[0],link.interfaces[1],g_type)
       continue
 
-    append_segment(graph,link,g_type)
+    append_segment(graph,link,g_type,topology)
     isis_areas = set([ topology.nodes[node].get('isis.area') for node in isis_nodes ])
     if len(isis_areas) == 1:
       area_id = isis_areas.pop().replace('.','_')

netsim/outputs/graph.py

@@ -70,7 +70,7 @@ def gv_line_attr(
   if newline:
     f.write("\n")
 
-def gv_start(f : typing.TextIO, settings: Box, topology: Box) -> None:
+def gv_start(f : typing.TextIO, graph: Box, topology: Box, settings: Box) -> None:
   title = topology.get('graph.title') or topology.get('defaults.graph.title')
   f.write('graph {\n')
   gv_multiline_attr(f,attr=settings.styles.graph,indent=2)
@@ -82,6 +82,16 @@ def gv_start(f : typing.TextIO, settings: Box, topology: Box) -> None:
   gv_line_attr(f,attr=settings.styles.node,newline=True)
   f.write('  edge')
   gv_line_attr(f,attr=settings.styles.edge,newline=True)
+  rank = { node.graph.rank 
+              for node in graph.nodes.values()
+                if 'graph.rank' in node and node.device != 'link' }
+  if rank:
+    f.write ('  newrank=true;\n')
+    for r_val in sorted(list(rank)):
+      r_nodes = [ node.name +"; "
+                    for node in graph.nodes.values()
+                      if node.get('graph.rank',None) == r_val and node.device != 'link' ]
+      f.write(f'  {{ rank=same; {"".join(r_nodes)}}}\n')
 
 def gv_end(f : typing.TextIO, fname: str) -> None:
   f.write('}\n')
@@ -135,7 +145,7 @@ def gv_clusters(f : typing.TextIO, graph: Box, topology: Box, settings: Box) ->
     f.write('  }\n')
 
 def gv_nodes(f: typing.TextIO, graph: Box, topology: Box, settings: Box) -> None:
-  for n_name,n_data in graph.nodes.items():
+  for _,n_data in graph.nodes.items():
     if 'graph.cluster' not in n_data:
       if 'prefix' in n_data:
         gv_network(f,n_data,settings,indent=2)
@@ -190,7 +200,7 @@ def gv_migrate_styles(settings: Box) -> None:
 def draw_graph(topology: Box, settings: Box, graph: Box, fname: str) -> None:
   f = _files.open_output_file(fname)
   gv_migrate_styles(settings)
-  gv_start(f,settings,topology)
+  gv_start(f,graph,topology,settings)
 
   gv_clusters(f,graph,topology,settings)
   gv_nodes(f,graph,topology,settings)

netsim/outputs/graph.yml

@@ -73,11 +73,13 @@ attributes:
     color: str
     fill: str
     width: { type: int, min_value: 1, max_value: 32 }
+    rank: { type: int, min_value: 1, max_value: 200 }
   link:
     type: dict
     _keys:
       linkorder: { type: int, min_value: 1, max_value: 200 }
       type: { type: str, valid_values: ['lan'] }
       color: str
       width: { type: int, min_value: 1, max_value: 32 }
+      rank: { type: int, min_value: 1, max_value: 200 }
   shared: [ linkorder, color, fill, width ]

tests/platform-integration/graph/bgp.yml

@@ -5,6 +5,9 @@ module: [ ospf, bgp, vrf, vlan, vxlan, evpn ]
 plugin: [ files ]
 defaults.vrf.warnings.inactive: False
 
+groups:
+  core:
+    members: [ r2, r5 ]
 bgp.as_list:
   65000:
     members: [ r1, r2, r3 ]
@@ -16,6 +19,7 @@ nodes:
   r1:
   r2:
     device: eos
+    graph.rank: 1
   r3:
   r4:
   r5:

tests/platform-integration/graph/create-graphviz.sh

@@ -13,7 +13,7 @@ if [[ "$OPTS" == *"topo"* ]]; then
   NETLAB_OUTPUTS_GRAPH_GROUPS=[fabric,host] graph topo.yml dot-topo-groups.svg ""
 fi
 if [[ "$OPTS" == *"bgp"* ]]; then
-  graph bgp.yml dot-bgp-default.svg :bgp "Default BGP graph"
+  NETLAB_GROUPS_CORE_GRAPH_RANK=1 graph bgp.yml dot-bgp-default.svg :bgp "Default BGP graph"
   graph bgp.yml dot-bgp-rr.svg :bgp:rr "BGP graph with RR sessions"
   graph bgp.yml dot-bgp-vrf.svg :bgp:vrf "BGP graph with VRF sessions"
   graph bgp.yml dot-bgp-novrf.svg :bgp:novrf "No VRF sessions in the BGP graph"

tests/platform-integration/graph/isis.yml

@@ -8,13 +8,18 @@ plugin: [ files ]
 isis.area: '49.0100'
 isis.type: level-2
 
+groups:
+  l2_is:
+    members: [ c1, c2, x1, x2 ]
+    graph.rank: 1
+
 nodes:
+  x1:
+    isis.area: "49.0001"
   c1:
     isis.type: level-1-2
   c2:
     isis.type: level-1-2
-  x1:
-    isis.area: "49.0001"
   x2:
     isis.area: "49.0002"
   r1:

tests/platform-integration/graph/topo.yml

@@ -15,6 +15,15 @@ groups:
   host:
     members: [ h1, h2, h3, h4 ]
     device: linux
+  spine:
+    members: [ s1, s2 ]
+    graph.rank: 1
+  leaf:
+    members: [ l1, l2 ]
+    graph.rank: 2
+  sa_host:
+    members: [ h3, h4 ]
+    graph.rank: 50
 
 module: [ ospf, bgp ]