Contribution Guide

• 1: Development setup
• 2: Making changes
• 3: Running tests
• 4: Documentation
• 5: Submitting a pull request
• 6: Developer's certificate of origin

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

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.

2 - Making changes

1. Make sure the main branch of your fork is up-to-date:

   git fetch upstream
   git checkout main
   git merge upstream/main
   

   For further reference read GitHub syncing a fork documentation.

2. Create a PR branch with a descriptive name, branching from main:

   git switch -c pr/${GITHUB_USERNAME_OR_ORG}/changes-to-something main
   

3. Make the changes you want.

4. Separate the changes into logical commits.

   • Describe the changes in the commit messages. Focus on answering the question why the change is required and document anything that might be unexpected.
   • If any description is required to understand your code changes, then those instructions should be code comments instead of statements in the commit description.
   • For submitting PRs, all commits need to be signed off (git commit -s). See the section Developer’s Certificate of Origin

5. Make sure your changes meet the following criteria:

   • New code is covered by Integration Testing.
   • End to end integration / runtime tests have been extended or added. If not required, mention in the commit message what existing test covers the new code.
   • Follow-up commits are squashed together nicely. Commits should separate logical chunks of code and not represent a chronological list of changes.

6. Run git diff --check to catch obvious white space violations

7. Build Tetragon with your changes included.

What’s next

• See how to run the tests of the project.
• See how to submit your first pull request.

3 - Running tests

Tetragon has several types of tests:

• Go tests, composed of unit tests for userspace Go code and Go and BPF code.
• BPF unit tests, testing specifing BPF functions.
• E2E tests, for end-to-end tests, installing Tetragon in Kubernetes clusters and checking for specific features.

Those tests are running in the Tetragon CI on various kernels¹ and various architectures (amd64 and arm64).

Go tests

To run the Go tests locally, you can use:

make test

Use EXTRA_TESTFLAGS to add flags to the go test command.

Test specific kernels

To run the Go tests on various kernel versions, we use vmtests with cilium/little-vm-helper in the CI, you can also use it locally for testing specific kernels. See documentation github.com/cilium/tetragon/tests/vmtests.

BPF unit tests

To run BPF unit tests, you can use:

make bpf-test

Those tests can be found under github.com/cilium/tetragon/bpf/tests. The framework uses Go tests with cilium/ebpf to run those tests, you can use BPFGOTESTFLAGS to add go test flags, like make BPFGOTESTFLAGS="-v" bpf-test.

E2E tests

To run E2E tests, you can use:

make e2e-test

This will build the Tetragon image and use the e2e framework to create a kind cluster, install Tetragon and run the tests. To not rebuild the image before running the test, use E2E_BUILD_IMAGES=0. You can use EXTRA_TESTFLAGS to add flags to the go test command.

What’s next

• See how to submit your first pull request.

4 - Documentation

Thank you for taking the time to improve Tetragon’s documentation.

Find the content

All the Tetragon documentation content can be found under github.com/cilium/tetragon/docs/content/en/docs.

Style to follow

We generally follow the Kubernetes docs style guide k8s.io/docs/contribute/style/style-guide.

Preview locally

To preview the documentation locally, use one of the method below. Then browse to localhost:1313/docs, the default port used by Hugo to listen.

Using Docker

With a Docker service available, from the root of the repository, use:

make docs

You can also use make from the Makefile at the /docs folder level.

To cleanup the container image built in the process, you can use:

make -C docs clean

Local Hugo installation

The documentation is a Hugo static website using the Docsy theme.

Please refer to dedicated guides on how to install Hugo+extended and how to tweak Docsy, but generally, to preview your work, from the /docs folder:

hugo server

5 - Submitting a pull request

Submitting a pull request

Contributions must be submitted in the form of pull requests against the upstream GitHub repository at https://github.com/cilium/tetragon.

1. Fork the Tetragon repository.

2. Push your changes to the topic branch in your fork of the repository.

3. Submit a pull request on https://github.com/cilium/tetragon.

Before hitting the submit button, please make sure that the following requirements have been met:

1. Each commit compiles and is functional on its own to allow for bisecting of commits.

2. All code is covered by unit and/or runtime tests where feasible.

3. All changes have been tested and checked for regressions by running the existing testsuite against your changes.

4. All commits contain a well written commit description including a title, description and a Fixes: #XXX line if the commit addresses a particular GitHub issue identified by its number. Note that the GitHub issue will be automatically closed when the commit is merged.

   doc: add contribution guideline and how to submit pull requests
   
   Tetragon Open Source project was just released and it does not include
   default contributing guidelines.
   
   This patch fixes this by adding:
   
   1. CONTRIBUTING.md file in the root directory as suggested by github documentation: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors
   
   2. Development guide under docs directory with a section on how to submit pull requests.
   
   3. Moves the DEVELOP.md file from root directory to the `docs/contributing/development/` one.
   
   Fixes: #33
   
   Signed-off-by: Djalal Harouni <djalal@cilium.io>
   

   Note: Make sure to include a blank line in between commit title and commit description.

5. All commits are signed off. See the section Developer’s Certificate of Origin.

6. All important steps in Making changes have been followed.

Frequently Asked Questions

CI is complaining about Go module vendoring, what do I do?

You can run make vendor then add and commit your changes.

CI is complaining about a missing “signed-off-by” line. What do I do?

You need to add a signed-off-by line to your commit messages. The easiest way to do this is with git fetch origin/main && git rebase --signoff origin/main. Then push your changes.

6 - Developer's certificate of origin

To improve tracking of who did what, we’ve introduced a “sign-off” procedure, make sure to read and apply the Developer’s Certificate of Origin.