diff --git a/docs/content/en/docs/contribution-guide/_index.md b/docs/content/en/docs/contribution-guide/_index.md index b5b41ec4aed..21ddff8efcb 100644 --- a/docs/content/en/docs/contribution-guide/_index.md +++ b/docs/content/en/docs/contribution-guide/_index.md @@ -5,6 +5,8 @@ description: > How to contribute to the project --- +Welcome to Tetragon :) ! + We're happy you're interested in contributing to the Tetragon project. This section of the Tetragon documentation will help you make sure you @@ -12,33 +14,41 @@ 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. -### Clone and provision an environment +## Clone and provision an environment 1. Make sure you have a [GitHub account](https://github.com/join). -2. Fork the Tetragon repository to your GitHub user or organization. - -3. Turn off GitHub actions for your fork as described in the - [GitHub Docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#managing-github-actions-permissions-for-your-repository>). +2. [Fork the Tetragon repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) + to your GitHub user or organization. The repository is available under + [github.com/cilium/tetragon](https://github.com/cilium/tetragon). - This is recommended to avoid unnecessary CI notification failures on the fork. +3. (Optional) [Turn off GitHub actions](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#about-github-actions-permissions-for-your-repository) + for your fork. This is recommended to avoid unnecessary CI notification + failures on the fork. -4. Clone your `${YOUR_GITHUB_USERNAME_OR_ORG}/tetragon` fork into your - `GOPATH`, and set up the base repository as `upstream` remote: +4. [Clone your fork](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) + and set up the base repository as `upstream` remote: ```shell - mkdir -p "${GOPATH}/src/github.com/cilium" - cd "${GOPATH}/src/github.com/cilium" git clone https://github.com/${YOUR_GITHUB_USERNAME_OR_ORG}/tetragon.git cd tetragon git remote add upstream https://github.com/cilium/tetragon.git ``` -5. Prepare your [Development setup](/docs/contribution-guide/development-setup), - see section below. +5. Prepare your [development setup]({{< ref "/docs/contribution-guide/development-setup" >}}). + +6. Check out GitHub [good first issues](https://github.com/cilium/tetragon/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) + 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!](https://www.redhat.com/en/blog/dont-lick-cookie)). + +7. Follow the steps in [making changes]({{< ref "/docs/contribution-guide/making-changes" >}}) + to start contributing. -6. Check the GitHub issues for [good tasks to get - started](https://github.com/cilium/tetragon/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). +8. Learn how to [run the tests]({{< ref "/docs/contribution-guide/running-tests" >}}). -7. Follow the steps in [Making changes](/docs/contribution-guide/making-changes) to start contributing. Welcome :)! +9. Learn how to [submit a pull request]({{< ref "/docs/contribution-guide/submitting-a-pull-request" >}}) + to the project. +10. Please accept our gratitude for taking the time to improve Tetragon! :) diff --git a/docs/content/en/docs/contribution-guide/development-setup.md b/docs/content/en/docs/contribution-guide/development-setup.md index f1356fc1ada..b7bf7b60364 100644 --- a/docs/content/en/docs/contribution-guide/development-setup.md +++ b/docs/content/en/docs/contribution-guide/development-setup.md @@ -4,18 +4,22 @@ weight: 1 description: "This will help you getting started with your development setup to build Tetragon" --- -### Building and Running Tetragon +## Building and running Tetragon For local development, you will likely want to build and run bare-metal Tetragon. -Requirements: -- go 1.18 -- GNU make -- A running docker service -- `libcap` and `libelf` (in Debian systems, e.g., install `libelf-dev` and - `libcap-dev`) +### Requirements -You can build Tetragon as follows: +- A Go toolchain with the [version specified in the main `go.mod`](https://github.com/cilium/tetragon/blob/main/go.mod#L4); +- 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](#minimal-build)): ```shell make @@ -34,10 +38,19 @@ To build using the local clang, you can use: CONTAINER_ENGINE='sudo podman' LOCAL_CLANG=1 LOCAL_CLANG_FORMAT=1 make ``` -See -[Dockerfile.clang](https://github.com/cilium/tetragon/blob/main/Dockerfile.clang) +See [Dockerfile.clang](https://github.com/cilium/tetragon/blob/main/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: +```shell +make tetragon tetragon-bpf tetra +``` + +### Run Tetragon + You should now have a `./tetragon` binary, which can be run as follows: ```shell @@ -52,9 +65,10 @@ Notes: 2. If Tetragon fails with an error `"BTF discovery: candidate btf file does not exist"`, then make sure that your kernel support [BTF](#btf-requirement), otherwise place a BTF file where Tetragon can read it and specify its path - with the `--btf` flag. + with the `--btf` flag. See more about that + [in the FAQ]({{< ref "/docs/faq/#tetragon-failed-to-start-complaining-about-a-missing-btf-file" >}}). -### Running Code Generation +## 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 @@ -76,7 +90,20 @@ 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 codegen`. -### Building and running a Docker image +## 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: + +```shell +make vendor +``` + +Note that the `make codegen` and `make generate` commands already vendor +changes automatically. + +## Building and running a Docker image The base kernel should support [BTF](https://github.com/cilium/tetragon#btf-requirement) or a BTF file should be bind mounted on top of `/var/lib/tetragon/btf` inside @@ -103,14 +130,14 @@ docker exec -it tetragon \ bash -c "/usr/bin/tetra getevents -o compact" ``` -### Building and running as a systemd service +## Building and running as a systemd service To build Tetragon tarball: ```shell make tarball ``` -### Running Tetragon in kind +## Running Tetragon in kind This command will setup tetragon, kind cluster and install tetragon in it. Ensure docker, kind, kubectl, and helm are installed. @@ -124,9 +151,9 @@ Verify that Tetragon is installed by running: kubectl get pods -n kube-system ``` -### Local Development in Vagrant Box +## Local Development in Vagrant Box -If you are on a Mac, use Vagrant to create a dev VM: +If you are on an intel Mac, use Vagrant to create a dev VM: ```shell vagrant up @@ -138,7 +165,7 @@ If you are getting an error, you can try to run `sudo launchctl load /Library/LaunchDaemons/org.virtualbox.startup.plist` (from [a Stackoverflow answer](https://stackoverflow.com/questions/18149546/macos-vagrant-up-failed-dev-vboxnetctl-no-such-file-or-directory)). -### What's next +## What's next - See how to [make your first changes](/docs/contribution-guide/making-changes). diff --git a/docs/content/en/docs/contribution-guide/making-changes.md b/docs/content/en/docs/contribution-guide/making-changes.md index dc06607afb5..86d15e0ed8d 100644 --- a/docs/content/en/docs/contribution-guide/making-changes.md +++ b/docs/content/en/docs/contribution-guide/making-changes.md @@ -13,7 +13,7 @@ description: "Learn how to make your first changes to the project" ``` For further reference read - [github syncing a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) + [GitHub syncing a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) documentation. 2. Create a PR branch with a descriptive name, branching from main: @@ -33,7 +33,7 @@ description: "Learn how to make your first changes to the project" 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](/docs/contribution-guide/developer-certificate-of-origin/) + See the section [Developer's Certificate of Origin]({{< ref "/docs/contribution-guide/developer-certificate-of-origin" >}}) 5. Make sure your changes meet the following criteria: @@ -48,7 +48,7 @@ description: "Learn how to make your first changes to the project" 7. Build Tetragon with your changes included. -### What's next +## What's next - See how to [run the tests of the project](/docs/contribution-guide/running-tests/). - See how to [submit your first pull request](/docs/contribution-guide/submitting-a-pull-request/). diff --git a/docs/content/en/docs/contribution-guide/running-tests.md b/docs/content/en/docs/contribution-guide/running-tests.md index f14b545df7f..91da17726fa 100644 --- a/docs/content/en/docs/contribution-guide/running-tests.md +++ b/docs/content/en/docs/contribution-guide/running-tests.md @@ -1,13 +1,66 @@ --- title: "Running tests" weight: 3 -manualLink: "https://github.com/cilium/tetragon/tree/main/tests/vmtests" -manualLinkTarget: "_blank" description: "Learn how to run the tests of the project" --- -See https://github.com/cilium/tetragon/tree/main/tests/vmtests. +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. -### What's next +Those tests are running in the Tetragon CI on various kernels[^1] and various +architectures (amd64 and arm64). + +[^1]: For the detailed list, search for `jobs.test.strategy.matrix.kernel` in +[github.com/cilium/tetragon/.github/workflows/vmtests.yml](https://github.com/cilium/tetragon/blob/main/.github/workflows/vmtests.yml) + +## Go tests + +To run the Go tests locally, you can use: + +```shell +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](https://github.com/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](https://github.com/cilium/tetragon/tree/main/tests/vmtests). + +## BPF unit tests + +To run BPF unit tests, you can use: + +```shell +make bpf-test +``` + +Those tests can be found under +[github.com/cilium/tetragon/bpf/tests](https://github.com/cilium/tetragon/tree/main/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: + +```shell +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](/docs/contribution-guide/submitting-a-pull-request/). diff --git a/docs/content/en/docs/contribution-guide/submitting-a-pull-request.md b/docs/content/en/docs/contribution-guide/submitting-a-pull-request.md index f308d9cd8bb..71eec835a51 100644 --- a/docs/content/en/docs/contribution-guide/submitting-a-pull-request.md +++ b/docs/content/en/docs/contribution-guide/submitting-a-pull-request.md @@ -53,7 +53,7 @@ requirements have been met: 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](/docs/contribution-guide/developer-certificate-of-origin/). + Origin]({{< ref "/docs/contribution-guide/developer-certificate-of-origin" >}}). -6. All important steps in [Making changes](/docs/contribution-guide/making-changes/) have been followed. +6. All important steps in [Making changes]({{< ref "/docs/contribution-guide/making-changes" >}}) have been followed.