[pve-devel] [PATCH v2 pve-docs 2/2] sdn : add subnet/ipam documentation

[Alexandre Derumier]

Signed-off-by: Alexandre Derumier <aderumier at odiso.com>
---
 pvesdn.adoc | 129 ++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 120 insertions(+), 9 deletions(-)

diff --git a/pvesdn.adoc b/pvesdn.adoc
index ed8652d..4b17bff 100644
--- a/pvesdn.adoc
+++ b/pvesdn.adoc
@@ -64,6 +64,11 @@ On the web-interface  SDN feature have 4 main sections for the configuration
 
 * Controller: For complex setups to control Layer 3 routing
 
+* Subnets: Used to defined ip networks on Vnets.
+
+* Ipams: Allow to use external tools for ip managements (vm/ct ips)
+
+* Dns: Allow to define a dns server api for register vm/ct  hostname/ip addresses
 
 [[pvesdn_config_main_sdn]]
 SDN
@@ -117,13 +122,6 @@ VNet properties are:
 * VLAN Aware: Allow to add an extra VLAN tag in the virtual machine or
   container vNIC configurations or allow the guest OS to manage the VLAN's tag.
 
-* IPv4: an anycast IPv4 address, it will be configured on the underlying bridge
-  on each node part of the Zone. It's only useful for `bgp-evpn` routing.
-
-* IPv6: an anycast IPv6 address, it will be configured on the underlying bridge
-  on each node part of the Zone. It's only useful for `bgp-evpn` routing.
-
-
 [[pvesdn_config_controllers]]
 Controllers
 ~~~~~~~~~~~
@@ -149,8 +147,7 @@ Simple Zones
 This is the simplest plugin, it will create an isolated vnet bridge.
 This bridge is not linked to physical interfaces, VM traffic is only
 local to the node(s).
-It can be used for NAT or routed setup.
-
+It can be also used for NAT or routed setup.
 
 [[pvesdn_zone_plugin_vlan]]
 VLAN Zones
@@ -269,6 +266,120 @@ gateway, but, for example, sent traffic to external BGP routers, which handle
 (reverse) routing then dynamically you can use. For example
 `192.168.0.253,192.168.0.254'
 
+[[pvesdn_config_subnet]]
+Subnets
+~~~~~~~
+
+A Subnet allow to define an ip network (ipv4 or ipv6).
+
+It can be used to restrict ip addresses you can define on a specific vnet,
+assign routes/gateway on vnet in layer3 zones,
+enable snat on vnet in layer 3 zones,
+auto assign ips on vm/ct through ipam plugin && dns registration through dns plugins.
+
+
+Subnet properties are:
+
+* ID: a cidr network address. Ex: 10.0.0.0/8
+
+* Vnet: an associated vnet
+
+* Gateway: ip address for the default gateway of the network. 
+           On layer3 zones (simple/evpn plugins), it'll be deployed on the vnet.
+           
+* Snat: Optional, Enable Snat for layer3 zones (simple/evpn plugins) for this subnet.
+        The subnet source ip will be natted to server outgoing interface/ip.
+        On evpn zone, it's done only on evpn gateway-nodes.
+
+* Ipam: Optional, if you want to use an ipam tool for this subnet.
+        The subnet will be auto created in the ipam tool.
+
+* Dns: Optional, dns api server for forward zone.
+
+* Dnszone: Optional, dns domain name. Use to register hostname like  <hostname>.<domain>
+           The dns zone need to be already existing in dns server.
+
+* Dnszoneprefix: Optional, add a prefix to domain, like <hostname>.prefix.<domain>
+
+* ReverseDns: Optional, reverse dns api server for reverse zone.
+
+* ReverseDnsZone: Optional, reverse dns domaine name. ex: 0.168.192.in-addr.arpa
+                  The dns reverse zone need to be already existing in dns server.
+
+
+[[pvesdn_config_ipam]]
+Ipams
+~~~~~
+IPAM (IP address management) tools, are used to manage/assign ips on your devices on the network.
+It can be used to find free ip address when you create a vm/ct for example (not yet implemented).
+
+
+[[pvesdn_ipam_plugins]]
+Ipam Plugins
+------------
+
+[[pvesdn_ipam_plugin_pveipam]]
+PVEIpam plugin
+~~~~~~~~~~~~~~
+
+This is an internal ipam for your proxmox cluster if you don't have external ipam software
+
+
+PVEIpam properties are:
+
+* nothing, simply define and ID.
+
+[[pvesdn_ipam_plugin_phpipam]]
+PHPIpam plugin
+~~~~~~~~~~~~~~
+https://phpipam.net/
+
+You need to create an application in phpipam, and add an api token with admin permission
+
+PHPipam properties are:
+
+* Url: The rest api url : http://phpipam.domain.com/api/<appname>/
+* Token: your api token
+* Section: An integer id. Sections are group of subnets in phpipam. 
+           Default install have sectionid=1 for customers
+
+[[pvesdn_ipam_plugin_netbox]]
+Netbox Ipam plugin
+~~~~~~~~~~~~~~~~~~
+https://github.com/netbox-community/netbox
+
+you need to create an api token in netbox
+https://netbox.readthedocs.io/en/stable/api/authentication
+
+PHPipam properties are:
+
+* Url: The rest api url: http://yournetbox.domain.com/api
+* Token: your api token
+
+[[pvesdn_config_dns]]
+Dns
+~~~
+Dns is used to define a dns api server for registration of your hostname/ip address
+
+[[pvesdn_dns_plugin_powerdns]]
+Powerdns plugin
+~~~~~~~~~~~~~~~
+https://doc.powerdns.com/authoritative/http-api/index.html
+
+you need to enable webserver && api in your powerdns config:
+
+----
+api=yes
+api-key=arandomgeneratedstring
+webserver=yes
+webserver-port=8081
+----
+
+Powerdns properties are:
+
+* Url: The rest api url: http://yourpowerdnserver.domain.com:8081/api/v1/servers/localhost
+* key: the api key
+* ttl: default ttl for records
 
 [[pvesdn_local_deployment_monitoring]]
 Local Deployment Monitoring
-- 
2.20.1