From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) by lore.proxmox.com (Postfix) with ESMTPS id 44C1A1FF15C for ; Fri, 22 Aug 2025 15:50:02 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id C449D1119E; Fri, 22 Aug 2025 15:49:55 +0200 (CEST) From: Stefan Hanreich To: pdm-devel@lists.proxmox.com Date: Fri, 22 Aug 2025 15:49:15 +0200 Message-ID: <20250822134942.380480-10-s.hanreich@proxmox.com> X-Mailer: git-send-email 2.47.2 In-Reply-To: <20250822134942.380480-1-s.hanreich@proxmox.com> References: <20250822134942.380480-1-s.hanreich@proxmox.com> MIME-Version: 1.0 X-SPAM-LEVEL: Spam detection results: 0 AWL -0.188 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment KAM_LAZY_DOMAIN_SECURITY 1 Sending domain does not have any anti-forgery methods RDNS_NONE 0.793 Delivered to internal network by a host with no rDNS SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_NONE 0.001 SPF: sender does not publish an SPF Record Subject: [pdm-devel] [PATCH pve-network v2 6/6] api: zones: update schema of endpoints X-BeenThere: pdm-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox Datacenter Manager development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Proxmox Datacenter Manager development discussion Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: pdm-devel-bounces@lists.proxmox.com Sender: "pdm-devel" The possible properties returned by the zone endpoints were only partly documented. Add all missing properties and improve descriptions for existing properties. Extract all duplicate properties into a separate variable, so we don't have to rewrite the whole API definition for every endpoint. Signed-off-by: Stefan Hanreich --- src/PVE/API2/Network/SDN/Zones.pm | 203 +++++++++++++++++++++-- src/PVE/Network/SDN/Zones/EvpnPlugin.pm | 22 ++- src/PVE/Network/SDN/Zones/QinQPlugin.pm | 6 +- src/PVE/Network/SDN/Zones/VlanPlugin.pm | 1 + src/PVE/Network/SDN/Zones/VxlanPlugin.pm | 15 +- 5 files changed, 218 insertions(+), 29 deletions(-) diff --git a/src/PVE/API2/Network/SDN/Zones.pm b/src/PVE/API2/Network/SDN/Zones.pm index 0e4726b..cc51652 100644 --- a/src/PVE/API2/Network/SDN/Zones.pm +++ b/src/PVE/API2/Network/SDN/Zones.pm @@ -62,6 +62,147 @@ my $api_sdn_zones_config = sub { return $scfg; }; +my $ZONE_PROPERTIES = { + mtu => { + type => 'integer', + optional => 1, + description => 'MTU of the zone, will be used for the created VNet bridges.', + }, + dns => { + type => 'string', + optional => 1, + description => 'ID of the DNS server for this zone.', + }, + reversedns => { + type => 'string', + optional => 1, + description => 'ID of the reverse DNS server for this zone.', + }, + dnszone => { + type => 'string', + optional => 1, + description => 'Domain name for this zone.', + }, + ipam => { + type => 'string', + optional => 1, + description => 'ID of the IPAM for this zone.', + }, + dhcp => { + type => 'string', + enum => ['dnsmasq'], + optional => 1, + description => 'Name of DHCP server backend for this zone.', + }, + 'rt-import' => { + type => 'string', + optional => 1, + description => + 'Comma-separated list of Route Targets that should be imported into the VRF of the zone. EVPN zone only.', + format => 'pve-sdn-bgp-rt-list', + }, + 'vrf-vxlan' => { + type => 'integer', + optional => 1, + description => 'VNI for the zone VRF. EVPN zone only.', + minimum => 1, + maximum => 16777215, + }, + mac => { + type => 'string', + optional => 1, + description => 'MAC address of the anycast router for this zone.', + }, + controller => { + type => 'string', + optional => 1, + description => 'ID of the controller for this zone. EVPN zone only.', + }, + nodes => { + type => 'string', + optional => 1, + description => 'Nodes where this zone should be created.', + }, + 'exitnodes' => get_standard_option( + 'pve-node-list', + { + description => + "List of PVE Nodes that should act as exit node for this zone. EVPN zone only.", + optional => 1, + }, + ), + 'exitnodes-local-routing' => { + type => 'boolean', + description => + "Create routes on the exit nodes, so they can connect to EVPN guests. EVPN zone only.", + optional => 1, + }, + 'exitnodes-primary' => get_standard_option( + 'pve-node', + { + description => "Force traffic through this exitnode first. EVPN zone only.", + optional => 1, + }, + ), + 'advertise-subnets' => { + type => 'boolean', + description => + "Advertise IP prefixes (Type-5 routes) instead of MAC/IP pairs (Type-2 routes). EVPN zone only.", + optional => 1, + }, + 'disable-arp-nd-suppression' => { + type => 'boolean', + description => + "Suppress IPv4 ARP && IPv6 Neighbour Discovery messages. EVPN zone only.", + optional => 1, + }, + 'rt-import' => { + type => 'string', + description => + "Route-Targets that should be imported into the VRF of this zone via BGP. EVPN zone only.", + optional => 1, + format => 'pve-sdn-bgp-rt-list', + }, + tag => { + type => 'integer', + minimum => 0, + optional => 1, + description => "Service-VLAN Tag (outer VLAN). QinQ zone only", + }, + 'vlan-protocol' => { + type => 'string', + enum => ['802.1q', '802.1ad'], + default => '802.1q', + optional => 1, + description => "VLAN protocol for the creation of the QinQ zone. QinQ zone only.", + }, + 'peers' => { + description => + "Comma-separated list of peers, that are part of the VXLAN zone. Usually the IPs of the nodes. VXLAN zone only.", + type => 'string', + format => 'ip-list', + optional => 1, + }, + 'vxlan-port' => { + description => + "UDP port that should be used for the VXLAN tunnel (default 4789). VXLAN zone only.", + minimum => 1, + maximum => 65536, + type => 'integer', + optional => 1, + }, + 'bridge' => { + type => 'string', + description => 'the bridge for which VLANs should be managed. VLAN & QinQ zone only.', + optional => 1, + }, + 'bridge-disable-mac-learning' => { + type => 'boolean', + description => "Disable auto mac learning. VLAN zone only.", + optional => 1, + }, +}; + __PACKAGE__->register_method({ name => 'index', path => '', @@ -98,17 +239,29 @@ __PACKAGE__->register_method({ items => { type => "object", properties => { - zone => { type => 'string' }, - type => { type => 'string' }, - mtu => { type => 'integer', optional => 1 }, - dns => { type => 'string', optional => 1 }, - reversedns => { type => 'string', optional => 1 }, - dnszone => { type => 'string', optional => 1 }, - ipam => { type => 'string', optional => 1 }, - dhcp => { type => 'string', optional => 1 }, - pending => { type => 'boolean', optional => 1 }, - state => { type => 'string', optional => 1 }, - nodes => { type => 'string', optional => 1 }, + digest => { + type => 'string', + description => 'Digest of the controller section.', + optional => 1, + }, + state => get_standard_option('pve-sdn-config-state'), + zone => { + type => 'string', + description => 'Name of the zone.', + }, + type => { + type => 'string', + description => 'Type of the zone.', + enum => PVE::Network::SDN::Zones::Plugin->lookup_types(), + }, + pending => { + type => 'object', + description => + 'Changes that have not yet been applied to the running configuration.', + optional => 1, + properties => $ZONE_PROPERTIES, + }, + %$ZONE_PROPERTIES, }, }, links => [{ rel => 'child', href => "{zone}" }], @@ -174,7 +327,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'), + zone => { + type => 'string', + description => 'Name of the zone.', + }, + type => { + type => 'string', + description => 'Type of the zone.', + enum => PVE::Network::SDN::Zones::Plugin->lookup_types(), + }, + pending => { + type => 'object', + description => + 'Changes that have not yet been applied to the running configuration.', + optional => 1, + properties => $ZONE_PROPERTIES, + }, + %$ZONE_PROPERTIES, + }, + }, code => sub { my ($param) = @_; diff --git a/src/PVE/Network/SDN/Zones/EvpnPlugin.pm b/src/PVE/Network/SDN/Zones/EvpnPlugin.pm index 0153364..4354bff 100644 --- a/src/PVE/Network/SDN/Zones/EvpnPlugin.pm +++ b/src/PVE/Network/SDN/Zones/EvpnPlugin.pm @@ -45,41 +45,47 @@ sub properties { return { 'vrf-vxlan' => { type => 'integer', - description => "l3vni.", + description => "VNI for the zone VRF.", + minimum => 1, + maximum => 16777215, }, 'controller' => { type => 'string', - description => "Frr router name", + description => 'Controller for this zone.', }, 'mac' => { type => 'string', - description => "Anycast logical router mac address", + description => "Anycast logical router mac address.", optional => 1, format => 'mac-addr', }, 'exitnodes' => get_standard_option('pve-node-list'), 'exitnodes-local-routing' => { type => 'boolean', - description => "Allow exitnodes to connect to evpn guests", + description => "Allow exitnodes to connect to EVPN guests.", optional => 1, }, 'exitnodes-primary' => get_standard_option( 'pve-node', - { description => "Force traffic to this exitnode first." }, + { + description => "Force traffic through this exitnode first.", + }, ), 'advertise-subnets' => { type => 'boolean', - description => "Advertise evpn subnets if you have silent hosts", + description => + "Advertise IP prefixes (Type-5 routes) instead of MAC/IP pairs (Type-2 routes).", optional => 1, }, 'disable-arp-nd-suppression' => { type => 'boolean', - description => "Disable ipv4 arp && ipv6 neighbour discovery suppression", + description => "Suppress IPv4 ARP && IPv6 Neighbour Discovery messages.", optional => 1, }, 'rt-import' => { type => 'string', - description => "Route-Target import", + description => + 'List of Route Targets that should be imported into the VRF of the zone', optional => 1, format => 'pve-sdn-bgp-rt-list', }, diff --git a/src/PVE/Network/SDN/Zones/QinQPlugin.pm b/src/PVE/Network/SDN/Zones/QinQPlugin.pm index 5806e69..3c72d35 100644 --- a/src/PVE/Network/SDN/Zones/QinQPlugin.pm +++ b/src/PVE/Network/SDN/Zones/QinQPlugin.pm @@ -18,11 +18,11 @@ sub properties { tag => { type => 'integer', minimum => 0, - description => "Service-VLAN Tag", + description => "Service-VLAN Tag (outer VLAN)", }, mtu => { type => 'integer', - description => "MTU", + description => "MTU of the zone, will be used for the created VNet bridges.", optional => 1, }, 'vlan-protocol' => { @@ -30,6 +30,8 @@ sub properties { enum => ['802.1q', '802.1ad'], default => '802.1q', optional => 1, + description => + "Which VLAN protocol should be used for the creation of the QinQ zone", }, }; } diff --git a/src/PVE/Network/SDN/Zones/VlanPlugin.pm b/src/PVE/Network/SDN/Zones/VlanPlugin.pm index 90f16bf..9d6932f 100644 --- a/src/PVE/Network/SDN/Zones/VlanPlugin.pm +++ b/src/PVE/Network/SDN/Zones/VlanPlugin.pm @@ -27,6 +27,7 @@ sub properties { return { 'bridge' => { type => 'string', + description => 'the bridge for which VLANs should be managed', }, 'bridge-disable-mac-learning' => { type => 'boolean', diff --git a/src/PVE/Network/SDN/Zones/VxlanPlugin.pm b/src/PVE/Network/SDN/Zones/VxlanPlugin.pm index 8f6fba0..7ab89da 100644 --- a/src/PVE/Network/SDN/Zones/VxlanPlugin.pm +++ b/src/PVE/Network/SDN/Zones/VxlanPlugin.pm @@ -27,21 +27,22 @@ sub type { sub properties { return { 'peers' => { - description => "peers address list.", + description => + "Comma-separated list of peers, that are part of the VXLAN zone. Usually the IPs of the nodes.", type => 'string', format => 'ip-list', }, - fabric => { - description => "SDN fabric to use as underlay for this VXLAN zone.", - type => 'string', - format => 'pve-sdn-fabric-id', - }, 'vxlan-port' => { - description => "Vxlan tunnel udp port (default 4789).", + description => "UDP port that should be used for the VXLAN tunnel (default 4789).", minimum => 1, maximum => 65536, type => 'integer', }, + fabric => { + description => "SDN fabric to use as underlay for this VXLAN zone.", + type => 'string', + format => 'pve-sdn-fabric-id', + }, }; } -- 2.47.2 _______________________________________________ pdm-devel mailing list pdm-devel@lists.proxmox.com https://lists.proxmox.com/cgi-bin/mailman/listinfo/pdm-devel