superseded: [PATCH docs/network 00/10] sdn: improve MAC cache, DHCP reservations and scope both to the vnet

[Hannes Laimer <h.laimer@proxmox.com>]

superseded-by:
https://lore.proxmox.com/pve-devel/20261102145630.1555953-1-h.laimer@proxmox.com

On 2026-11-02 12:06, Hannes Laimer wrote:
> This series addresses some problems in the IPAM code, mostly around
> caching. It also solves the problem that the MAC cache and the lookup
> behind it held a single address per MAC. This is a problem since MACs
> only have to be unique within a vnet and can repeat across vnets, and
> it led to a guest getting the IP of a guest with the same MAC on
> another vnet.
> 
> Patches 1-5 address general, mostly cache related problems. Patches
> 1-4 were already included in [1], 1-3 changed since then. Patch 1
> leaves entries without an address in the file and treats them as a
> miss, patch 2 skips the fill when the file changed while the IPAM was
> asked, and patch 3 leaves the cache keys as written, since nodes not
> yet upgraded still use them. Patch 5 is new.
> 
> Patch 6 adds updating of the dnsmasq reservations when a mapping
> changes, so dnsmasq picks the change up immediately and a guest gets
> its new address without a restart.
> 
> Patches 7-8 scope the lookup and the cache to the vnet, so guests
> don't get addresses of another vnet. The cache file now contains a
> `vnets` map next to `macs`. `macs` is not converted, its entries stay
> as written until their addresses are released, since nodes not yet
> upgraded still use them. They serve as fallback for a vnet, but only
> with addresses inside that vnet's subnets. A miss in the cache asks
> the IPAM within the vnet's subnets, and that answer is put into the
> new `vnets` map. So an old entry answers only for the vnet it was
> written for. The one exception is the same or an overlapping range on
> two vnets, where an old entry answers for the other vnet too, as it
> did before, until that vnet has an entry of its own or the address
> is released.
> 
> Patch 9 adds separation by zone for the two external IPAM providers
> we support, since two zones can use the same range.
>  - NetBox: each zone gets its own `pve-<zone>` VRF, and the prefixes
>    of its subnets go in there
>  - phpIPAM: each zone gets a sub-section `pve-<zone>` under the
>    configured one, and its subnets go in there(only if the configured
>    section is not a sub-section already, phpIPAM only allows 1 deep
>    nesting)
> 
> Patch 10 just adds docs explaining this for the two external IPAMs.
> 
> This is not a breaking change, existing assignments are returned
> exactly like they are already. Cache entries from before stay as
> written, since nodes not yet upgraded still use them, and answer for a
> vnet with the addresses in its subnets, so a running guest keeps its
> reservation. Records in an external IPAM stay where they are, in
> NetBox's global table or in phpIPAM's configured section. Like the
> cache, an IPAM lookup first checks the zone's VRF or section for the
> subnet and falls back to the global table or the configured section.
> Unlike with the cache, migration can be done manually, by moving a
> prefix together with its addresses and IP ranges into the zone's VRF
> in NetBox, or a subnet into the zone's sub-section in phpIPAM, since
> the lookup checks those first. Migration is not necessary though.
> Creating a subnet creates the VRF or sub-section if it doesn't exist
> yet, nothing else does. We don't move anything and we don't have to.
> If users are bothered by guests getting IPs not assigned to them, they
> can move the global entries into the `pve-<zone>` VRF or sub-section,
> where they'll be picked up correctly.
> 
> [1] https://lore.proxmox.com/pve-devel/20261021084445.462195-1-h.laimer@proxmox.com/
> 
> 
> pve-network:
> 
> Hannes Laimer (9):
>   sdn: ipam: stop caching IPAM misses
>   sdn: ipam: write the lookup's cache entry under the cluster lock
>   sdn: ipam: read the MAC cache case-insensitively
>   sdn: dhcp: replace a stale dnsmasq reservation instead of dropping it
>   sdn: ipam: release an address the built-in IPAM no longer holds
>   sdn: dhcp: update reservations when ip mappings change
>   sdn: ipam: look a MAC up within the vnet's subnets
>   sdn: ipam: keep the MAC cache per vnet
>   sdn: ipam: give each zone a VRF in NetBox and a section in phpIPAM
> 
>  src/PVE/API2/Network/SDN/Ips.pm               |  33 +-
>  src/PVE/Network/SDN/Dhcp.pm                   |  56 +-
>  src/PVE/Network/SDN/Dhcp/Dnsmasq.pm           | 137 +++--
>  src/PVE/Network/SDN/Dhcp/Plugin.pm            |   6 +-
>  src/PVE/Network/SDN/Ipams.pm                  | 108 +++-
>  src/PVE/Network/SDN/Ipams/NetboxPlugin.pm     | 198 +++++--
>  src/PVE/Network/SDN/Ipams/PVEPlugin.pm        |  27 +-
>  src/PVE/Network/SDN/Ipams/PhpIpamPlugin.pm    | 181 +++++--
>  src/PVE/Network/SDN/Ipams/Plugin.pm           |   7 +-
>  src/PVE/Network/SDN/Subnets.pm                |  11 +-
>  src/PVE/Network/SDN/Vnets.pm                  |  16 +-
>  src/test/ipams/netbox/expected.add_ip         |   2 +-
>  .../ipams/netbox/expected.add_ip_notgateway   |   2 +-
>  src/test/ipams/netbox/expected.add_subnet     |   2 +-
>  src/test/ipams/netbox/expected.update_ip      |   2 +-
>  src/test/run_test_ipams.pl                    | 258 ++++++++++
>  src/test/run_test_vnets_blackbox.pl           | 487 +++++++++++++++++-
>  17 files changed, 1327 insertions(+), 206 deletions(-)
> 
> 
> pve-docs:
> 
> Hannes Laimer (1):
>   sdn: ipam: document the per-zone VRF and section in NetBox and phpIPAM
> 
>  pvesdn.adoc | 15 +++++++++++++++
>  1 file changed, 15 insertions(+)
> 
> 
> Summary over all repositories:
>   18 files changed, 1342 insertions(+), 206 deletions(-)
>