aws-network-policy-agent
AGENTS.md81 starsChanged 2 days agoApache-2.0View on GitHub
Guidance for coding agents and human contributors working in this repository. The AWS Network Policy Agent enforces Kubernetes NetworkPolicy and ClusterNetworkPolicy on EKS nodes with eBPF. It runs on each node as a container in the aws-node DaemonSet.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
The file
We split this AGENTS.md into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 34
Flags: Treat a new agent flag as a one-way door.
- Very specific: line 39
Logging: Use the package's log() helper.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
Guidance for coding agents and human contributors working in this repository.
What this is
The AWS Network Policy Agent enforces Kubernetes NetworkPolicy and ClusterNetworkPolicy on EKS nodes with eBPF. It runs on each node as a container in the aws-node DaemonSet.
main.go: agent entry point.controllers/: reconcilers for PolicyEndpoint and ClusterPolicyEndpoint objects.pkg/ebpf/: loads, attaches and recovers the BPF programs throughgithub.com/aws/aws-ebpf-sdk-go.pkg/ebpf/c/: the BPF C sources, four tc programs and two events programs, v4 and v6. The two ingress sources are also built with-DNPA_CT_SHORTEN_ON_DENYinto the ct-deny objects (code inct_deny.h), so the image ships six tc objects and two events objects, plustc.shared.bpf.o, which holds no programs, only node-wide maps the tc programs share (tc_shared.h). The agent picks the ct-deny or the regular ingress object once at startup.pkg/fwruleprocessor/: turns policy rules into BPF map entries.pkg/rpc/: the gRPC server the VPC CNI calls on pod add and delete.cmd/cli,cmd/cliv6: theaws-eks-na-clinode tools.test/: ginkgo integration suites and framework.
Build and test
make build-linux: builds the agent and both CLIs with the host Go toolchain (Go 1.26.9 or later, pergo.mod;.go-versionpicks the Go image for docker builds).make build-bpf: compiles the BPF objects with clang. It needspkg/ebpf/c/vmlinux.h, whichmake vmlinuxhgenerates on a Linux host withbpftool.make docker-buildbuilds the image, including the objects.make test: unit tests,go test ./pkg/... ./controllers/...with coverage.make docker-unit-testsruns them in the test container. For one package:go test ./pkg/ebpf/....make check-format(needsgoimports) andmake vet: the code checks CI runs.make build-test-binaries: builds everytest/integration/<suite>exceptsoakintotest/build/(needsginkgo). Suites run against a live cluster:make run-cyclonus-test CLUSTER_NAME=<name>runsscripts/run-cyclonus-tests.sh.
CI:
.github/workflows/pr-tests.yamlruns on pushes tomainand on PRs tomainandrelease*:check-format,vet,build-linuxandmake test. On PRs it also runsmake docker-buildx, a deprecated-apiGroups check andgovulncheck. Only the docker job compiles the C.- A PR comment
/test cyclonus <full-sha>from a user with write access runspr-cyclonus-tests.yaml: cyclonus plus thepolicy,ebpf,clusternetworkpolicy,agentflagsandstrictsuites, on IPv4 and IPv6 clusters. nightly-kernel-tests.yamlrunsscripts/run-kernel-smoke-tests.sh(policy,ebpf,agentflags, thenstrict) daily across AL2023 kernel lines, on IPv4 and IPv6. New eBPF tests belong in one of those suites.agentflagschanges the agent's args on aws-node, so in both scripts it runs late, after the suites that expect the stock agent and beforestrict.run_agent_flags_suiteinscripts/lib/tests.shsaves the args first and restores them after the suite, or on exit if the script stops mid-suite, so a killed run can't leave a flag on for the suites after it.restart,leak,upgradeandsoakare not run by any workflow. Verifier rejections show up only on a real kernel.
Hard rules
- v4/v6 parity. A datapath change goes into both families: the C programs (including the
NPA_CT_SHORTEN_ON_DENYblocks andct_deny.h), conntrack GC, event decoding, CLI and tests. Runpython3 -I hack/v4v6-diff.py --all .at the merge base and at the change; it diffs both ingress builds. The change should add no hunk unless it is family-specific by design. - SDK naming. The SDK splits pin names at the first
_. ALoadBpfFile*prefix must not contain_. Every per-pod map must be listed inutils.NamespacedBPFMaps, or it is treated as a global map. - Flags. Treat a new agent flag as a one-way door. Prefer no flag. For a test-only code path, use a test-only mechanism (for example a test binary or image under
test/), not a product flag. - BPF object bytes. An edit to a
pkg/ebpf/cfile that changes code or shifts line numbers changes the bytes of every object built from it, even if it only adds a comment line: the objects are built with-g, so.BTF.ext,.debug_infoand.debug_linechange. Every node reloads a changed object on upgrade. A comment reworded in place, or appended at the end of a file, left the objects byte-identical (clang 15.0.7 on AL2023). Treat any edit as changing the bytes unless you have built both versions and compared them. When both directions must reload, bumpNPA_FILE_VERSIONin all four tc programs. - Headers.
.gitignoreignores*.h. A new header inpkg/ebpf/c/needs an exception, asct_deny.hhas. - Cached objects. The reconcilers read with
client.UnsafeDisableDeepCopy. Never write to those objects or to anything reachable from them. - Locks.
podIdentifierLocksis not re-entrant: never take it in a function called with it held. Some such helpers end inLocked, but the attach, load and delete helpers (attachIngressBPFProbe,loadBPFProgram,deleteBPFProbes) also run under it without the suffix. - Logging. Use the package's
log()helper. The logger formats likefmt.Sprintf, so use%v, not%w. - Comments. Describe current behavior and why, not change history.
Review checklist
docs/review-guide.md has the full checklist: SDK contracts, v4/v6 parity, upgrade and rollback, precedents to reuse, and recurring review themes, each with code citations and a way to check it. Read the sections that match the files a change touches before you open or review a PR. Each item is tagged [blocking] or [advisory]. When reviewing, report a finding as blocking only when its own impact meets the blocking bar in the guide's section 1, not because the guide item is tagged blocking; list blocking findings first and keep advisory ones brief.
docs/using-the-review-guide.md explains how to use AGENTS.md, the review guide and the diff helper in your workflow.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

