Here you can learn how you can contribute to Inspektor Gadget.


    It’s highly recommended to read the architecture documentation before starting to play with Inspektor Gadget.

    Setup developer environment

    Building the code

    Inspektor Gadget is composed by a client executable and a container image. A container repository is needed to push the image. The following commands use the value of the CONTAINER_REPO env variable, it defaults to if not defined.

    Building the client executable

    You can compile for your platform by running make kubectl-gadget.

    To cross compile for all supported platforms, you can run make kubectl-gadget-all or select a specific one with make kubectl-gadget-linux-amd64 or make kubectl-gadget-darwin-amd64.

    Building the gadget container image

    You can build and push the container gadget image by running the following commands:

    $ cd gadget-container
    $ make build
    $ make push

    The BPF code is built using a Docker container, so you don’t have to worry installing the compilers to build it.

    Building notes

    • The compilation uses tools/image-tag to choose the tag of the container image to use according to the branch that you are compiling.
    • The container repository is set with the CONTAINER_REPO env variable.
    • You can push the container images to another registry and use the --image argument when deploying to the Kuberentes cluster.
    • If you wish to make changes to traceloop program, update gadget.Dockerfile to pick your own image of traceloop.
    • As for traceloop, it is also possible to change the BCC to be used as described in BCC section.
    • See the minikube section for a faster development cycle.


    Github Actions

    This repo uses Github actions as CI. It compiles and uploads the Inspektor Gadget executable and gadget container image. It also runs unit and some integration tests. A fork of this project should enable them in the repo settings page and add the following secrets to be able to use them:

    • CONTAINER_REPO: The container repository to use. Example:
    • CONTAINER_REGISTRY: The registry containing the repo above. Leave empty for Docker Hub. Example:,,
    • CONTAINER_REGISTRY_USERNAME & CONTAINER_REGISTRY_PASSWORD: Authentication information for the the repo above.

    Development environment on minikube

    It’s possible to make changes to Inspektor Gadget and test them on minikube locally without pushing container images to any registry.

    • Follow the specific installation instructions for minikube.
    • Make sure the git repositories traceloop and inspektor-gadget are cloned in sibling directories
    • Minikube with the Docker driver does not work for traceloop. You can use another driver, for example:
    $ minikube start --driver=kvm2
    • Install Inspektor Gadget on minikube as usual:
    $ kubectl gadget deploy | kubectl apply -f -
    • Make changes in the traceloop repository and compile with make
    • Generate the new gadget image and deploy it to minikube:
    $ make -C gadget-container/ minikube


    Unit tests

    You can run the different unit tests with:

    $ make test

    Integration tests

    The integration tests use a Kubernetes cluster to deploy and test Inspektor Gadget. Be sure that you have a valid kubeconfig and run:

    $ export KUBECONFIG=... # not needed if valid config in $HOME/.kube/config
    $ make integration-tests

    Code of Conduct

    Please refer to the Kinvolk Code of Conduct .

    Authoring PRs

    For making PRs/commits consistent and easier to review, please check out Kinvolk’s contribution guidelines on git .

    Good first issues

    If you’re looking where to start, you can check the issues with the good first issue label on Inspektor Gadget or traceloop . Don’t hesitate to talk with us if you need further help.

    Proposing new features

    If you want to propose a new feature or do a big change in the architecture it’s highly recommended to open an issue first to discuss it with the team.


    Porting BCC gadgets

    This project uses some gadgets from BCC . Instead of keeping our patched versions, we prefer to make those gadgets suitable to be used with Inspektor Gadget by contributing to the upstream project.

    A BCC gadget has to provide a filtering mechanism by cgroup id and mount namespace id in order to be compatible with Inspektor Gadget. You can get some inspiration from the opensnoop and execsnoop implementations to port a different BCC gadget.

    Once the gadget has been updated in the BCC repo, it can be added to Inspektor Gadget by filling a PR adding the gadget to cmd/kubectl-gadget/bcck8s.go . The add gadget bindsnoop PR is an example of it.

    The adding new BCC-based gadgets in Inspektor Gadget blogpost presents some more details about this process.

    Updating BCC from upstream

    As you can see in gadget.Dockerfile, the gadget container image uses the BCC container image as its parent image. Given that there is not an official container repository to get that BCC image, we keep a synchronised Kinvolk BCC fork that is configured to publish the images on Kinvolk container registries Quay and Docker Hub , by using the Github actions already available in BCC upstream .

    Given that, if you want to update the BCC version used by Inspektor Gadget, it is necessary to first update the Kinvolk BCC fork so that the Github actions are triggered, and a new image is published. Once the image is available in registries, you have to update gadget.Dockerfile so that it uses the just created image, same goes for local compilation with gadget-local.Dockerfile. The Update BCC container image PR is an example of it.

    Currently, we use Docker Hub to pull the BCC image when building the gadget container image. Notice we do not use the latest tag because it is overwritten after each push on master branch. Instead, we use the stable unique tags that are named with format: <Timestamp><Commit-SHA>. For instance, tag 202107061407494e8e8c describes that it was created in 2021-07-06 at 14:07:49 from commit SHA starting with 4e8e8c.