[PATCH pve-docs v6 13/13] sdn: ipam: document zone namespaces and the mapping edit

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

Signed-off-by: Hannes Laimer <h.laimer@proxmox.com>
---
 pvesdn.adoc | 44 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 43 insertions(+), 1 deletion(-)

diff --git a/pvesdn.adoc b/pvesdn.adoc
index c85d86a48112..407986901ff2 100644
--- a/pvesdn.adoc
+++ b/pvesdn.adoc
@@ -1265,7 +1265,9 @@ If you are using DHCP, you can use the IPAM panel to create or edit leases for
 specific VMs, which enables you to change the IPs allocated via DHCP. When
 editing an IP of a VM that is using DHCP you must make sure to force the guest
 to acquire a new DHCP leases. This can usually be done by reloading the network
-stack of the guest or rebooting it.
+stack of the guest or rebooting it. The edit updates the DHCP reservation on the
+node of the guest right away. It is refused while the guest is being migrated,
+repeat it once the migration is done.
 
 [[pvesdn_ipam_plugin_netbox]]
 NetBox IPAM Plugin
@@ -1287,6 +1289,25 @@ Fingerprint:: The SHA-256 fingerprint of the NetBox API. Can be retrieved with
   `openssl x509 -in /etc/ssl/certs/netbox.crt -noout -fingerprint -sha256` when
   using the default certificate.
 
+With the `zone-namespaces` option of the IPAM entry turned on, {pve} creates a
+VRF named `pve-<zone>` for every zone, together with the first subnet of the
+zone, and keeps the prefixes of the zone's subnets in it. This way two zones can
+use the same subnet. The option is off by default and meant to be turned on once
+every node runs a version that knows the VRFs, since a node that does not puts
+an explicit mapping into the global table. With it off the prefixes are looked
+up without regard to their VRF, as before, so the option stays on once two zones
+share a range. Clusters sharing one NetBox set a `zone-namespace-prefix` of
+their own, the names start with `pve` by default. The IP addresses allocated in
+a prefix carry the MAC address of the guest in their description. Prefixes
+created in the global table, by earlier versions or with the option off, are
+still found there and can be moved into the VRF of their zone, together with
+their IP addresses and IP ranges. A zone gets its VRF only with the next subnet
+added to it, so to move prefixes into it earlier, create the VRF
+`<zone-namespace-prefix>-<zone>` by hand. With the option on, creating a subnet
+whose range the global table still holds is refused, since a prefix in the VRF
+would hide the addresses recorded in the old one, so move or remove that prefix
+first.
+
 
 [[pvesdn_ipam_plugin_phpipam]]
 phpIPAM Plugin
@@ -1304,6 +1325,27 @@ Token:: An API access token
 Section:: An integer ID. Sections are a group of subnets in phpIPAM. Default
   installations use `sectionid=1` for customers.
 
+With the `zone-namespaces` option of the IPAM entry turned on, {pve} creates a
+sub-section named `pve-<zone>` under the configured section for every zone,
+together with the first subnet of the zone, and keeps the zone's subnets in it.
+This way two zones can use the same subnet. The option is off by default and
+meant to be turned on once every node runs a version that knows the
+sub-sections. With it off the subnets are looked up in any section, as before,
+so the option stays on once two zones share a range. phpIPAM nests sections one
+level deep, so the option is refused for a configured section that is itself a
+sub-section. Configure its parent instead. The subnets in the old section have
+to move as well, into the parent or into the sub-sections of their zones, the
+lookup searches only these. Section names are global in phpIPAM, so clusters
+sharing one set a `zone-namespace-prefix` of their own, the names start with
+`pve` by default. Subnets created in the configured section itself, by earlier
+versions or with the option off, are still found there and can be moved into the
+sub-section of their zone. A zone gets its sub-section only with the next subnet
+added to it, so to move subnets into it earlier, create the sub-section
+`<zone-namespace-prefix>-<zone>` under the configured section by hand. With the
+option on, creating a subnet whose range the configured section still holds is
+refused, since a copy in the sub-section would hide the addresses recorded in
+the old one, so move or remove that subnet first.
+
 
 [[pvesdn_config_dns]]
 DNS
-- 
2.47.3