Cilium Hubble: eBPF Network and Security Observability for Kubernetes

The gap Hubble fills in a Cilium cluster

Kubernetes tells you a pod exists and whether its readiness probe passed. It does not tell you which service is opening connections to which database, which DNS lookups are returning NXDOMAIN, or which connection was dropped by a network policy. Hubble exists to answer those questions. The README frames it as a fully distributed networking and security observability platform for cloud native workloads, built on Cilium and eBPF.

The audience is specific. If you run Cilium as your CNI, Hubble is the observation surface for the data Cilium is already processing. The README's list of questions is a fair description of the intended user: someone debugging service-to-service connectivity, DNS resolution failures, interrupted TCP connections, HTTP 4xx and 5xx rates, or connections blocked by policy. Because visibility comes from eBPF at the kernel level, applications do not need to be instrumented, restarted, or aware that they are being observed. That is the property that separates Hubble from application-level tracing, and it is also the property that limits it: Hubble sees what crosses the network stack, not what happens inside a process after a request arrives.

How the CLI, server, relay and UI divide the work

Hubble is not a single binary. The README's component stability table names five pieces: the Hubble CLI, the Hubble Server, Hubble Metrics, Hubble Relay and Hubble UI. The server runs where the eBPF datapath runs, which in a Cilium deployment means per node, and it is what turns kernel events into a flow stream. Relay aggregates those per-node streams so a client does not have to query every node individually, and the README classifies it under the Multinode area. The CLI is the client that consumes the stream, including through relay.

The stability table is worth reading before you build on any of this. CLI, Server and Metrics are marked Stable. Relay is Stable but listed under Multinode. Hubble UI is marked Beta, with the README noting that some components are relatively young and have to be used with caution in critical production workloads. That is an unusually candid statement from a project in this space, and it should shape how you deploy the UI versus the CLI.

The repository itself is the CLI. The Makefile sets TARGET=hubble and builds from the repository root, and go.mod declares the module as github.com/cilium/hubble with a direct dependency on github.com/cilium/cilium v1.19.4. The README states that the Hubble CLI is backward compatible with all supported Cilium releases, which is why only the latest CLI version is maintained. Practically, that means you upgrade the CLI freely and treat the Cilium version as the constraint.

Installing the Hubble CLI and reading your first flows

The README's Getting Started section does not contain install commands. It points to two documents: Introduction to Cilium & Hubble and Networking and Security Observability with Hubble, both under docs.cilium.io. So the authoritative install path lives outside this repository. What the repository does give you is the build recipe. The Makefile builds a static binary with CGO disabled, stamping the version from the Cilium module and the git branch and hash into the binary.

If you build from source, the target is `hubble` and the output binary is written to the repository root by default:

make hubble
./hubble --help

The Makefile also defines a `release` target that runs the build inside a pinned golang image, and an install path that defaults to `/usr/local/bin`, overridable through BINDIR. Once the CLI is on your PATH, the README's flow visibility examples show the shape of real use. This one lists DNS responses that indicate failure over the last minute and counts them per destination pod:

hubble observe --since=1m -t l7 -o json \
   | jq 'select(.l7.dns.rcode==3) | .destination.namespace + "/" + .destination.pod_name' \
   | sort | uniq -c | sort -r

The README shows the expected output as a count followed by a namespace and pod name, for example `42 "starwars/jar-jar-binks-6f5847c97c-qmggv"`. The `-t l7` filter restricts output to layer 7 events and `-o json` switches to structured output for jq. A successful DNS exchange in the README's output shows a query line and an answer line between a pod and coredns, which is what you should see if resolution is healthy.

For metrics rather than flows, the README points to the Metrics Documentation under docs.cilium.io and lists example categories: networking behavior, network policy observation, HTTP request and response rate and latency, and DNS request and response monitoring. The exact metric names are not in this repository's README, so treat the linked documentation as the source of truth before you write alert rules.

What Hubble cannot see, and when it is the wrong tool

The most important limitation is structural: Hubble is built on top of Cilium. If your cluster runs a different CNI, or no CNI beyond the default, there is no eBPF datapath feeding Hubble and the tool has nothing to observe. This is not a configuration problem you can work around. The README describes Hubble as built on Cilium and eBPF, and the component model assumes Cilium's per-node datapath.

The second limitation is the UI's maturity. The README's own stability table marks Hubble UI as Beta and warns that components in that state have to be used with caution in critical production workloads. A service map is a genuinely useful artifact during an incident, but if your on-call workflow depends on a Beta component staying up, you are taking on risk the project has explicitly flagged.

The third is scope. Hubble observes network and application protocol behavior at L3, L4 and L7 for the protocols Cilium understands, which the README lists as TCP connections, DNS queries, HTTP requests and Kafka communication among others. It does not replace application performance monitoring inside your services, and it does not tell you why a handler was slow once the request has been accepted. If your problem is CPU inside a container, Hubble is the wrong tool. If your problem is that a request never arrived, it is the right one.

How Hubble differs from a service mesh's telemetry

The closest alternative for most teams is the observability that comes bundled with a service mesh, typically sidecar or per-node proxy telemetry over mTLS. The difference in approach is where the data is produced. A mesh observes traffic at the proxy, so it sees exactly what the proxy sees, including HTTP headers and gRPC status codes, and it works on any CNI because the proxy sits in the request path. Hubble observes at the kernel, below the proxy and below the application, so it sees connections that never reach a proxy: traffic to a database, DNS lookups, connections dropped by policy before any application code runs.

That difference cuts both ways. Kernel-level observation means no application change and no proxy in the path, which the README describes as transparent visibility. It also means fewer application-layer semantics than a proxy that terminates the protocol. A mesh can rewrite and retry; Hubble only reports. For teams already running a mesh, the two are complementary rather than competing, and the decision is which layer answers the question in front of you. For teams on Cilium without a mesh, Hubble is the lower-effort option because it requires no additional data plane component.

Maintenance, version compatibility and licence

The repository was last pushed on 2026-09-22 and is not archived. Recent releases are v1.19.4 on 2026-06-05, v1.19.3 on 2026-04-22 and v1.18.6 on 2026-02-09. The README's release table lists v1.19 as maintained and supported against Cilium 1.19 and older, and states that only the latest Hubble CLI version is maintained because the CLI is backward compatible with supported Cilium releases.

That policy has a concrete consequence for upgrade planning: your Hubble CLI is a rolling dependency you can update on its own schedule, while the Hubble server moves with Cilium. You cannot upgrade the server independently of the CNI, because the server ships as part of Cilium rather than as a standalone deployment in this repository. Check the compatibility table before assuming a newer CLI will talk to an older Cilium.

The licence is Apache-2.0, declared in the README badge and present as a LICENSE file at the repository root. Apache-2.0 is permissive and includes an explicit patent grant, which matters for a project that implements kernel-level networking behaviour. This is a description of the licence, not legal advice; if you redistribute Hubble inside a product, have counsel review the notice and attribution requirements.

Editorial conclusion

Adopt Hubble if you already run Cilium and need per-connection visibility, DNS and HTTP failure data, or a service map without instrumenting code. Do not adopt it if you are not on Cilium, or if you need stable multi-cluster UI workflows, since the project itself lists Hubble UI as Beta. Before rolling it out, verify that your Cilium version is covered by the compatibility table, that hubble observe returns flows from a pod on a node you care about, and that the metrics you plan to alert on are actually exported.

Frequently asked questions

Official sources

1. cilium/hubble on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases