{"id":17526241,"url":"https://github.com/netobserv/netobserv-ebpf-agent","last_synced_at":"2025-04-12T09:26:31.367Z","repository":{"id":37405031,"uuid":"467035748","full_name":"netobserv/netobserv-ebpf-agent","owner":"netobserv","description":"Network Observability eBPF Agent","archived":false,"fork":false,"pushed_at":"2025-01-30T13:03:04.000Z","size":31511,"stargazers_count":152,"open_issues_count":16,"forks_count":35,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-01-30T13:45:19.301Z","etag":null,"topics":["ebpf","kubernetes","network-observability","openshift"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/netobserv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-07T09:55:49.000Z","updated_at":"2025-01-30T13:03:08.000Z","dependencies_parsed_at":"2023-10-03T18:58:38.335Z","dependency_job_id":"c3a45c92-a557-45d1-9ec5-31907ff9a43f","html_url":"https://github.com/netobserv/netobserv-ebpf-agent","commit_stats":null,"previous_names":["netobserv/netobserv-agent"],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netobserv%2Fnetobserv-ebpf-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netobserv%2Fnetobserv-ebpf-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netobserv%2Fnetobserv-ebpf-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netobserv%2Fnetobserv-ebpf-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/netobserv","download_url":"https://codeload.github.com/netobserv/netobserv-ebpf-agent/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248545360,"owners_count":21122128,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ebpf","kubernetes","network-observability","openshift"],"created_at":"2024-10-20T15:01:29.034Z","updated_at":"2025-04-12T09:26:26.350Z","avatar_url":"https://github.com/netobserv.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"# Network Observability eBPF Agent\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/netobserv/netobserv-ebpf-agent)](https://goreportcard.com/report/github.com/netobserv/netobserv-ebpf-agent)\n\nThe Network Observability eBPF Agent allows collecting and aggregating all the ingress and\negress flows on a Linux host (required a Kernel 5.8+ with eBPF enabled).\n\n* [How to build](#how-to-build)\n* [How to configure](#how-to-configure)\n* [How to run](#how-to-run)\n* [Development receipts](#development-receipts)\n* [Known issues](#known-issues)\n* [Frequently-asked questions](#frequently-asked-questions)\n* [Troubleshooting](#troubleshooting)\n\n## How to build\n\nTo build the agent image and push it to your Docker / Quay repository, run:\n```bash\n# compile project\nmake build\n\n# build the default image (quay.io/netobserv/netobserv-ebpf-agent:main):\nmake image-build\n\n# push the default image (quay.io/netobserv/netobserv-ebpf-agent:main):\nmake image-push\n\n# build and push on your own quay.io account (quay.io/myuser/netobserv-ebpf-agent:dev):\nIMAGE_ORG=myuser VERSION=dev make images\n\n# build and push on a different registry\nIMAGE=dockerhub.io/myuser/plugin:tag make images\n```\n\n## How to configure\n\nThe eBPF Agent is configured by means of environment variables. Check the\n[configuration documentation](./docs/config.md) for more details.\n\n## How to run\n\nThe NetObserv eBPF Agent is designed to run as a DaemonSet in OpenShift/K8s. It is triggered and\nconfigured by our [Network Observability Operator](https://github.com/netobserv/network-observability-operator).\n\nAnyway you can run it directly as an executable from your command line:\n\n```bash\nexport TARGET_HOST=...\nexport TARGET_PORT=...\nsudo -E bin/netobserv-ebpf-agent\n```\n\nWe don't recommend using the agent's IPFIX exporter mode as it is not actively maintained (if you're interested in maintaining it, let us know!). Note that flowlogs-pipeline can also generate IPFIX exports, so a valid way to get IPFIX data is to export to flowlogs-pipeline (via GRPC, Kafka or direct-flp) and then configure IPFIX within flowlogs-pipeline.\n\nA simple way to try the agent is using the `direct-flp` export mode, printing directly to stdout:\n\nGiven the following file `flp-config.json`:\n\n```json\n{\n\t\"pipeline\":[\n\t\t{\"name\": \"writer\",\"follows\": \"preset-ingester\"}\n\t],\n\t\"parameters\":[\n\t\t{\"name\": \"writer\",\"write\": {\"type\": \"stdout\"}}\n\t]\n}\n```\nRun:\n\n```bash\nexport FLP_CONFIG=$(cat flp-config.json)\nexport EXPORT=\"direct-flp\"\nsudo -E bin/netobserv-ebpf-agent\n```\n\nFor more information about configuring flowlogs-pipeline, please refer to [its documentation](https://github.com/netobserv/flowlogs-pipeline).\n\nTo deploy locally, use instructions from [flowlogs-dump (like tcpdump)](./examples/flowlogs-dump/README.md).    \nTo deploy it as a Pod, you can check the [deployment examples](./deployments).\n\nThe Agent needs to be executed either with:\n\n1. The following [Linux capabilities](https://man7.org/linux/man-pages/man7/capabilities.7.html)\n   (recommended way): `BPF`, `PERFMON`, `NET_ADMIN`, `SYS_RESOURCE`. If you\n   [deploy it in Kubernetes or OpenShift](./deployments/flp-daemonset-cap.yml),\n   the container running the Agent needs to define the following `securityContext`:\n   ```yaml\n   securityContext:\n     runAsUser: 0\n     capabilities:\n       add:\n         - BPF\n         - PERFMON\n         - NET_ADMIN\n         - SYS_RESOURCE\n   ```\n   (Please notice that the `runAsUser: 0` is still needed).\n2. Administrative privileges. If you\n   [deploy it in Kubernetes or OpenShift](./deployments/flp-daemonset.yml),\n   the container running the Agent needs to define the following `securityContext`:\n   ```yaml\n   securityContext:\n     privileged: true\n     runAsUser: 0\n   ```\n   This option is only recommended if your Kernel does not recognize some of the above capabilities.\n   We found some Kubernetes distributions (e.g. K3s) that do not recognize the `BPF` and\n   `PERFMON` capabilities.\n\nHere is a list of distributions where we tested both full privileges and capability approaches,\nand whether they worked (✅) or did not (❌):\n\n| Distribution                  | K8s Server version | Capabilities | Privileged |\n|-------------------------------|--------------------|--------------|------------|\n| Amazon EKS (Bottlerocket AMI) | 1.22.6             | ✅            | ✅          |\n| K3s (Rancher Desktop)         | 1.23.5             | ❌            | ✅          |\n| Kind                          | 1.23.5             | ❌            | ✅          |\n| OpenShift                     | 1.23.3             | ✅            | ✅          |\n\n## Running on KinD cluster\n\n### How to run on kind cluster\n\nInstall KinD and the ebpf agent and export KUBECONFIG\n```sh\nmake create-and-deploy-kind-cluster\nexport KUBECONFIG=$(pwd)/scripts/kubeconfig\n```\n\n### Deleting the kind cluster\n\nIn order to delete the kind cluster:\n```sh\nmake destroy-kind-cluster\n```\n\n## Development receipts\n\n### How to regenerate the eBPF Kernel binaries\n\nThe eBPF program is embedded into the `pkg/ebpf/bpf_*` generated files.\nThis step is generally not needed unless you change the C code in the `bpf` folder.\n\nIf you have Docker installed, you just need to run:\n\n```bash\nmake docker-generate\n```\n\nIf you can't install docker, you can install locally the following packages, then run `make generate`:\n\n```bash\ndnf install -y kernel-devel make llvm clang glibc-devel.i686\nmake generate\n```\n\nRegularly tested on Fedora.\n\n### Running end-to-end tests\n\nRefer to the specific documentation: [e2e readme](./e2e/README.md)\n\n## Known issues\n\n### Extrenal Traffic in Openshift (OVN-Kubernetes CNI)\n\nFor egress traffic, you can see the source Pod metadata. For ingress traffic (e.g. an HTTP response),\nyou see the destination **Host** metadata.\n\n## Frequently-asked questions\n\n### Where is the collector?\n\nAs part of our Network Observability solution, the eBPF Agent is designed to send the traced\nflows to our [Flowlogs Pipeline](https://github.com/netobserv/flowlogs-pipeline) component.\n\nIn addition, we provide a simple GRPC+Protobuf library to allow implementing your own collector.\nCheck the [packet counter code](./examples/performance/server/packet-counter-collector.go)\nfor an example of a simple collector using our library.\n\n## Troubleshooting\n\n### Deployed as a Kubernetes Pod, the agent shows permission errors in the logs and can't start\n\nIn your [deployment file](./deployments/flp-daemonset-cap.yml), make sure that the container runs as\nthe root user (`runAsUser: 0`) and with the granted capabilities or privileges (see [how to run](#how-to-run) section).\n\n### The Agent doesn't work in my Amazon EKS puzzle\n\nDespite Amazon Linux 2 enables eBPF by default in EC2, the\n[EKS images are shipped with disabled eBPF](https://github.com/awslabs/amazon-eks-ami/issues/728).\n\nYou'd need either:\n\n1. Provide your own AMI configured to work with eBPF\n2. Use other Linux distributions that are shipped with eBPF enabled by default. We have successfully\n   tested the eBPF Agent in EKS with the [Bottlerocket](https://aws.amazon.com/es/bottlerocket/)\n   Linux distribution, without requiring any extra configuration.\n\n## Licenses\n\nTwo licenses are used for the source code in this repository:\n\n- [GPL v2](./bpf/LICENSE) covers the eBPF code in `./bpf` directory.\n- [Apache v2](./LICENSE) covers everything else.\n\n## Discussions and contributions\n\nDiscussions related to NetObserv are welcome on [GitHub discussions](https://github.com/orgs/netobserv/discussions) as well as on the [#netobserv-project](http://cloud-native.slack.com/) channel from CNCF slack.\n\nIf you'd like to reach out because you've found a security issue, please do not share sensitive details publicly. Please follow the instructions described on the [Red Hat Customer Portal](https://access.redhat.com/security/team/contact/?extIdCarryOver=true\u0026sc_cid=701f2000001Css5AAC).\n\nRefer to the [NetObserv projects contribution guide](https://github.com/netobserv/documents/blob/main/CONTRIBUTING.md) for more details on contributions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetobserv%2Fnetobserv-ebpf-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetobserv%2Fnetobserv-ebpf-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetobserv%2Fnetobserv-ebpf-agent/lists"}