Getting started

This page is for engineers building Cilium from source. End-user installation is documented at docs.cilium.io.

Prerequisites

• Go matching the version pinned in go.mod (currently go 1.26.0).
• clang/LLVM ≥ 18 — required to compile the BPF C sources in bpf/.
• Docker (or another OCI runtime) — image builds use Makefile.docker and Dockerfiles under images/.
• make — the top-level Makefile is the canonical build entry point.
• kind + kubectl — for end-to-end testing via Makefile.kind.
• A Linux kernel ≥ 5.4 with eBPF, BTF, and recent verifier improvements is recommended for development. macOS and Windows are unsupported as build hosts for the BPF half of the project.

System requirements (kernel features, kernel config flags, supported distros) live in Documentation/operations/system_requirements.rst.

Repository layout (top level)

Path	Purpose
daemon/	Cilium agent entry point.
operator/	Cilium operator entry point.
cilium-cli/	User-facing cilium CLI source.
cilium-dbg/	In-pod debug CLI.
cilium-health/	Per-node health probe.
bugtool/	Diagnostic bundle collector.
hubble/, hubble-relay/	Hubble CLI and gRPC relay.
clustermesh-apiserver/	Cluster Mesh control plane.
standalone-dns-proxy/	Optional out-of-process DNS proxy.
bpf/	eBPF C dataplane.
pkg/	All shared Go libraries (~120 subpackages).
api/	OpenAPI specs and generated server/client code.
Documentation/	User-facing docs (Sphinx, restructured text).
images/	Dockerfiles for every published image.
install/	Helm chart sources.
test/	Ginkgo end-to-end test suite (legacy).
tools/	Internal Go tools used during build/codegen.
contrib/	Standalone helper scripts.
vendor/	Vendored Go modules (committed).

Building from source

# Build all Go binaries into ./<binary>/<binary>
make

# Build a specific binary
make -C daemon
make -C operator
make -C cilium-cli

# Build the BPF programs (requires clang)
make -C bpf

# Build the agent container image (requires Docker buildx)
make dev-docker-image

The top-level Makefile and Makefile.defs define the variables; per-binary Makefiles are thin wrappers that call out to a shared template. Makefile.docker orchestrates multi-arch image builds; Makefile.kind builds and pushes images into a local kind cluster.

Running tests

# Go unit tests (everything under pkg/)
make unit-tests

# A single package
go test ./pkg/policy/...

# Race detector
go test -race ./pkg/...

# BPF unit tests (uses bpftest harness)
make -C bpf unit-test

# Privileged unit tests (need root + bpf, run via sudo)
make tests-privileged

# Generate code (CRDs, mocks, OpenAPI, BPF asm dumps)
make generate-api
make generate-k8s-api

Most CI runs through GitHub Actions in .github/workflows/. The agent pod tests live in test/ (Ginkgo) and are gradually being replaced by package-level Go tests and the cilium-cli connectivity test suite.

Running locally

For most contributors the simplest dev loop is:

# Start a local kind cluster with two nodes
make -C cilium-cli kind

# Build current source into images and load them into kind
make kind-image
make kind-install

# Push iterative changes
make kind-image && make kind-install-quick

Once installed, use the in-pod CLI (cilium-dbg) to inspect state:

kubectl -n kube-system exec ds/cilium -- cilium status
kubectl -n kube-system exec ds/cilium -- cilium endpoint list
kubectl -n kube-system exec ds/cilium -- cilium bpf ct list global

See how-to-contribute/development-workflow.md for the full PR cycle and how-to-contribute/debugging.md for the debug toolkit.