From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [IPv6:2a0f:8001:1:32::40]) by lore.proxmox.com (Postfix) with ESMTPS id 88B241FF0E0 for ; Thu, 09 Jul 2026 11:23:27 +0200 (CEST) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id D30792182B; Thu, 09 Jul 2026 11:20:09 +0200 (CEST) From: Hannes Laimer To: pve-devel@lists.proxmox.com Subject: [PATCH pve-docs v2 26/27] sdn: add microsegmentation section Date: Thu, 9 Jul 2026 11:18:51 +0200 Message-ID: <20260709091852.538885-27-h.laimer@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260709091852.538885-1-h.laimer@proxmox.com> References: <20260709091852.538885-1-h.laimer@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1783588755414 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.277 Adjusted score from AWL reputation of From: address DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment (newer systems) SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: 3B3PIKRDT5H56XKPQMBD5TXAZWVCZBNG X-Message-ID-Hash: 3B3PIKRDT5H56XKPQMBD5TXAZWVCZBNG X-MailFrom: h.laimer@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: Signed-off-by: Hannes Laimer --- 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 .prefix. 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