[pve-devel] [PATCH common/manager/network/proxmox{-ve-rs, -perl-rs} v3 00/39] Improve status reporting for SDN / networking

[Stefan Hanreich <s.hanreich@proxmox.com>]

## Warning

Applying this patch series, will break all version of PDM that do not have
support for the new network type, since all nodes now send resources that are
incompatible with the PDM schema. We might want to consider holding off the
resource type parts until after we've prepared a PDM version that can actually
handle those resources. Prior to v2, this was only limited to Remotes that have
an SDN fabric configured - now it isn't anymore since every node sends at least
the localnetwork SDN zone as a network resource.

## Introduction

This patch series builds upon and replaces the two patch series initially
submitted by Gabriel [1] [2]. Main reason for merging those is that some
additional refactoring to the status API module structure as well as the UI
widgets for the SDN browser has been done, which both series would need to
depend on. Additionally, the EVPN series depended on the fabric series already
as well, so submitting them as one seemed like the least complicated option for
both developers and maintainers with the additional changes introduced in this
iteration.

refreshed packages are available on sani: `network-resource-pve`

## Rationale

Currently, the SDN and PVE networking stack provide little insight into their
inner workings and can be a bit of a black box to users. Inspecting the current
state of networking resources, particularly for EVPN zones, requires dropping
into the CLI and invoking specific iproute2 / FRR commands. The current status
endpoint only provides very coarse and limited feedback on the current state of
SDN / networking resources.

With this iteration, this patch series also adds status reporting for bridges /
vnets, which has been requested several times in forums / enterprise support /
trainings.

Most of those endpoints could be interesting additions to the PDM UI as well,
particularly fabrics and evpn status.


## New network resource type

While the initial implementations extended the existing SDN resource type, this
iteration introduces a 'network' resource type. The pre-existing SDN resource
type utilized 'sdn/<zone_id>' as its id, which makes it hard to add additional
types that do not share that ID space. Changing the schema for the ID would also
break backwards-compatibility of API and UI between 9.0 and 9.1.

With potential additional status reporting for other network entities (see
below), it would make sense to generalize the resource type to network in
particular, to avoid cluttering the top level with one type per SDN/networking
entity. If that is not a concern, the current state could be easily adapted to
have one top-level type per resource - simplifying the current implementation.

The ID schema for this resource type is now as follow:

network/{node}/{network_type}/{name}

An example network resource:

	{
		"id": "network/acolyte/fabric/underlay",
		"type": "network",
		"network_type": "fabric",
		"network": "underlay"
		"node": "acolyte",
		"status": "ok",
		"protocol": "ospf",
	}

The plan for migrating:
* New nodes will report the resource status in *both* formats
* New networking entities (fabrics, for now) will utilize the network resource
  type only
* When migrating from PVE 9 -> 10, status reporting for zones will move to the
  new network resource type completely
* old nodes should be able to cope with the old format, but they cannot display
  any newly returned information - it will get dropped
* PDM will also be able to handle both formats with a separate pdm series, so
  older versions of Proxmox VE can also be used with PDM

I know this is a bit of a sledgehammer method of solving this problem, but imo
while this migration might be a bit painful now, it seems the best option to me
long-term. Any suggestions / opinions on this would be greatly appreciated. I
don't really see another way of implementing additional types of entities
without either breaking backwards-compatibility with PVE <= 9.0 or having
potential ID collisions in the SDN resource type or having one dedicated type
per networking resource.


## Potential future work / extensions

Add status reporting for the firewall, which currently acts a bit like a
black-box as well, without any easy way of checking the current (running) state
of the firewall.

Other entities to consider adding to the resources: controllers, DNS, external
IPAM.

The data from those endpoints could be used to provide a graphical overview of a
bridge in the UI, an idea which has been floating around internally for awhile.


## New API endpoints

/nodes/{node}/sdn/fabrics/{fabric}/routes
/nodes/{node}/sdn/fabrics/{fabric}/neighbors
/nodes/{node}/sdn/fabrics/{fabric}/interfaces

