Contribution Guide
How to contribute to the project
Welcome to Tetragon :) !
We’re happy you’re interested in contributing to the Tetragon project.
All contributions are welcome
While this document focuses on the technical details of how to submit patches
to the Tetragon project, we value all kinds of contributions.
For example, actions that can greatly improve Tetragon and contribute to its
success could be:
- Write a blog post about Tetragon or one of its use cases, we will be happy to
add a reference to it in resources.
- Talk about Tetragon during conferences or meetups, similarly, as a blog post,
video recordings can be added to resources.
- Share your usage of Tetragon on social platforms, and add yourself to the
user list of the Cilium project
as a Tetragon user.
- Raise an issue on the repository about a bug, enhancement, or something else.
See open a new issue.
- Review a patch on the repository, this might look intimidading but some
simple pull requests would benefit from a fresh pair of eyes. See open pull
requests.
- Submit a patch to the Tetragon project, for code and documentation
contribution. See the next section
for a how-to guide.
Guide for code and docs contribution
This section of the Tetragon documentation will help you make sure you
have an environment capable of testing changes to the Tetragon source code,
and that you understand the workflow of getting these changes reviewed and
merged upstream.
Make sure you have a GitHub account.
Fork the Tetragon repository
to your GitHub user or organization. The repository is available under
github.com/cilium/tetragon.
(Optional) Turn off GitHub actions
for your fork. This is recommended to avoid unnecessary CI notification
failures on the fork.
Clone your fork
and set up the base repository as upstream
remote:
git clone https://github.com/${YOUR_GITHUB_USERNAME_OR_ORG}/tetragon.git
cd tetragon
git remote add upstream https://github.com/cilium/tetragon.git
Prepare your development setup.
Check out GitHub good first issues
to find something to work on. If this is your first Tetragon issue, try to
start with something small that you think you can do without too much
external help. Also avoid assigning too many issues to yourself (see Don’t
Lick the Cookie!).
Follow the steps in making changes
to start contributing.
Learn how to run the tests
or how to preview and contribute to the docs.
Learn how to submit a pull request
to the project.
Please accept our gratitude for taking the time to improve Tetragon! :)
1 - Development setup
This will help you getting started with your development setup to build Tetragon
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):
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 the make
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:
And to run k8s CRD generation, run the following command from the root of the repository:
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:
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:
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:
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
2 - Making changes
Learn how to make your first changes to the project
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.
Create a PR branch with a descriptive name, branching from main:
git switch -c pr/${GITHUB_USERNAME_OR_ORG}/changes-to-something main
Make the changes you want.
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
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.
Run git diff --check
to catch obvious white space violations
Build Tetragon with your changes included.
What’s next
3 - Running tests
Learn how to run the tests of the project
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:
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:
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:
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
4 - Documentation
Learn how to contribute to the 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.
Note When submitting a docs related pull request, a Netlify job will automatically
build a preview of your changes and post the link in a PR comment, it is often
a good idea to edit your initial PR message and link to the precise location
of your changes within the preview to help the reviewer’s job.
Using Docker
With a Docker service available, from the root of the repository, use:
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:
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:
5 - Submitting a pull request
Learn how to submit a pull request to the project
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.
Fork the Tetragon repository.
Push your changes to the topic branch in your fork of the repository.
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:
Each commit compiles and is functional on its own to allow for bisecting of
commits.
All code is covered by unit and/or runtime tests where feasible.
All changes have been tested and checked for regressions by running the
existing testsuite against your changes.
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.
All commits are signed off. See the section Developer’s Certificate of
Origin.
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
Learn about the “sign-off” procedure
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.