Skip to content

CLAUDE.md

Latest commit

 

History

History
105 lines (64 loc) · 5.46 KB

CLAUDE.md

File metadata and controls

105 lines (64 loc) · 5.46 KB
Raw

Felix Operational Guide

This file is operational guidance for agents working in Felix: how to build, run tests, debug, and use Felix-specific tooling.

For architecture, invariants, and review criteria, see felix/DESIGN.md — the design index — and the per-topic sub-designs under felix/design/. Do not look here for invariants; look there.

Running Tests

Unit Tests

make ut

Runs all Go unit tests (via Ginkgo with coverage). Skips fv/, k8sfv/, and bpf/ut/ packages. Pass GINKGO_ARGS for extra flags (e.g., GINKGO_ARGS="-focus=TestName").

Prefer vanilla go test for new packages. Only reach for Ginkgo where an established pattern already exists.

Felix's "brain" is the calculation graph in calc/. Changes there require calc graph "FV" tests in calc/calc_graph_fv_test.go.

Functional Tests

make fv GINKGO_FOCUS="TestName"

Runs functional tests from fv/, using Ginkgo v2. make fv builds everything it needs first, and detects which images are already fresh so it does not rebuild them. GINKGO_FOCUS filters by test name (supports regex). Can be parallelized with FV_NUM_BATCHES and FV_BATCHES_TO_RUN; the race detector is on by default on amd64/arm64 (FV_RACE_DETECTOR_ENABLED).

fv-no-prereqs skips that build step. It exists for CI, which builds separately and wants no accidental rebuilds — don't use it locally.

A test's ID is the concatenation of all its nested Context/Describe headings, so GINKGO_FOCUS can match on any enclosing heading. Other useful flags: -ginkgo.dryRun (list tests without running them), -ginkgo.v (verbose), and FV_FELIX_LOG_LEVEL=debug.

BPF-Specific Tests

Where the BPF code lives

  • bpf-gpl/ — eBPF programs, GPL v2.0/Apache dual licensed for Linux kernel compatibility.
  • bpf-apache/ — Apache-licensed BPF code.
  • make clone-libbpf — run before your first BPF build; fetches libbpf.
  • BPF tooling versions (LIBBPF_VERSION, BPFTOOL_IMAGE) are pinned in metadata.mk.

Building BPF Programs

After modifying C code in bpf-gpl/, verify it compiles for all targets (IPv4, IPv6, all hook types):

make build-bpf

Run make clean first if you hit stale object issues. Use make -C felix build to verify both BPF C and Go code compile together.

BPF Unit Tests

BPF unit tests run the BPF dataplane programs in a privileged container:

make ut-bpf                          # Run all BPF unit tests (~2000 tests)
make FOCUS="TestName" ut-bpf         # Run specific test by name
make FOCUS="TestNatEncap" ut-bpf     # Example: VXLAN encap/decap tests
make FOCUS="TestNATPodPodXNode" ut-bpf  # Example: cross-node NAT tests

FOCUS filters by Go test function name (supports regex). Each test function typically has multiple sub-tests exercising different BPF programs (ingress/egress, different interface types).

TestPrecompiledBinariesAreLoadable verifies that all compiled BPF programs pass the kernel verifier on the local machine. Always run this after modifying BPF C code to catch verifier rejections early:

make FOCUS="TestPrecompiledBinariesAreLoadable" ut-bpf

BPF functional tests run the standard FV suite with the BPF dataplane enabled:

make fv-bpf GINKGO_FOCUS="TestName"

fv/bpf_*_test.go tests carry a matrix prefix (e.g. "ipv4 udp, ct=true, log=debug, tunnel=none, dsr=false") which GINKGO_FOCUS can regex-match to slice the matrix when triaging. The matrix axes, the _BPF-SAFE_ convention for shared FV tests, and the harness conventions for bpf/ut/ are documented in design/bpf-tests.md.

Nftables Functional Tests

make fv-nft GINKGO_FOCUS="TestName"

Runs FV tests with the nftables backend enabled (FELIX_FV_NFTABLES=Enabled).

Diagnosing Test Failures with fv-tests-guru

fv-tests-guru is an AI-powered tool that parses Felix FV/UT failure logs and runs AI analysis to diagnose root causes. It reads its Gemini API key from ~/.fv-tests-guru/gemini-key.

When asked to analyze a test failure log file, always run fv-tests-guru FIRST (if available — check with which fv-tests-guru) — it is the most efficient way to identify the failing test(s), extract relevant context, and get an initial diagnosis. Use its output to guide subsequent investigation (reading test code, checking source changes, etc.). If fv-tests-guru is not installed, skip it and proceed with manual analysis.

fv-tests-guru -debug-logfile <log-path> -ai-provider gemini -calico-repo <path-to-calico-repo-root> -max-timeout 1m40s

Add -ut for unit test logs. Use -extra-context "..." to provide hints about the branch under test.

Configuration parameters

Felix parameters are declared in config/config_params.go with types and validation in config/param_types.go. When adding a new parameter, both files are updated; the docs under felix/docs/config-params.md are regenerated by make generate.

Design and review criteria

Architecture, invariants, and review criteria live in the design index felix/DESIGN.md and the per-topic sub-designs under felix/design/. Path-scoped Copilot rules that reference each sub-design live under .github/instructions/. Do not look here for dataplane invariants, calc-graph internals, or rule-generation rules — look in the matching sub-design.