[PATCH pve-docs v2 26/27] sdn: add microsegmentation section

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

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

diff --git a/pvesdn.adoc b/pvesdn.adoc
index 3fd3533..bb8a36e 100644
--- a/pvesdn.adoc
+++ b/pvesdn.adoc
@@ -443,6 +443,124 @@ 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 a set of *groups*, 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 on a VXLAN-based zone, 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]). An SRv6-based carrier for routed
+setups exists at the API level, without UI support yet. 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. An interface can
+carry several groups at once. Its memberships form a set, the union of every
+assignment that covers it. Rules do not target interfaces directly but match
+this set through their predicates, so combinations of groups (a guest that is
+both `prod` and `web`) can be addressed without defining a group for every
+combination.
+
+Group configuration options:
+
+Name:: An identifier for the group.
+
+Mark:: A unique number from 1 to 65535 identifying the group, auto-assigned if
+  omitted. What is carried on the wire is a compact identity derived from an
+  interface's whole group set, not the individual marks.
+
+Comment:: Optional descriptive comment.
+
+[[pvesdn_microseg_rule]]
+Rules
+~~~~~
+
+A rule permits or denies traffic between a *source* and a *destination*
+predicate, each evaluated against an interface's group set by a match kind. As
+the default is deny, rules are only needed to permit traffic (or to deny a flow
+within a broader allow). Traffic within a single group is not permitted
+implicitly, so add an explicit rule for it.
+
+Rules are stateless and directional. Each packet is checked on its own, the
+source predicate against the sender's groups and the destination predicate
+against the receiver's, with no connection tracking. Return traffic needs its
+own rule. For a TCP connection from `web` to `app`, both a `web` to `app` and
+an `app` to `web` allow are required.
+
+Rule configuration options:
+
+Source / Destination:: The groups each predicate is evaluated against.
+
+Source match / Destination match:: How the predicate matches an interface's
+  groups. *any* fires when the set shares at least one listed group, *all* when
+  it has all of them, and *exact* when the groups equal the listed set.
+
+Priority:: On a conflict the highest-priority matching rule wins. Conflicting
+  verdicts tied at the top priority deny.
+
+Action:: Allow or deny.
+
+A built-in *untagged* group represents the no-group identity, an interface in no
+group, an external host, or a cross-node frame that arrives without a GBP tag.
+List it in a predicate like any other group, on its own (`exact` over
+`untagged`) or combined with real groups (`any` over `untagged, web`), to admit
+such traffic. This is what lets a managed guest exchange ARP / DHCP and reach its
+gateway, which are themselves untagged and would otherwise be dropped. It is
+meaningful as a rule *source*. As a destination it has no effect, since an
+untagged interface has no program to enforce on. The `untagged` group cannot be
+used in an assignment.
+
+[[pvesdn_microseg_assignment]]
+Assignments
+~~~~~~~~~~~
+
+An assignment binds guest network interfaces to a set of groups. It matches a
+specific guest, guests by their tags, or guests whose name matches a regular
+expression. An interface may be placed in several groups (by one assignment
+listing multiple groups, or by several assignments).
+
+The *tag* and *name regex* matchers are dynamic. They are re-evaluated against
+the current guests whenever the SDN configuration is applied, so tagging or
+renaming a guest shows up as a pending SDN change and takes effect on the next
+apply (until then a newly matched guest is treated as it was at the last apply,
+i.e. fail-closed). Both match at the guest level, so unless a specific interface
+is named the assignment covers all of a matching guest's interfaces.
+
+Assignment configuration options:
+
+Match by:: Whether to match a specific *guest*, guests by *tags*, or guests by
+  a *name regex*.
+
+Guest:: (guest matcher) The VM or container.
+
+Tags:: (tag matcher) The guest tags to match.
+
+Tag match:: (tag matcher) Whether a guest must carry *any* of the listed tags
+  (the default), *all* of them, or have *exact*ly the listed set.
+
+Name regex:: (regex matcher) A regular expression matched against each guest's
+  name (VM name or container hostname). It matches anywhere in the name, so anchor
+  it with `^` and `$` to match the whole name.
+
+Network interface:: Optional. The guest's netN interface. If left empty, all of
+  the guest's interfaces are covered.
+
+Groups:: The groups the matching interfaces are placed into.
+
 [[pvesdn_config_controllers]]
 Controllers
 -----------
-- 
2.47.3