Add eBPF dataplane design & review guide (felix/bpf/DESIGN.md)

.github/copilot-instructions.md

@@ -242,5 +242,13 @@ make image                   # Build all images (slow)
 
 Every PR needs one docs label (`docs-pr-required`, `docs-completed`, or `docs-not-required`) and one release note label (`release-note-required` or `release-note-not-required`). Optional: `cherry-pick-candidate` (bug fix backports), `needs-operator-pr` (requires operator change).
 
+## eBPF Dataplane Review
+
+Changes that touch the eBPF dataplane have their own design and review guide: [`felix/bpf/DESIGN.md`](../felix/bpf/DESIGN.md). It describes the packet path, TC program layout, service NAT, Maglev, CTLB, the bpfnat workaround, VXLAN flow-mode device, RPF, conntrack cleanup, IP fragmentation, ICMP error generation, `*tables`→BPF migration, third-party DNAT interop, log filters, flow logs, QoS, fast-path cost discipline, and cross-cutting review rules. Each section has a **Review notes** block listing the invariants a PR in that area must respect — cross-check it when reviewing BPF changes.
+
+Path-specific reviewer rules for BPF files live in [`.github/instructions/ebpf-dataplane.instructions.md`](instructions/ebpf-dataplane.instructions.md) and apply automatically to files under `felix/bpf-gpl/`, `felix/bpf/`, `felix/dataplane/linux/bpf_*.go`, and `felix/dataplane/linux/vxlan_mgr.go`.
+
+**Update rule.** A BPF dataplane PR that changes how the dataplane works (new sub-program, new CT flag, new mark bit, new map or map field, new config knob affecting any of those, or any change to the packet path or forwarding decision) must update `felix/bpf/DESIGN.md` in the same PR. Exemptions: (a) a bug fix that restores behaviour `DESIGN.md` already describes, (b) a mechanical refactor with no observable change, (c) comment / log-message edits, (d) dependency bumps. If in doubt, update the doc.
+
 ### Trust These Instructions
 These instructions are based on actual testing of the build system. Only search for additional information if you encounter specific errors not covered here or if the repository structure has changed significantly.

.github/instructions/ebpf-dataplane.instructions.md

@@ -0,0 +1,106 @@
+---
+applyTo:
+  - "felix/bpf-gpl/**"
+  - "felix/bpf/**"
+  - "felix/dataplane/linux/bpf_*.go"
+  - "felix/dataplane/linux/vxlan_mgr.go"
+  - "felix/bpf/DESIGN.md"
+---
+
+# eBPF dataplane review instructions
+
+The authoritative design and review guide for Calico's eBPF dataplane
+is [`felix/bpf/DESIGN.md`](../../felix/bpf/DESIGN.md). Each of its
+topic sections ends with a **Review notes** block listing the
+invariants a change in that area must respect. When reviewing a
+change that touches a file matching this instruction's `applyTo`,
+cross-check the relevant section(s) of `DESIGN.md` — the doc is the
+source of truth for dataplane principles; this file is a short
+pointer.
+
+## Must-check principles
+
+- **Per-packet cost (§22).** For every BPF dataplane change,
+  answer explicitly: *does this cause more packets to do more
+  work?* The obvious case is new code on the fast path. The
+  non-obvious case is a change that **shrinks the set of packets
+  eligible for an existing fast-path shortcut** — work that
+  already existed is now paid by more flows. Both need the same
+  justification: a benchmark, a scoping mechanism that restores
+  the shortcut in steady state, or an argument that the affected
+  flow class is small. If the answer to the question is "yes" and
+  the PR description doesn't address it, that's a finding. See
+  §22 for cost tiers and patterns to prefer (CT flags, skb marks,
+  compile-time gates, slow-path sub-programs).
+- **Map versioning (§23).** Bump `MapParameters.Version` only when
+  the change makes new BPF programs incompatible with the old
+  pinned map. Repurposing padding / reserved bytes does not need
+  a bump. Moving fields, widening keys, shrinking values, or
+  depending on a field old programs write as zero does.
+- **New BPF sub-programs.** Must be registered in
+  `felix/bpf-gpl/jump.h` (`enum cali_jump_index`, with matching
+  `_DEBUG` variant), in `felix/bpf/hook/map.go`
+  (`SubProg*` constant + entry in `tcSubProgNames` /
+  `xdpSubProgNames`), and filtered by `GetApplicableSubProgs`
+  if they aren't needed for every attach type.
+- **skb marks.** New signals between BPF and `*tables` use bits in
+  `0x1FF00000` (`enum calico_skb_mark` in
+  `felix/bpf-gpl/bpf.h`). Matching `*tables` rule-generator
+  updates under `felix/rules/` are required when the signal
+  crosses the boundary.
+- **CT flags are preferred over main-path lookups.** When a check
+  produces a per-flow result, encode it as a `CALI_CT_FLAG_*` at
+  flow creation; the fast path reads the flag, not a map.
+- **Attach-gap.** Any change that lets BPF forward a packet that
+  used to go through `*tables` must consult `fib_approve` (or an
+  equivalent check against the `cali_iface` readiness flag) for
+  the target interface.
+- **Cross-section invariants.** RPF (§12), mid-flow fallthrough
+  (§16), SkipFIB for third-party DNAT (§17), bpfnat RPF sysctls
+  (§10), VXLAN flow-mode device (§11), and fast-path discipline
+  (§22) all have explicit rules in their Review notes sections.
+  If the change touches any of those areas, read the relevant
+  Review notes.
+
+## The update rule
+
+A BPF dataplane PR that **changes how the dataplane works** must
+update `felix/bpf/DESIGN.md` in the same PR. This includes:
+
+- A new BPF sub-program or tail-call target.
+- A new CT flag or reuse of an existing one for a new purpose.
+- A new skb-mark bit or a changed meaning.
+- A new BPF map, new map field, or a layout change.
+- A new config knob that affects any of the above.
+- Any change to the packet path, forwarding decision, or
+  fast-path/slow-path split.
+
+**Exemption.** No `DESIGN.md` update is needed if the PR is
+exclusively one of:
+
+- (a) A bug fix that restores behaviour `DESIGN.md` already
+  describes.
+- (b) A mechanical refactor with no observable change.
+- (c) Comment / log-message edits.
+- (d) Dependency bumps.
+
+If in doubt, update the doc. A PR that modifies the BPF dataplane
+without a `DESIGN.md` update and without falling into one of the
+four exemptions is incomplete.
+
+**Amending the PR.** The Copilot automated code-review step is
+read-only with respect to the PR branch — it cannot push the
+`DESIGN.md` amendment itself. When the review flags a missing
+update per the rule above, its comment should include a
+ready-to-paste `@copilot` prompt that specifies which section
+needs updating and what new invariant or mechanic to cover, for
+example:
+
+> `@copilot update felix/bpf/DESIGN.md §13 to cover the new CT flag CALI_CT_FLAG_FOO — the fields it uses, where it is set, how it interacts with the fast path.`
+
+The reviewer (or the PR author) drops that into a new PR comment
+to invoke the Copilot coding agent, which pushes a commit with
+the amendment to the PR branch. Pre-formatting the invocation in
+the review comment is the path of least resistance; without it
+the reviewer has to draft the prompt themselves and the doc
+drift typically ends up in a follow-up PR.

