[pve-devel] [PATCH pve-network 5/5] api: zones: update schema of endpoints

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

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 <s.hanreich@proxmox.com>
---
 src/PVE/API2/Network/SDN/Zones.pm        | 190 +++++++++++++++++++++--
 src/PVE/Network/SDN/Zones/EvpnPlugin.pm  |  22 +--
 src/PVE/Network/SDN/Zones/QinQPlugin.pm  |   5 +-
 src/PVE/Network/SDN/Zones/VlanPlugin.pm  |   1 +
 src/PVE/Network/SDN/Zones/VxlanPlugin.pm |  21 +--
 5 files changed, 205 insertions(+), 34 deletions(-)

diff --git a/src/PVE/API2/Network/SDN/Zones.pm b/src/PVE/API2/Network/SDN/Zones.pm
index 6baee52..7b28199 100644
--- a/src/PVE/API2/Network/SDN/Zones.pm
+++ b/src/PVE/API2/Network/SDN/Zones.pm
@@ -58,6 +58,133 @@ 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 => '',
@@ -92,18 +219,30 @@ __PACKAGE__->register_method ({
 	type => 'array',
 	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},
-			  },
+	    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,
+	  },
 	},
 	links => [ { rel => 'child', href => "{zone}" } ],
     },
@@ -167,7 +306,32 @@ __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 4843756..f3504d5 100644
--- a/src/PVE/Network/SDN/Zones/EvpnPlugin.pm
+++ b/src/PVE/Network/SDN/Zones/EvpnPlugin.pm
@@ -44,39 +44,43 @@ 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",
-	    optional => 1, format => 'pve-sdn-bgp-rt-list'
+	    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 4c4be64..9346043 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,7 @@ 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 13fb49e..05d1ae8 100644
--- a/src/PVE/Network/SDN/Zones/VlanPlugin.pm
+++ b/src/PVE/Network/SDN/Zones/VlanPlugin.pm
@@ -24,6 +24,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 9a77bb9..19996ce 100644
--- a/src/PVE/Network/SDN/Zones/VxlanPlugin.pm
+++ b/src/PVE/Network/SDN/Zones/VxlanPlugin.pm
@@ -25,16 +25,17 @@ sub type {
 
 sub properties {
     return {
-        'peers' => {
-            description => "peers address list.",
-            type => 'string', format => 'ip-list'
-        },
-        'vxlan-port' => {
-            description => "Vxlan tunnel udp port (default 4789).",
-            minimum => 1,
-            maximum => 65536,
-            type => 'integer'
-        },
+	'peers' => {
+	    description => "Comma-separated list of peers, that are part of the VXLAN zone. Usually the IPs of the nodes.",
+	    type => 'string',
+	    format => 'ip-list'
+	},
+	'vxlan-port' => {
+	    description => "UDP port that should be used for the VXLAN tunnel (default 4789).",
+	    minimum => 1,
+	    maximum => 65536,
+	    type => 'integer'
+	},
     };
 }
 
-- 
2.39.5


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