Development setup
Building and running Tetragon
For local development, you will likely want to build and run bare-metal Tetragon.
Requirements
- A Go toolchain with the version specified in the main
go.mod
; - GNU make;
- A running Docker service (you can use Podman as well);
- The docker-buildx-plugin (you may already have this);
- For building tests,
libcap
andlibelf
(in Debian systems, e.g., installlibelf-dev
andlibcap-dev
).
Build everything
You can build most Tetragon targets as follows (this can take time as it builds all the targets needed for testing, see minimal build):
make
If you want to use podman
instead of docker
, you can do the following (assuming you
need to use sudo
with podman
):
CONTAINER_ENGINE='sudo podman' make
You can ignore /bin/sh: docker: command not found
in the output.
To build using the local clang, you can use:
CONTAINER_ENGINE='sudo podman' LOCAL_CLANG=1 LOCAL_CLANG_FORMAT=1 make
See Dockerfile.clang
for the minimal required version of clang
.
Minimal build
To build the tetragon
binary, the BPF programs and the tetra
CLI binary you
can use:
make tetragon tetragon-bpf tetra
Run Tetragon
You should now have a ./tetragon
binary, which can be run as follows:
sudo ./tetragon --bpf-lib bpf/objs
Notes:
The
--bpf-lib
flag tells Tetragon where to look for its compiled BPF programs (which were built in themake
step above).If Tetragon fails with an error
"BTF discovery: candidate btf file does not exist"
, then make sure that your kernel support BTF, otherwise place a BTF file where Tetragon can read it and specify its path with the--btf
flag. See more about that in the FAQ.
Building and running a Docker image
The base kernel should support BTF
or a BTF file should be bind mounted on top of /var/lib/tetragon/btf
inside
container.
To build Tetragon image:
make image
To run the image:
docker run --name tetragon \
--rm -it -d --pid=host \
--cgroupns=host --privileged \
-v /sys/kernel/btf/vmlinux:/var/lib/tetragon/btf \
cilium/tetragon:latest
Run the tetra
binary to get Tetragon events:
docker exec -it tetragon \
bash -c "/usr/bin/tetra getevents -o compact"
Building and running as a systemd service
To build Tetragon tarball:
make tarball
Running Tetragon in kind
This command will setup tetragon, kind cluster and install tetragon in it. Ensure docker, kind, kubectl, and helm are installed.
# Setup tetragon on kind
make kind-setup
Verify that Tetragon is installed by running:
kubectl get pods -n tetragon
Local Development in Vagrant Box
If you are on an intel Mac, use Vagrant to create a dev VM:
vagrant up
vagrant ssh
make
If you are getting an error, you can try to run sudo launchctl load /Library/LaunchDaemons/org.virtualbox.startup.plist
(from a Stackoverflow
answer).
What’s next
- See how to make your first changes.