felix/CLAUDE.md

@@ -253,6 +253,18 @@ Typically, back-to-back sub-tests simulate a packet traversing from one interfac
 
 `dataplane/linux/bpf_*.go` — manages the BPF dataplane from user space (program lifecycle, map syncing, endpoint management).
 
+### eBPF Dataplane Design & Review Guide
+
+`felix/bpf/DESIGN.md` is the authoritative design and review guide for the eBPF dataplane. It covers the packet path, TC program layout (preamble + jump maps + fast/debug paths), XDP→TC handoff, intra-cluster & external service NAT, Maglev, session affinity, the BPF kube-proxy replacement, CTLB, the bpfnat workaround, VXLAN flow-mode, RPF, conntrack cleanup, IP fragmentation, BPF-synthesised ICMP errors, `*tables`→BPF migration, third-party DNAT interop, log filters, flow logs, QoS, the fast-path cost discipline, and cross-cutting review rules. Each section ends with a **Review notes** block listing the invariants a PR in that area must respect.
+
+**When reviewing a BPF dataplane change with `/review` or the `review` skill,** read the relevant DESIGN.md section(s) before forming an opinion and use the Review notes there as the checklist. Path-specific Copilot rules mirror the same checks and live in `.github/instructions/ebpf-dataplane.instructions.md`.
+
+Before signing off on any BPF dataplane PR, answer §22's question in plain prose: *does this change the per-packet cost for any class of flows?* This includes changes that don't add new fast-path code but route more flows through existing slow-path work — e.g., a CT flag whose effect is to suppress a fast-path return code, or a condition that gates the policy program on a wider set of packets. If the per-packet cost changes for any class of flows and the PR doesn't address it, the review must flag it.
+
+**Update rule.** A BPF dataplane PR that changes how the dataplane works — new sub-program, new CT flag, new mark bit, new map or map field, new config knob affecting any of those, or any change to the packet path or forwarding decision — must update `felix/bpf/DESIGN.md` in the same PR. Exemptions: (a) a bug fix that restores behaviour `DESIGN.md` already describes, (b) a mechanical refactor with no observable change, (c) comment / log-message edits, (d) dependency bumps. If in doubt, update the doc.
+
+**When `/review` finds a BPF dataplane PR that meets the update rule above but has no `DESIGN.md` change:** propose the update as a concrete diff in the review output — name the section, the invariant or mechanic being added, and the exact wording. If the reviewer confirms, write the amendment to `felix/bpf/DESIGN.md` and push it as an additional commit on the PR branch rather than leaving the doc drift to a follow-up PR. `/review` already has `gh` and push access when run locally; use them. The trust level is the same as making a code suggestion in review — this is just writing documentation prose for a well-defined gap.
+
 ## Iptables/Nftables Dataplane
 
 The netfilter-based policy engine uses a layered architecture: