[pve-devel] [PATCH v2 pve-docs 1/6] sdn: installation, overview and main configuration

[Stefan Lendl]

refs only work with subsequent patches

Signed-off-by: Stefan Lendl <s.lendl at proxmox.com>
---
 pvesdn.adoc | 67 +++++++++++++++++++++++++++++------------------------
 1 file changed, 37 insertions(+), 30 deletions(-)

diff --git a/pvesdn.adoc b/pvesdn.adoc
index b796c5e..562e081 100644
--- a/pvesdn.adoc
+++ b/pvesdn.adoc
@@ -15,18 +15,16 @@ xref:getting_help[mailing lists or in the forum] for questions and feedback.
 
 [[pvesdn_installation]]
 Installation
-------------
+-------------
 
 To enable the experimental Software-Defined Network (SDN) integration, you need
-to install the `libpve-network-perl` and `ifupdown2` packages on every node:
+to install the `libpve-network-perl` package on every node:
 
 ----
 apt update
-apt install libpve-network-perl ifupdown2
+apt install libpve-network-perl
 ----
 
-NOTE: {pve} version 7 and above come installed with ifupdown2.
-
 After this, you need to add the following line to the end of the
 `/etc/network/interfaces` configuration file, so that the SDN configuration gets
 included and activated.
@@ -36,47 +34,56 @@ source /etc/network/interfaces.d/*
 ----
 
 
-Basic Overview
---------------
+[[pvesdn_overview]]
+Overview
+-------------
 
 The {pve} SDN allows for separation and fine-grained control of virtual guest
 networks, using flexible, software-controlled configurations.
 
-Separation is managed through zones, where a zone is its own virtual separated
-network area. A 'VNet' is a type of a virtual network connected to a zone.
-Depending on which type or plugin the zone uses, it can behave differently and
-offer different features, advantages, and disadvantages. Normally, a 'VNet'
-appears as a common Linux bridge with either a VLAN or 'VXLAN' tag, however,
-some can also use layer 3 routing for control. 'VNets' are deployed locally on
-each node, after being configured from the cluster-wide datacenter SDN
-administration interface.
+Separation is managed through *zones*, virtual networks (*VNets*), and
+*subnets*.  A zone is its own virtually separated network area.  A VNet is a
+virtual network that belongs to a zone. A subnet is an IP range inside a VNet.
 
+Depending on the type of the zone, the network behaves differently and offers
+specific features, advantages, and limitations.
 
-Main Configuration
-~~~~~~~~~~~~~~~~~~
+Use cases for SDN range from an isolated private network on each individual node
+to complex overlay networks across multiple PVE clusters on different locations.
 
-Configuration is done at the datacenter (cluster-wide) level and is saved in
-files located in the shared configuration file system:
-`/etc/pve/sdn`
+After configuring an VNet in the cluster-wide datacenter SDN administration
+interface, it is available as a common Linux bridge, locally on each node, to be
+assigned to VMs and Containers.
+
+
+[[pvesdn_main_configuration]]
+Main Configuration
+-------------
 
-On the web-interface, SDN features 3 main sections:
+Configuration is done at the web UI at datacenter level and is saved in files
+located in the shared configuration file system at `/etc/pve/sdn`.
 
-* SDN: An overview of the SDN state
+On the web interface, SDN features the following sections:
 
-* Zones: Create and manage the virtually separated network zones
+* xref:pvesdn_config_main_sdn[SDN]:: An overview of the SDN state
 
-* VNets: Create virtual network bridges and manage subnets
+* xref:pvesdn_config_zone[Zones]: Create and manage the virtually separated
+  network zones
 
-In addition to this, the following options are offered:
+* xref:pvesdn_config_vnets[VNets] VNets: Create virtual network bridges and
+  manage subnets
 
-* Controller: For controlling layer 3 routing in complex setups
+The Options category allows adding and managing additional services to be used
+in your SDN setup.
 
-* Subnets: Used to defined IP networks on VNets
+* xref:pvesdn_config_controllers[Controllers]: For controlling layer 3 routing
+  in complex setups
 
-* IPAM: Enables the use of external tools for IP address management (guest
-  IPs)
+* xref:pvesdn_config_ipam[IPAM]: Enables external for IP address management for
+  guests
 
-* DNS: Define a DNS server API for registering virtual guests' hostname and IP
+* xref:pvesdn_config_dns[DNS]: Define a DNS server integration for registering
+  virtual guests' hostname and IP
   addresses
 
 [[pvesdn_config_main_sdn]]
-- 
2.42.0