[PATCH pve-docs v4 13/13] sdn: ipam: document zone namespaces in NetBox and phpIPAM

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

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

diff --git a/pvesdn.adoc b/pvesdn.adoc
index c85d86a48112..0cd1b938528d 100644
--- a/pvesdn.adoc
+++ b/pvesdn.adoc
@@ -1287,6 +1287,22 @@ 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. 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 `pve-<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 +1320,23 @@ 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. phpIPAM nests sections one level deep, so a configured section
+that is itself a sub-section gets no sub-sections and the subnets of all zones
+stay in it. 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 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