[pve-devel] [PATCH pve-network 5/5] api: zones: update schema of endpoints
Stefan Hanreich
s.hanreich at proxmox.com
Fri Feb 28 15:01:36 CET 2025
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 at 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
More information about the pve-devel
mailing list