calico / felix

# 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`](./DESIGN.md) — the design index — and the per-topic sub-designs under [`felix/design/`](./design/). Do not look here for invariants; look there.

## Running Tests

### Unit Tests

```bash
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`](./calc/calc_graph_fv_test.go).

### Functional Tests

```bash
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

The BPF C programs live in `bpf-gpl/`; building them, checking headers and the
include conventions are covered in [`bpf-gpl/CLAUDE.md`](./bpf-gpl/CLAUDE.md).

#### BPF Unit Tests

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

```bash
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:

```bash
make FOCUS="TestPrecompiledBinariesAreLoadable" ut-bpf
```

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

```bash
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`](./design/bpf-tests.md).

**Name a new FV test that needs BPF mode `_BPF-SAFE_`, or `_BPF_ _BPF-SAFE_` if it targets the BPF dataplane.** CI's BPF jobs focus on `BPF-SAFE|_BPF_`, so either marker is enough to get the test run; a test with neither marker runs in no BPF job.

### Nftables Functional Tests

```bash
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](https://github.com/tigera/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.

```bash
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`](./DESIGN.md) and the per-topic sub-designs under [`felix/design/`](./design/). Path-scoped Copilot rules that reference each sub-design live under [`.github/instructions/`](../.github/instructions/). Do not look here for dataplane invariants, calc-graph internals, or rule-generation rules — look in the matching sub-design.

## AI-assisted contribution policy

Contributions written with AI assistance follow [`AI_POLICY.md`](../AI_POLICY.md): disclose the assistance in the PR description, no AI co-author trailers, and leave the change in a state the human author can explain themselves.

More agent context in projectcalico/calico

13 other files this repository gives its agents.