/nodes/{node}/sdn/zones/{zone}/ip-vrf
/nodes/{node}/sdn/zones/{zone}/bridges

/nodes/{node}/sdn/vnets/{vnet}/mac-vrf


## New UI panels

Those panels can all be reached via the resource tree and are found in the SDN
browser.

For all zones:
* Bridges overview

For EVPN zones:
* IP-VRF
* MAC-VRFs

For Fabrics:
* Routes
* Neighbors
* Interfaces


## Dependencies

proxmox-perl-rs depends on proxmox-ve-rs
pve-network depends on proxmox-perl-rs
pve-network depends on pve-common
pve-manager depends on pve-network


Changes from v2:
* Made the implications of merging this patch series more evident and prominent
  in the cover letter
* Fix SDN status overview
* Fix displayed icon for zones in the ResourceTree

Changes from v1 (Thanks @Thomas, @Wolfgang, @Hannes, @Gabriel!):
* Broadcast zones via both resource types, not only the previous sdn one
* Add handling for receiving zones via both resource types, to avoid duplicated
  entries
* Update fabrics API endpoints descriptions and property descriptions
* Fix typo when checking parameter in the NetworkBrowser panel
* add definedness check in ip_link_is_bridge_member
* add integration / snapshot tests (courtesy of gabriel)
* -compressvlan -> -compressvlans in IPRoute2 Helper

Changes from (v1, v4):

* refactor the SDN status API module structure (no functional changes to
  existing endpoints)
* move the fabrics API endpoints to the pre-existing /nodes/{node}/sdn subdir
* refactor the SDN content view panel, so it can be reused for the EVPN panels
  (no functional changes to existing UI panels)
* add a completely new resource type, instead of trying to re-use the existing
  SDN one (reasoning above).
* move the iproute2 and bridge helpers to pve-common
* improve JSONSchema of all API endpoints (descriptions mainly)
* return additional information in the fabric endpoints
* add full UI integration for EVPN status (IP-VRF + MAC-VRF panels)
* Use the installed, duplicate and bestpath properties of FRR to show only
  routes that are actually installed into the kernel routing table for EVPN
  zones
* filter for type 2 routes specifically when invoking vtysh

[1] https://lore.proxmox.com/pve-devel/20250904114206.193052-1-g.goller@proxmox.com/
[2] https://lore.proxmox.com/pve-devel/20250905114504.195110-1-g.goller@proxmox.com/

pve-common:

Stefan Hanreich (2):
  iproute2: add helper for detecting bridge members
  iproute2: add helper for querying vlan information

 src/PVE/IPRoute2.pm | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)


proxmox-ve-rs:

Gabriel Goller (7):
  frr: make room for deserialization structs
  frr: add deserialization types for openfabric and ospf
  ve-config: add helper function to iterate over all nodes in all
    fabrics
  ve-config: add optional tag property to vnet
  frr: fix some route deserialization types
  frr: add deserialization types for EVPN
  add derive PartialEq, Eq and HashMap->BTreeMap for tests

 proxmox-frr/Cargo.toml                        |   2 +
 proxmox-frr/debian/control                    |   6 +
 proxmox-frr/src/de/evpn.rs                    | 165 ++++++++++++
 proxmox-frr/src/de/mod.rs                     |  49 ++++
 proxmox-frr/src/de/openfabric.rs              | 101 ++++++++
 proxmox-frr/src/de/ospf.rs                    |  70 +++++
 proxmox-frr/src/lib.rs                        | 243 +-----------------
 proxmox-frr/src/ser/mod.rs                    | 241 +++++++++++++++++
 proxmox-frr/src/{ => ser}/openfabric.rs       |   4 +-
 proxmox-frr/src/{ => ser}/ospf.rs             |   2 +-
 proxmox-frr/src/{ => ser}/route_map.rs        |   0
 proxmox-frr/src/{ => ser}/serializer.rs       |   2 +-
 proxmox-ve-config/src/sdn/config.rs           |  27 +-
 proxmox-ve-config/src/sdn/fabric/frr.rs       | 170 ++++++------
 proxmox-ve-config/src/sdn/fabric/mod.rs       |   5 +
 proxmox-ve-config/src/sdn/frr.rs              |   2 +-
 proxmox-ve-config/tests/fabric/main.rs        |   2 +-
 proxmox-ve-config/tests/sdn/main.rs           |   5 +-
 .../tests/sdn/resources/running-config.json   |   1 +
 19 files changed, 767 insertions(+), 330 deletions(-)
 create mode 100644 proxmox-frr/src/de/evpn.rs
 create mode 100644 proxmox-frr/src/de/mod.rs
 create mode 100644 proxmox-frr/src/de/openfabric.rs
 create mode 100644 proxmox-frr/src/de/ospf.rs
 create mode 100644 proxmox-frr/src/ser/mod.rs
 rename proxmox-frr/src/{ => ser}/openfabric.rs (97%)
 rename proxmox-frr/src/{ => ser}/ospf.rs (99%)
 rename proxmox-frr/src/{ => ser}/route_map.rs (100%)
 rename proxmox-frr/src/{ => ser}/serializer.rs (99%)


