Hubble gRPC API

Active contributors: rolinh, glibsm, michi-covalent, gandro

Services

Defined under api/v1/:

Service	.proto	Description
Observer	api/v1/observer/observer.proto	Stream and query flow events.
Peer	api/v1/peer/peer.proto	Discover peer agents (used by Relay).
Relay	api/v1/relay/relay.proto	Relay-specific service definitions.
Recorder	api/v1/recorder/recorder.proto	pcap-style flow recording.

The flow message itself (api/v1/flow/flow.proto) is the workhorse type returned by Observer.GetFlows.

Stable vs experimental

Observer.GetFlows is the stable API used by the Hubble UI, the hubble CLI, and third-party flow consumers. Other services (Recorder, Peer) are stable but more rarely consumed externally.

Backward compatibility:

• Field numbers are never reused.
• Adding new fields is allowed within a minor version.
• Removing fields requires a major version.
• Stable since Hubble v1.0; field additions across the v1.x line have not broken clients.

Generation

make -C api proto

Uses vendored protoc tools to produce *.pb.go next to each .proto. Buf-style lint config lives in the api/ tree.

Where it is implemented

• Per-node Observer: pkg/hubble/observer/. Reads from the per-agent flow ring buffer (pkg/hubble/container/), applies filters (pkg/hubble/filters/), streams to the client.
• Relay: pkg/hubble/relay/. Connects to every agent's Observer endpoint, fans out a unified stream to clients.
• Peer: pkg/hubble/peer/. Discovers agents; Relay subscribes to changes.
• Recorder: pkg/hubble/recorder/. Programs the recorder BPF map (pkg/maps/recorder/) and exports captured packets.

Examples

The Hubble CLI (hubble/) is the canonical example client:

hubble observe --pod default/foo --verdict DROPPED
hubble observe --type policy-verdict
hubble status   # -> Peer.GetStatus
hubble list nodes  # -> Peer.GetPeers

External consumers connect with any gRPC client. Authentication is mTLS; cert provisioning is handled at install time by cilium hubble enable.

Key source files

File	Purpose
api/v1/flow/flow.proto	Flow message.
api/v1/observer/observer.proto	Observer service.
pkg/hubble/observer/server.go	Per-node implementation.
pkg/hubble/relay/server.go	Cluster-wide aggregator.
pkg/hubble/peer/manager.go	Peer discovery.