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

[Christoph Heiss]

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

> +
> +----
> +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").

> +
> +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).

[..]
> +
> +[[pvesdn_ospf_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 address used to identify this router within the OSPF
> +network. Each node in the same fabric must have a different Router-ID.
> +
> +Interfaces:: Specify the interfaces used to establish peering connections with
> +other OSPF nodes. Preferably select interfaces without pre-assigned IP
> +addresses, then configure addresses in the IPv4 column if needed. A dummy
> +"loopback" interface with the router-id is automatically created.
> +
> +The following optional parameter can be configured per interface when enabling
> +the additional columns:

^ Same as above.