proxmox-perl-rs:

Gabriel Goller (11):
  pve-rs: firewall: cargo: fmt
  pve-rs: cargo: bump proxmox-apt and proxmox-ve-config versions
  pve-rs: fabrics: update proxmox-frr import path
  pve-rs: fabrics: fix clippy lint warnings
  pve-rs: fabrics: add function to get status of fabric
  pve-rs: fabrics: add function to get l2vpn and l3vpn routes for evpn
  pve-rs: fabrics: add function to get routes learned by a fabric
  pve-rs: fabrics: add function to get the interfaces used for a fabric
  pve-rs: fabrics: add function to get the neighbors for a fabric
  pve-rs: fabrics: add unit-tests for fabrics
  pve-rs: fabrics: add unit-tests for evpn l2vpn and l3vpn routes

Stefan Hanreich (1):
  pve-rs: firewall: add missing documentation comments

 pve-rs/Cargo.toml                   |    4 +-
 pve-rs/src/bindings/firewall/sdn.rs |   16 +-
 pve-rs/src/bindings/sdn/fabrics.rs  |  313 +++-
 pve-rs/src/lib.rs                   |    2 +
 pve-rs/src/sdn/mod.rs               |    3 +
 pve-rs/src/sdn/status.rs            | 2655 +++++++++++++++++++++++++++
 6 files changed, 2983 insertions(+), 10 deletions(-)
 create mode 100644 pve-rs/src/sdn/mod.rs
 create mode 100644 pve-rs/src/sdn/status.rs


pve-network:

Gabriel Goller (3):
  fabrics: add fabrics status to SDN::status function
  api: nodes: fabrics: add endpoint for querying route status
  api: nodes: fabrics: add endpoint for querying neighbor information

