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 and libelf (in Debian systems, e.g., install libelf-dev and libcap-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:

1. The --bpf-lib flag tells Tetragon where to look for its compiled BPF programs (which were built in the make step above).

2. 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

Working on the nok8s build

Building the nok8s version of tetragon relies on setting the nok8s tag in builds. This means that editor or IDE would need to be configured appropriately so that features such as “goto-definition” operate in the full build.

You can find some configuration examples below.

• vim

vim.lsp.config.gopls = {
  cmd =     { "gopls" },
  cmd_env = {GOFLAGS = "-tags=nok8s"}
}

let g:go_build_tags = 'nok8s'

Local Development with Apple Silicon Mac

Use Lima to create a Linux VM if you are using a Mac with Apple silicon. For example:

First create a VM using Lima:

brew install lima
limactl create --mount-writable --tty=false --name=tetragon
limactl start tetragon
limactl shell tetragon

Then install needed dependencies inside the VM:

sudo add-apt-repository -y ppa:longsleep/golang-backports
sudo apt update
sudo apt install -y golang-1.23 libelf-dev libcap-dev make
export CONTAINER_ENGINE=nerdctl
export PATH=$PATH:/usr/lib/go-1.23/bin

You can now build Tetragon in your VM:

make -j3 tetragon-bpf tetragon tetra

What’s next

• See how to make your first changes.