[PATCH pve-docs 14/16] sdn: add microsegmentation section

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

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

diff --git a/pvesdn.adoc b/pvesdn.adoc
index a09a443..09ec087 100644
--- a/pvesdn.adoc
+++ b/pvesdn.adoc
@@ -443,6 +443,83 @@ DNS Zone Prefix:: Add a prefix to the domain registration, like
   <hostname>.prefix.<domain>  Optional.
 
 
+[[pvesdn_config_microseg]]
+Microsegmentation
+-----------------
+
+Microsegmentation enforces an allow/deny policy between groups of guests at the
+guest network interface, independent of IP addressing. Each interface can be
+assigned to a *group*, and *rules* between groups decide which traffic is
+allowed. Enforcement happens in the kernel via eBPF programs attached to the
+guest interfaces, on the receiving side.
+
+The default is deny: without a matching rule, traffic between groups is
+dropped, so every allowed flow needs an explicit rule.
+
+To carry the group identity between nodes, the underlying VXLAN must have Group
+Based Policy enabled via the `VXLAN-GBP` option on the zone (see
+xref:pvesdn_zone_plugin_vxlan[VXLAN Zones] and
+xref:pvesdn_zone_plugin_evpn[EVPN Zones]). Traffic that stays on a single
+node needs no extra configuration. A guest cannot forge its own group, as the
+host stamps it at the interface; the underlay is trusted, much like a VLAN tag.
+
+[[pvesdn_microseg_group]]
+Groups
+~~~~~~
+
+A group is a label applied to one or more guest interfaces. Groups can be
+nested: a group may have a single parent, and a rule on a group also applies to
+every group below it. When several rules match, the most specific one wins -
+the rule naming the destination group closest in the tree, then the source
+group.
+
+Group configuration options:
+
+Name:: An identifier for the group.
+
+Mark:: A unique numeric tag from 1 to 65535, carried on the wire to identify the
+  group.
+
+Parent:: Optional parent group, whose rules this group inherits and can refine.
+
+Comment:: Optional descriptive comment.
+
+[[pvesdn_microseg_rule]]
+Rules
+~~~~~
+
+A rule maps a `(source group, destination group)` pair to *allow* or *deny*. As
+the default is deny, rules are only needed to permit traffic, or to deny a flow
+within a broader allow inherited from a parent. Traffic within a single group is
+not permitted implicitly; add an explicit rule from a group to itself for that.
+
+Rule configuration options:
+
+Source group:: Where the traffic comes from. Leave empty to match unstamped
+  traffic, that is, traffic from interfaces not in any group.
+
+Destination group:: Where the traffic is destined.
+
+Action:: Allow or deny.
+
+NOTE: An interface with a group assigned drops unstamped traffic unless a rule
+with an empty source for that group explicitly allows it.
+
+[[pvesdn_microseg_assignment]]
+Assignments
+~~~~~~~~~~~
+
+An assignment places a specific guest network interface into a group. Each
+interface can belong to at most one group.
+
+Assignment configuration options:
+
+Guest:: The VM or container.
+
+Network interface:: The interface of that guest to place in the group.
+
+Group:: The group to assign it to.
+
 [[pvesdn_config_controllers]]
 Controllers
 -----------
-- 
2.47.3