{"id":47297152,"url":"https://github.com/netobserv/netobserv-operator","last_synced_at":"2026-03-30T23:00:48.324Z","repository":{"id":37439223,"uuid":"411168701","full_name":"netobserv/netobserv-operator","owner":"netobserv","description":"A Kubernetes operator for network observability","archived":false,"fork":false,"pushed_at":"2026-03-27T21:42:13.000Z","size":49464,"stargazers_count":221,"open_issues_count":37,"forks_count":47,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-03-28T01:45:11.419Z","etag":null,"topics":["ebpf","kubernetes","network","observability","operator"],"latest_commit_sha":null,"homepage":"https://netobserv.io","language":"Go","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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2021-09-28T06:51:14.000Z","updated_at":"2026-03-27T13:32:33.000Z","dependencies_parsed_at":"2025-12-17T19:04:57.651Z","dependency_job_id":null,"html_url":"https://github.com/netobserv/netobserv-operator","commit_stats":null,"previous_names":["netobserv/netobserv-operator"],"tags_count":69,"template":false,"template_full_name":null,"purl":"pkg:github/netobserv/netobserv-operator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netobserv%2Fnetobserv-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netobserv%2Fnetobserv-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netobserv%2Fnetobserv-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netobserv%2Fnetobserv-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/netobserv","download_url":"https://codeload.github.com/netobserv/netobserv-operator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netobserv%2Fnetobserv-operator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31213707,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-30T15:24:02.938Z","status":"ssl_error","status_checked_at":"2026-03-30T15:23:44.804Z","response_time":138,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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","operator"],"created_at":"2026-03-16T18:00:30.553Z","updated_at":"2026-03-30T23:00:48.317Z","avatar_url":"https://github.com/netobserv.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# NetObserv Operator\n\n![GitHub release (latest by date)](https://img.shields.io/github/v/release/netobserv/netobserv-operator)\n[![Artifact HUB](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/NetObserv)](https://artifacthub.io/packages/helm/netobserv/netobserv-operator)\n[![Go Report Card](https://goreportcard.com/badge/github.com/netobserv/netobserv-operator)](https://goreportcard.com/report/github.com/netobserv/netobserv-operator)\n\nNetObserv Operator is a Kubernetes operator for network observability. It deploys a monitoring pipeline that consists in:\n- An eBPF agent, that generates network flows from captured packets.\n- Flowlogs-pipeline, a component that collects, enriches and exports these flows.\n- A web console for flows visualization with powerful filtering options, a topology representation, a network health view, etc.\n\nFlow data is then available in multiple ways, each optional:\n\n- As Prometheus metrics.\n- As raw flow logs stored in Loki.\n- As raw flow logs exported to a collector via Kafka, OpenTelemetry or IPFIX.\n\n## Getting Started\n\nYou can install the NetObserv Operator using [Helm](https://helm.sh/), or directly from sources.\n\n\u003e [!TIP]\nNetObserv can be used in downstream products, which may provide their own documentation. If you are using such a product, please refer to that documentation instead:\n\u003e \n\u003e - On OpenShift: [see Network Observability operator](https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/network_observability/installing-network-observability-operators).\n\n### Pre-requisite\n\nThe following architectures are supported: _amd64_, _arm64_, _ppc64le_ and _s390x_.\n\nNetObserv has a couple of dependencies that must be installed on your cluster:\n\n- Cert-manager / trust-manager\n- Prometheus\n- Loki\n\nCert-manager and Trust-manager have to be installed separately. For example, using helm:\n\n```bash\nhelm repo add cert-manager https://charts.jetstack.io\nhelm install cert-manager -n cert-manager --create-namespace cert-manager/cert-manager --set crds.enabled=true\nhelm upgrade trust-manager oci://quay.io/jetstack/charts/trust-manager --install --namespace cert-manager --wait\n```\n\nIf you don't want to use Cert-manager and Trust-manager, you need to provide certificates by other means: refer to [TLS.md](./docs/TLS.md).\n\nPrometheus and Loki can be installed separately, or as dependencies of NetObserv (see below).\n\nLoki is not mandatory but improves the overall experience with NetObserv.\n\n### Install with Helm\n\n\u003e [!TIP]\n\u003e See it also on [ArtifactHub](https://artifacthub.io/packages/helm/netobserv/netobserv-operator).\n\n```bash\nhelm repo add netobserv https://netobserv.io/static/helm/ --force-update\n\n# Standalone install, including dependencies:\nhelm install netobserv -n netobserv --create-namespace --set install.loki=true --set install.prom-stack=true netobserv/netobserv-operator\n\n# OR minimal install (Prometheus/Loki must be installed separately)\nhelm install netobserv -n netobserv --create-namespace netobserv/netobserv-operator\n```\n\nTo start generating network flows, you must then create a `FlowCollector` resource ([full API reference](https://github.com/netobserv/netobserv-operator/blob/main/docs/FlowCollector.md#flowsnetobserviov1beta2)) named `cluster`. A short `FlowCollector` should work:\n\n```bash\ncat \u003c\u003cEOF | kubectl apply -f -\napiVersion: flows.netobserv.io/v1beta2\nkind: FlowCollector\nmetadata:\n  name: cluster\nspec:\n  namespace: netobserv\n  networkPolicy:\n    enable: false\n  processor:\n    service:\n      tlsType: Auto-mTLS\n  loki:\n    mode: Monolithic\n    monolithic:\n      url: 'http://netobserv-loki.netobserv.svc.cluster.local.:3100/'\n  prometheus:\n    querier:\n      mode: Manual\n      manual:\n        url: http://netobserv-prom-stack-prometheus.netobserv.svc.cluster.local.:9090/\n        alertManager:\n          url: http://netobserv-prom-stack-alertmanager.netobserv.svc.cluster.local.:9093/\nEOF\n```\n\nA few remarks:\n- You can change the Prometheus and Loki URLs depending on your installation. This example works if you use the \"standalone\" installation described above, with `install.loki=true` and `install.prom-stack=true`. Check more configuration options for [Prometheus](https://github.com/netobserv/netobserv-operator/blob/main/docs/FlowCollector.md#flowcollectorspecprometheus-1) and [Loki](https://github.com/netobserv/netobserv-operator/blob/main/docs/FlowCollector.md#flowcollectorspecloki-1).\n- Depending on the Kubernetes distribution and CNI, NetObserv may come secured by default with a built-in network policy. You can force installing it or not by setting `spec.networkPolicy.enable` in `FlowCollector`. If the built-in policy does not work as intended, it is recommended to turn it off and create your own instead. NetObserv runs some highly privileged workloads, thus it is important to keep it as much isolated as possible. See [NetworkPolicy.md](./docs/NetworkPolicy.md) for more details on how to create a policy.\n\nTo view the test console, you can port-forward 9001:\n\n```bash\nkubectl port-forward svc/netobserv-plugin 9001:9001 -n netobserv\n```\n\nThen open http://localhost:9001/ in your browser.\n\n### Install from repository\n\nA couple of `make` targets are provided in this repository to allow installing without OLM:\n\n```bash\ngit clone https://github.com/netobserv/netobserv-operator.git \u0026\u0026 cd network-observability-operator\nUSER=netobserv make deploy deploy-loki deploy-grafana\n```\n\nIt will deploy the operator in its latest version, with port-forwarded Loki and Grafana (they are optional).\n\n\u003e Note: the `loki-deploy` script is provided as a quick install path and is not suitable for production. It deploys a single pod, configures a 10GB storage PVC, with 24 hours of retention. For a scalable deployment, please refer to [our distributed Loki guide](https://github.com/netobserv/documents/blob/main/loki_distributed.md) or [Grafana's official documentation](https://grafana.com/docs/loki/latest/).\n\nTo deploy the monitoring pipeline, this `make` target installs a `FlowCollector` with default values:\n\n```bash\nmake deploy-sample-cr\n```\n\nAlternatively, you can [grab and edit](./config/samples/flows_v1beta2_flowcollector.yaml) this config before installing it.\n\nYou can still edit the `FlowCollector` after it's installed: the operator will take care about reconciling everything with the updated configuration:\n\n```bash\nkubectl edit flowcollector cluster\n```\n\nRefer to the [Configuration section](#configuration) of this document.\n\n### With or without Loki?\n\nHistorically, Grafana Loki was a strict dependency but it isn't anymore. If you don't want to install it, you can still get the Prometheus metrics, and/or export raw flows to a custom collector. But be aware that some of the Console plugin features will be disabled. For instance, you will not be able to view raw flows there, and the metrics / topology will have a more limited level of details, missing information such as pods or IPs.\n\n### Web Console\n\nWhen `FlowCollector` is installed, a standalone web console is deployed or, when available, a console plugin. It provides the following views:\n\n#### Overview metrics\n\nCharts on this page show overall, aggregated metrics on the cluster network. The stats can be refined with comprehensive filtering and display options. Different levels of aggregations are available: per zone, per node, per namespace, per owner or per pod/service. For instance, it allows to identify biggest talkers in different contexts: top X inter-namespace flows, or top X pod-to-pod flows within a namespace, etc.\n\nThe watched time interval can be adjusted, as well as the refresh frequency, hence you can get an almost live view on the cluster traffic. This also applies to the other pages described below.\n\n![Overview](./docs/assets/overview-dashboard.png)\n\n#### Topology\n\nThe topology view represents traffic between elements as a graph. The same filtering and aggregation options as described above are available, plus extra display options e.g. to group element by node, namespaces, etc. A side panel provides contextual information and metrics related to the selected element.\n\n![Topology](./docs/assets/topology-main.png)\n_This screenshot shows the NetObserv architecture itself: Nodes (via eBPF agents) sending traffic (flows) to the collector flowlogs-pipeline, which in turn sends data to Loki. The NetObserv console plugin fetches these flows from Loki._\n\n#### Flow table\n\nThe table view shows raw flows, ie. non aggregated, still with the same filtering options, and configurable columns.\n\n![Flow table](./docs/assets/network-traffic-main.png)\n\n## Configuration\n\nThe `FlowCollector` resource is used to configure the operator and its managed components. A comprehensive documentation is [available here](./docs/FlowCollector.md), and a full sample file [there](./config/samples/flows_v1beta2_flowcollector.yaml).\n\nTo edit configuration in cluster, run:\n\n```bash\nkubectl edit flowcollector cluster\n```\n\nAs it operates cluster-wide on every node, only a single `FlowCollector` is allowed, and it has to be named `cluster`.\n\nA couple of settings deserve special attention:\n\n- Agent features (`spec.agent.ebpf.features`) can enable more features such as tracking packet drops, TCP latency (RTT) and DNS requests and responses.\n\n- Sampling `spec.agent.ebpf.sampling`: a value of `100` means: one packet every 100 is sampled. `1` means all packets are sampled. The lower it is, the more flows you get, and the more accurate are derived metrics, but the higher amount of resources are consumed. By default, sampling is set to 50 (ie. 1:50). Note that more sampled packets also means more storage needed. We recommend to start with default values and refine empirically, to figure out which setting your cluster can manage.\n\n- Loki (`spec.loki`): configure here how to reach Loki. The default URL values match the Loki quick install paths mentioned in the _Getting Started_ section, but you may have to configure differently if you used another installation method. You will find more information in our guides for deploying Loki: [with Loki Operator](https://github.com/netobserv/documents/blob/main/loki_operator.md), or an alternative [\"distributed Loki\" guide](https://github.com/netobserv/documents/blob/main/loki_distributed.md). You should set `spec.loki.mode` according to the chosen installation method, for instance use `LokiStack` if you use the Loki Operator. Make sure to disable Loki (`spec.loki.enable`) if you don't want to use it.\n\n- Quick filters (`spec.consolePlugin.quickFilters`): configure preset filters to be displayed in the Console plugin. They offer a way to quickly switch from filters to others, such as showing / hiding pods network, or infrastructure network, or application network, etc. They can be tuned to reflect the different workloads running on your cluster. For a list of available filters, [check this page](./docs/QuickFilters.md).\n\n- Kafka (`spec.deploymentModel: Kafka` and `spec.kafka`): when enabled, integrates the flow collection pipeline with Kafka, by splitting ingestion from transformation (kube enrichment, derived metrics, ...). Kafka can provide better scalability, resiliency and high availability. It's also an option to consider when you have a bursty traffic. [This page](https://www.redhat.com/en/topics/integration/what-is-apache-kafka) provides some guidance on why to use Kafka. When configured to use Kafka, NetObserv operator assumes it is already deployed and a topic is created. For convenience, we provide a quick deployment using [Strimzi](https://strimzi.io/): run `make deploy-kafka` from the repository.\n\n- Exporters (`spec.exporters`) an optional list of exporters to which to send enriched flows. Currently, KAFKA and IPFIX are available (only KAFKA being actively maintained). This allows you to define any custom storage or processing that can read from Kafka or from an IPFIX collector.\n\n- To enable availability zones awareness, set `spec.processor.addZone` to `true`.\n\n### Metrics\n\nMore information on Prometheus metrics is available in a dedicated page: [Metrics.md](./docs/Metrics.md).\n\n### Performance fine-tuning\n\nIn addition to sampling and using Kafka or not, other settings can help you get an optimal setup, with or without compromising on the observability.\n\nHere is what you should pay attention to:\n\n- eBPF agent's cache eviction interval (`spec.agent.ebpf.cacheActiveTimeout`) controls how often flows are reported by the agents. The higher it is, the more aggregated the flows are, which results in less traffic sent by the agents themselves, and also ties with less CPU load. But on the flip side, it leads to a slightly higher memory consumption in the agent, and generates more latency in the flow collection. It must be configured in relation with the max flows parameters (`spec.agent.ebpf.cacheMaxFlows`), which defines the size of the eBPF data structures, to make sure there is always enough room for new flows. There is [a blog entry](https://netobserv.io/posts/performance-fine-tuning-a-deep-dive-in-ebpf-agent-metrics/) dedicated to this tuning.\n\n- It is possible to reduce the overall observed traffic by restricting or excluding interfaces via `spec.agent.ebpf.interfaces` and `spec.agent.ebpf.excludeInterfaces`. Note that the interface names may vary according to the CNI used.\n\n- You can also add [eBPF filters](https://netobserv.io/posts/enhancing-netobserv-by-introducing-multi-rules-flow-filtering-capability-in-ebpf/) and [flowlogs-pipeline filters](https://github.com/netobserv/flowlogs-pipeline/blob/main/docs/filtering.md) to further narrow down what's being collected, if you find that you don't need every kind of flows. The former has the greatest impact on the performance of each component, while the latter mainly improves the storage/Loki end of the pipeline.\n\n- Resource requirements and limits (`spec.agent.ebpf.resources`, `spec.agent.processor.resources`): adapt the resource requirements and limits to the load and memory usage you expect on your cluster. The default limits (800MB) should be sufficient for most medium sized clusters. You can read more about reqs and limits [here](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/).\n\n- Each component offers more advanced settings via `spec.agent.ebpf.advanced`, `spec.processor.advanced`, `spec.loki.advanced` and `spec.consolePlugin.advanced`. The agent has [environment variables](https://github.com/netobserv/netobserv-ebpf-agent/blob/main/docs/config.md) that you can set through `spec.agent.ebpf.advanced.env`.\n\n#### Loki\n\nThe `FlowCollector` resource includes configuration of the Loki client, which is used by the processor (`flowlogs-pipeline`) to connect and send data to Loki for storage. They impact two things: batches and retries.\n\n- `spec.loki.writeBatchWait` and `spec.loki.writeBatchSize` control the batching mechanism, ie. how often data is flushed out to Loki. Like in the eBPF agent batching, higher values will generate fewer traffic and consume less CPU, however it will increase a bit the memory consumption of `flowlogs-pipeline`, and may increase a bit collection latency.\n\n- `spec.loki.advanced.writeMinBackoff`, `spec.loki.writeMaxBackoff` and `spec.loki.writeMaxRetries` control the retry mechanism. Retries may happen when Loki is unreachable or when it returns errors. Often, it is due to the rate limits configured on Loki server. When such situation occurs, it might not always be the best solution to increase rate limits (on server configuration side) or to increase retries. Increasing rate limits will put more pressure on Loki, so expect more memory and CPU usage, and also more traffic. Increasing retries will put more pressure on `flowlogs-pipeline`, as it will retain data for longer and accumulate more flows to send. When all the retry attempts fail, flows are simply dropped. Flow drops are counted in the metric `netobserv_loki_dropped_entries_total`.\n\nOn the Loki server side, configuration differs depending on how Loki was installed, e.g. via Helm chart, Loki Operator, etc. Nevertheless, here are a couple of settings that may impact the flow processing pipeline:\n\n- Rate limits ([cf Loki documentation](https://grafana.com/docs/loki/latest/configuration/#limits_config)), especially ingestion rate limit, ingestion burst size, per-stream rate limit and burst size. When these rate limits are reached, Loki returns an error when `flowlogs-pipeline` tries to send batches, visible in logs. A good practice is to define an alert, to get notified when these limits are reached: [cf this example](https://github.com/netobserv/documents/blob/main/examples/distributed-loki/alerting/loki-ratelimit-alert.yaml). It uses a metrics provided by the Loki operator: `loki_request_duration_seconds_count`. In case you don't use the Loki operator, you can replace it by the same metric provided by NetObserv Loki client, named `netobserv_loki_request_duration_seconds_count`.\n\n- Max active streams / max streams per user: this limit is reached when too many streams are created. In Loki terminology, a stream is a given set of labels (keys and values) used for indexing. NetObserv defines labels for source and destination namespaces and pod owners (ie. aggregated workloads, such as Deployments). So the more workloads are running and generating traffic on the cluster, the more chances there are to hit this limit, when it's set. We recommend setting a high limit or turning it off (0 stands for unlimited).\n\n#### With Kafka\n\nMore performance fine-tuning is possible when using Kafka, ie. with `spec.deploymentModel` set to `Kafka`:\n\n- You can set the size of the batches (in bytes) sent by the eBPF agent to Kafka, with `spec.agent.ebpf.kafkaBatchSize`. It has a similar impact than `cacheMaxFlows` mentioned above, with higher values generating less traffic and less CPU usage, but more memory consumption and more latency. We expect the default values to be a good fit for most environments.\n\n- If you find that the Kafka consumer might be a bottleneck, you can increase the number of replicas with `spec.processor.kafkaConsumerReplicas`, or set up an horizontal autoscaler with `spec.processor.kafkaConsumerAutoscaler`.\n\n- Other advanced settings for Kafka include `spec.processor.kafkaConsumerQueueCapacity`, that defines the capacity of the internal message queue used in the Kafka consumer client, and `spec.processor.kafkaConsumerBatchSize`, which indicates to the broker the maximum batch size, in bytes, that the consumer will read.\n\n\n### Securing data and communications\n\n#### Authorizations\n\nNetObserv is meant to be used by cluster admins, or, when using the Loki Operator (v5.7 or above), project admins (ie. users having admin permissions on some namespaces only). Multi-tenancy is based on namespaces permissions, with allowed users able to get flows limited to their namespaces. Flows across two namespaces will be visible to them as long as they have access to at least one of these namespaces.\n\nSince `FlowCollector v1beta2`, NetObserv is automatically configured with multi-tenancy enabled when `spec.loki.mode` is `LokiStack`.\n\nTo give flow logs access to a `test` user, run:\n\n```bash\noc adm policy add-cluster-role-to-user netobserv-loki-reader test\n```\n\nMore information about multi-tenancy can be found on [this page](https://github.com/netobserv/documents/blob/main/multitenancy.md).\n\n#### Network Policy\n\nFor a production deployment, it is highly recommended to lock down the `netobserv` namespace (or wherever NetObserv is installed) using network policies.\n\nYou can set `spec.networkPolicy.enable` to `true` to make NetObserv install automatically a network policy. The policy may need to be fined-tuned for your environment (e.g. for access to kube apiserver, or Prometheus), by adding authorized namespaces. More information [here](./docs/NetworkPolicy.md).\n\n#### Communications\n\nInternal communications may be encrypted, depending on the configuration:\n\n- Between eBPF agents and flowlogs-pipeline, depending on `deploymentModel`:\n  - `Service` (default): it uses TLS by default.\n  - `Kafka`: it is unencrypted by default and can be configured via `spec.kafka.tls` (mTLS is also supported here).\n  - `Direct`: it is unencrypted, but limited to localhost.\n- Communications to Loki:\n  - When Loki mode is `LokiStack`, TLS is used.\n  - In other modes, it is unencrypted by default and can be configured via `spec.loki.tls`.\n- The operator webhooks and the console plugin server always use TLS.\n\n## Architecture\n\nPlease refer to [the Architecture page](./docs/Architecture.md).\n\n## Development \u0026 building from sources\n\nPlease refer to [this documentation](./DEVELOPMENT.md) for everything related to building, deploying or bundling from sources.\n\n## F.A.Q / Troubleshooting\n\nPlease refer to [F.A.Q / Troubleshooting main document](./FAQ.md).\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 the CNCF slack (to create an account get an invite from https://slack.cncf.io/).\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. You will also [find here](./DEVELOPMENT.md) some help on how to build, run and test your code changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetobserv%2Fnetobserv-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetobserv%2Fnetobserv-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetobserv%2Fnetobserv-operator/lists"}