[pdm-devel] [PATCH pve-network v3 6/6] 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        | 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