[pve-devel] [PATCH pve-docs 1/1] fabrics: add initial documentation for sdn fabrics

[Gabriel Goller]

On 02.04.2025 10:49, Christoph Heiss wrote:
>On Fri Mar 28, 2025 at 6:13 PM CET, Gabriel Goller wrote:
>[..]
>> +
>> +Installation
>> +~~~~~~~~~~~~
>> +
>> +We use the FRR implementations of OpenFabric and OSPF, so first you need to
>> +install `frr` and the `frr-pythontools` package:
>
>Rather try to avoid first-person, as per our style guide [0].
>
>Could be rephrased as e.g.
>
>  The FRR implementations of OpenFabric and OSPF are used, so first the
>  `frr` and `frr-pythontools` packages must be installed:
>
>[0] https://pve.proxmox.com/wiki/Technical_Writing_Style_Guide#Avoid_first_person

Oops, yeah my oversight.

>> +
>> +----
>> +apt update
>> +apt install frr frr-pythontools
>> +----
>> +
>[..]
>> +
>> +[[pvesdn_openfabric_node]]
>> +On the Node
>> +^^^^^^^^^^^
>> +
>> +Node:: Select the node which will be added to the fabric. Only nodes that
>> +currently are in the cluster will be shown.
>> +
>> +Router-ID:: A unique IPv4 or IPv6 address used to generate the OpenFabric
>> +Network Entity Title (NET). Each node in the same fabric must have a different
>> +Router-ID, while a single node must use the same NET address across all fabrics
>> +(this consistency is automatically managed by {pve}).
>> +
>> +NOTE: When using IPv6 addresses, we use the last 3 segments to generate the
>> +NET. Ensure these segments differ between nodes.
>
>Same here w.r.t. first person ("we use").

Fixed this as well.

>> +
>> +Interfaces:: Specify the interfaces used to establish peering connections with
>> +other OpenFabric nodes. Preferably select interfaces without pre-assigned IP
>> +addresses, then configure addresses in the IPv4/IPv6 column if needed. A dummy
>> +"loopback" interface with the router-id is automatically created.
>> +Interface-specific settings override the global fabric settings.
>> +
>> +The following optional parameters can be configured per interface when enabling
>> +the additional columns:
>
>Perhaps this sentence should be made a bit more prominent, e.g. as
>sub-heading? It's easy to read over it and miss it, but it's quite
>important piece of information. Especially if your not *that* familiar
>with the UI and enablable columns.
>
>There are advanced options, so hiding them by default is good IMO - just
>a bit confusing to have big headings with the option names but nowhere
>to enable them (directly).

I thought about adding section (even though this is not exactly a
different panel in the UI), e.g.,

     On The Interface
     ^^^^^^^^^^^^^^^^

So we'd have:
OpenFabric
  - On the Node
  - On the Interface
  - On the Fabric

and obviously the same with OSPF.

What do you think?

Thanks for looking through this!