From ed013f92ce890b82d919ccb0aaf309e65973bfc8 Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Thu, 4 Sep 2025 10:18:32 +0200 Subject: api: controllers: update schema of endpoints The possible properties returned by the controller endpoints were only partly documented. Add all missing properties and update descriptions for existing properties. Update the descriptions of the schemas in the plugin to provide more detailed information about the different configuration options. Move all duplicate properties between the GET endpoints into its own variable, so we can reuse them. Signed-off-by: Stefan Hanreich Reviewed-by: Dominik Csapak Tested-by: Dominik Csapak --- src/PVE/API2/Network/SDN/Controllers.pm | 116 ++++++++++++++++++++++++-- src/PVE/Network/SDN/Controllers/BgpPlugin.pm | 7 +- src/PVE/Network/SDN/Controllers/IsisPlugin.pm | 6 +- 3 files changed, 119 insertions(+), 10 deletions(-) diff --git a/src/PVE/API2/Network/SDN/Controllers.pm b/src/PVE/API2/Network/SDN/Controllers.pm index 5c2b6c3..bc3ec09 100644 --- a/src/PVE/API2/Network/SDN/Controllers.pm +++ b/src/PVE/API2/Network/SDN/Controllers.pm @@ -34,6 +34,67 @@ my $api_sdn_controllers_config = sub { return $scfg; }; +my $CONTROLLER_PROPERTIES = { + asn => { + type => 'integer', + description => 'The local ASN of the controller. BGP & EVPN only.', + optional => 1, + minimum => 0, + maximum => 4294967295, + }, + node => { + type => 'string', + optional => 1, + description => 'Node(s) where this controller is active.', + }, + peers => { + type => 'string', + optional => 1, + description => 'Comma-separated list of the peers IP addresses.', + }, + 'bgp-multipath-as-relax' => { + type => 'boolean', + optional => 1, + description => + 'Consider different AS paths of equal length for multipath computation. BGP only.', + }, + ebgp => { + type => 'boolean', + optional => 1, + description => "Enable eBGP (remote-as external). BGP only.", + }, + 'ebgp-multihop' => { + type => 'integer', + optional => 1, + description => + "Set maximum amount of hops for eBGP peers. Needs ebgp set to 1. BGP only.", + }, + loopback => { + description => + "Name of the loopback/dummy interface that provides the Router-IP. BGP only.", + optional => 1, + type => 'string', + }, + 'isis-domain' => { + description => "Name of the IS-IS domain. IS-IS only.", + optional => 1, + type => 'string', + }, + 'isis-ifaces' => { + description => + "Comma-separated list of interfaces where IS-IS should be active. IS-IS only.", + optional => 1, + type => 'string', + format => 'pve-iface-list', + }, + 'isis-net' => { + description => "Network Entity title for this node in the IS-IS network. IS-IS only.", + optional => 1, + type => 'string', + format => 'pve-sdn-isis-net', + }, +}; + __PACKAGE__->register_method({ name => 'index', path => '', @@ -70,10 +131,29 @@ __PACKAGE__->register_method({ items => { type => "object", properties => { - controller => { type => 'string' }, - type => { type => 'string' }, - state => { type => 'string', optional => 1 }, - pending => { type => 'boolean', optional => 1 }, + digest => { + type => 'string', + description => 'Digest of the controller section.', + optional => 1, + }, + state => get_standard_option('pve-sdn-config-state'), + controller => { + type => 'string', + description => 'Name of the controller.', + }, + type => { + type => 'string', + description => 'Type of the controller', + enum => PVE::Network::SDN::Controllers::Plugin->lookup_types(), + }, + pending => { + type => 'object', + description => + 'Changes that have not yet been applied to the running configuration.', + optional => 1, + properties => $CONTROLLER_PROPERTIES, + }, + %$CONTROLLER_PROPERTIES, }, }, links => [{ rel => 'child', href => "{controller}" }], @@ -139,7 +219,33 @@ __PACKAGE__->register_method({ }, }, }, - returns => { type => 'object' }, + returns => { + properties => { + digest => { + type => 'string', + description => 'Digest of the controller section.', + optional => 1, + }, + state => get_standard_option('pve-sdn-config-state'), + controller => { + type => 'string', + description => 'Name of the controller.', + }, + type => { + type => 'string', + description => 'Type of the controller', + enum => PVE::Network::SDN::Controllers::Plugin->lookup_types(), + }, + pending => { + type => 'object', + description => + 'Changes that have not yet been applied to the running configuration.', + optional => 1, + properties => $CONTROLLER_PROPERTIES, + }, + %$CONTROLLER_PROPERTIES, + }, + }, code => sub { my ($param) = @_; diff --git a/src/PVE/Network/SDN/Controllers/BgpPlugin.pm b/src/PVE/Network/SDN/Controllers/BgpPlugin.pm index 5f3fcb0..c84b384 100644 --- a/src/PVE/Network/SDN/Controllers/BgpPlugin.pm +++ b/src/PVE/Network/SDN/Controllers/BgpPlugin.pm @@ -22,18 +22,21 @@ sub properties { 'bgp-multipath-as-path-relax' => { type => 'boolean', optional => 1, + description => + 'Consider different AS paths of equal length for multipath computation.', }, ebgp => { type => 'boolean', optional => 1, - description => "Enable ebgp. (remote-as external)", + description => "Enable eBGP (remote-as external).", }, 'ebgp-multihop' => { type => 'integer', optional => 1, + description => 'Set maximum amount of hops for eBGP peers.', }, loopback => { - description => "source loopback interface.", + description => "Name of the loopback/dummy interface that provides the Router-IP.", type => 'string', }, node => get_standard_option('pve-node'), diff --git a/src/PVE/Network/SDN/Controllers/IsisPlugin.pm b/src/PVE/Network/SDN/Controllers/IsisPlugin.pm index 716bb0f..3a9acfd 100644 --- a/src/PVE/Network/SDN/Controllers/IsisPlugin.pm +++ b/src/PVE/Network/SDN/Controllers/IsisPlugin.pm @@ -31,16 +31,16 @@ sub pve_verify_sdn_isis_net { sub properties { return { 'isis-domain' => { - description => "ISIS domain.", + description => "Name of the IS-IS domain.", type => 'string', }, 'isis-ifaces' => { - description => "ISIS interface.", + description => "Comma-separated list of interfaces where IS-IS should be active.", type => 'string', format => 'pve-iface-list', }, 'isis-net' => { - description => "ISIS network entity title.", + description => "Network Entity title for this node in the IS-IS network.", type => 'string', format => 'pve-sdn-isis-net', }, -- cgit v1.2.3