Stefan Hanreich (6):
  refactor: rework api module structure for the /nodes/{node}/sdn subdir
  sdn: status: add zone type to sdn resource
  api: nodes: fabrics: add endpoint for querying interface status
  api: nodes: zones: add bridge status
  api: nodes: zones: add ip vrf endpoint for evpn zones
  api: nodes: vnets: add mac-vrf endpoint for evpn vnets

 src/PVE/API2/Network/SDN/Makefile             |   2 +-
 src/PVE/API2/Network/SDN/Nodes/Fabric.pm      | 187 +++++++++
 src/PVE/API2/Network/SDN/Nodes/Fabrics.pm     |  16 +
 .../Network/SDN/{Zones => Nodes}/Makefile     |  12 +-
 src/PVE/API2/Network/SDN/Nodes/Status.pm      |  61 +++
 src/PVE/API2/Network/SDN/Nodes/Vnet.pm        | 147 +++++++
 src/PVE/API2/Network/SDN/Nodes/Vnets.pm       |  16 +
 src/PVE/API2/Network/SDN/Nodes/Zone.pm        | 379 ++++++++++++++++++
 .../SDN/{Zones/Status.pm => Nodes/Zones.pm}   |  58 +--
 src/PVE/API2/Network/SDN/Vnets.pm             |   2 +-
 src/PVE/API2/Network/SDN/Zones/Content.pm     |  88 ----
 src/PVE/Network/SDN.pm                        |   6 +-
 src/PVE/Network/SDN/Zones.pm                  |   2 +
 src/test/debug/statuscheck.pl                 |   3 +-
 14 files changed, 833 insertions(+), 146 deletions(-)
 create mode 100644 src/PVE/API2/Network/SDN/Nodes/Fabric.pm
 create mode 100644 src/PVE/API2/Network/SDN/Nodes/Fabrics.pm
 rename src/PVE/API2/Network/SDN/{Zones => Nodes}/Makefile (51%)
 create mode 100644 src/PVE/API2/Network/SDN/Nodes/Status.pm
 create mode 100644 src/PVE/API2/Network/SDN/Nodes/Vnet.pm
 create mode 100644 src/PVE/API2/Network/SDN/Nodes/Vnets.pm
 create mode 100644 src/PVE/API2/Network/SDN/Nodes/Zone.pm
 rename src/PVE/API2/Network/SDN/{Zones/Status.pm => Nodes/Zones.pm} (56%)
 delete mode 100644 src/PVE/API2/Network/SDN/Zones/Content.pm


pve-manager:

Gabriel Goller (2):
  pvestatd: add network resource to status reporting
  ui: resource tree: add network resource

Stefan Hanreich (7):
  api: nodes: use new status module for sdn subdirectory
  refactor: ui: sdn browser: parametrize zone content panel
  pvestatd: sdn: adapt to changes in status reporting
  ui: network browser: Add ip-vrf panel for evpn zones
  ui: network browser: add mac vrf panel
  ui: network browser: add zone bridge view
  ui: sdn: status view: adapt to new network resource

 PVE/API2/Cluster.pm                     | 118 +++++++++++++----
 PVE/API2/Nodes.pm                       |  50 +------
 PVE/Service/pvestatd.pm                 |  39 ++++--
 www/manager6/Makefile                   |   6 +
 www/manager6/Utils.js                   |  12 ++
 www/manager6/Workspace.js               |   1 +
 www/manager6/sdn/Browser.js             |  29 ++++
 www/manager6/sdn/EvpnZoneIpVrfPanel.js  |  84 ++++++++++++
 www/manager6/sdn/EvpnZoneMacVrfPanel.js | 130 ++++++++++++++++++
 www/manager6/sdn/FabricsContentView.js  |  77 +++++++++++
 www/manager6/sdn/NetworkBrowser.js      | 167 ++++++++++++++++++++++++
 www/manager6/sdn/StatusView.js          |  11 +-
 www/manager6/sdn/ZoneBridgeView.js      |  88 +++++++++++++
 www/manager6/sdn/ZoneBridgesPanel.js    | 131 +++++++++++++++++++
 www/manager6/sdn/ZoneContentPanel.js    |  11 +-
 www/manager6/sdn/ZoneContentView.js     |  75 ++++++-----
 www/manager6/tree/ResourceTree.js       |   6 +
 17 files changed, 918 insertions(+), 117 deletions(-)
 create mode 100644 www/manager6/sdn/EvpnZoneIpVrfPanel.js
 create mode 100644 www/manager6/sdn/EvpnZoneMacVrfPanel.js
 create mode 100644 www/manager6/sdn/FabricsContentView.js
 create mode 100644 www/manager6/sdn/NetworkBrowser.js
 create mode 100644 www/manager6/sdn/ZoneBridgeView.js
 create mode 100644 www/manager6/sdn/ZoneBridgesPanel.js


Summary over all repositories:
  57 files changed, 5526 insertions(+), 603 deletions(-)

-- 
Generated by git-murpp 0.8.0

_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel