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);
- 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.
Running code generation
Tetragon uses code generation based on protoc to generate large amounts of boilerplate code based on our protobuf API. We similarly use automatic generation to maintain our k8s CRDs. Whenever you make changes to these files, you will be required to re-run code generation before your PR can be accepted.
To run codegen from protoc, run the following command from the root of the repository:
make protogen
And to run k8s CRD generation, run the following command from the root of the repository:
make crds
Finally, should you wish to modify any of the resulting codegen files (ending
in .pb.go
), do not modify them directly. Instead, you can edit the files in
cmd/protoc-gen-go-tetragon
and then re-run make protogen
.
Running vendor
Tetragon uses multiple modules to separate the main module, from api
from
pkg/k8s
. Depending on your changes you might need to vendor those changes,
you can use:
make vendor
Note that the make protogen
and make crds
commands already vendor
changes automatically.
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 kube-system
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.