Protocol Documentation

Table of Contents

• observer/observer.proto

  • ExportEvent

  • GetAgentEventsRequest

  • GetAgentEventsResponse

  • GetDebugEventsRequest

  • GetDebugEventsResponse

  • GetFlowsRequest

  • GetFlowsRequest.Experimental

  • GetFlowsResponse

  • GetNamespacesRequest

  • GetNamespacesResponse

  • GetNodesRequest

  • GetNodesResponse

  • Namespace

  • Node

  • ServerStatusRequest

  • ServerStatusResponse

  • TLS

  • Observer

• Scalar Value Types

Top

observer/observer.proto

ExportEvent

ExportEvent contains an event to be exported. Not to be used outside of the exporter feature.

Field	Type	Label	Description
flow	flow.Flow
node_status	relay.NodeStatusEvent		node_status informs clients about the state of the nodes participating in this particular GetFlows request.
lost_events	flow.LostEvent		lost_events informs clients about events which got dropped due to a Hubble component being unavailable
agent_event	flow.AgentEvent		agent_event informs clients about an event received from the Cilium agent.
debug_event	flow.DebugEvent		debug_event contains Cilium datapath debug events
node_name	string		Name of the node where this event was observed.
time	google.protobuf.Timestamp		Timestamp at which this event was observed.

GetAgentEventsRequest

Field	Type	Label	Description
number	uint64		Number of flows that should be returned. Incompatible with since/until. Defaults to the most recent (last) number events, unless first is true, then it will return the earliest number events.
first	bool		first specifies if we should look at the first number events or the last number of events. Incompatible with follow.
follow	bool		follow sets when the server should continue to stream agent events after printing the last N agent events.
since	google.protobuf.Timestamp		Since this time for returned agent events. Incompatible with number.
until	google.protobuf.Timestamp		Until this time for returned agent events. Incompatible with number.

GetAgentEventsResponse

GetAgentEventsResponse contains an event received from the Cilium agent.

Field	Type	Label	Description
agent_event	flow.AgentEvent
node_name	string		Name of the node where this event was observed.
time	google.protobuf.Timestamp		Timestamp at which this event was observed.

GetDebugEventsRequest

Field	Type	Label	Description
number	uint64		Number of events that should be returned. Incompatible with since/until. Defaults to the most recent (last) number events, unless first is true, then it will return the earliest number events.
first	bool		first specifies if we should look at the first number events or the last number of events. Incompatible with follow.
follow	bool		follow sets when the server should continue to stream debug events after printing the last N debug events.
since	google.protobuf.Timestamp		Since this time for returned debug events. Incompatible with number.
until	google.protobuf.Timestamp		Until this time for returned debug events. Incompatible with number.

GetDebugEventsResponse

GetDebugEventsResponse contains a Cilium datapath debug events.

Field	Type	Label	Description
debug_event	flow.DebugEvent
node_name	string		Name of the node where this event was observed.
time	google.protobuf.Timestamp		Timestamp at which this event was observed.

GetFlowsRequest

Field	Type	Label	Description
number	uint64		Number of flows that should be returned. Incompatible with since/until. Defaults to the most recent (last) number flows, unless first is true, then it will return the earliest number flows.
first	bool		first specifies if we should look at the first number flows or the last number of flows. Incompatible with follow.
follow	bool		follow sets when the server should continue to stream flows after printing the last N flows.
blacklist	flow.FlowFilter	repeated	blacklist defines a list of filters which have to match for a flow to be excluded from the result. If multiple blacklist filters are specified, only one of them has to match for a flow to be excluded.
whitelist	flow.FlowFilter	repeated	whitelist defines a list of filters which have to match for a flow to be included in the result. If multiple whitelist filters are specified, only one of them has to match for a flow to be included. The whitelist and blacklist can both be specified. In such cases, the set of the returned flows is the set difference whitelist - blacklist. In other words, the result will contain all flows matched by the whitelist that are not also simultaneously matched by the blacklist.
since	google.protobuf.Timestamp		Since this time for returned flows. Incompatible with number.
until	google.protobuf.Timestamp		Until this time for returned flows. Incompatible with number.
field_mask	google.protobuf.FieldMask		FieldMask allows clients to limit flow’s fields that will be returned. For example, {paths: [“source.id”, “destination.id”]} will return flows with only these two fields set.
experimental	GetFlowsRequest.Experimental
extensions	google.protobuf.Any		extensions can be used to add arbitrary additional metadata to GetFlowsRequest. This can be used to extend functionality for other Hubble compatible APIs, or experiment with new functionality without needing to change the public API.

GetFlowsRequest.Experimental

Experimental contains fields that are not stable yet. Support for experimental features is always optional and subject to change.

Field	Type	Label	Description
field_mask	google.protobuf.FieldMask		Deprecated. FieldMask allows clients to limit flow’s fields that will be returned. For example, {paths: [“source.id”, “destination.id”]} will return flows with only these two fields set. Deprecated in favor of top-level field_mask. This field will be removed in v1.17.

GetFlowsResponse

GetFlowsResponse contains either a flow or a protocol message.

Field	Type	Label	Description
flow	flow.Flow
node_status	relay.NodeStatusEvent		node_status informs clients about the state of the nodes participating in this particular GetFlows request.
lost_events	flow.LostEvent		lost_events informs clients about events which got dropped due to a Hubble component being unavailable
node_name	string		Name of the node where this event was observed.
time	google.protobuf.Timestamp		Timestamp at which this event was observed.

GetNamespacesRequest

GetNamespacesResponse

GetNamespacesResponse contains the list of namespaces.

Field	Type	Label	Description
namespaces	Namespace	repeated	Namespaces is a list of namespaces with flows

GetNodesRequest

GetNodesResponse

GetNodesResponse contains the list of nodes.

Field	Type	Label	Description
nodes	Node	repeated	Nodes is an exhaustive list of nodes.

Namespace

Field	Type	Label	Description
cluster	string
namespace	string

Node

Node represents a cluster node.

Field	Type	Label	Description
name	string		Name is the name of the node.
version	string		Version is the version of Cilium/Hubble as reported by the node.
address	string		Address is the network address of the API endpoint.
state	relay.NodeState		State represents the known state of the node.
tls	TLS		TLS reports TLS related information.
uptime_ns	uint64		UptimeNS is the uptime of this instance in nanoseconds
num_flows	uint64		number of currently captured flows
max_flows	uint64		maximum capacity of the ring buffer
seen_flows	uint64		total amount of flows observed since the observer was started

ServerStatusRequest

ServerStatusResponse

Field	Type	Label	Description
num_flows	uint64		number of currently captured flows In a multi-node context, this is the cumulative count of all captured flows.
max_flows	uint64		maximum capacity of the ring buffer In a multi-node context, this is the aggregation of all ring buffers capacities.
seen_flows	uint64		total amount of flows observed since the observer was started In a multi-node context, this is the aggregation of all flows that have been seen.
uptime_ns	uint64		uptime of this observer instance in nanoseconds In a multi-node context, this field corresponds to the uptime of the longest living instance.
num_connected_nodes	google.protobuf.UInt32Value		number of nodes for which a connection is established
num_unavailable_nodes	google.protobuf.UInt32Value		number of nodes for which a connection cannot be established
unavailable_nodes	string	repeated	list of nodes that are unavailable This list may not be exhaustive.
version	string		Version is the version of Cilium/Hubble.
flows_rate	double		Approximate rate of flows seen by Hubble per second over the last minute. In a multi-node context, this is the sum of all flows rates.

TLS

TLS represents TLS information.

Field	Type	Label	Description
enabled	bool		Enabled reports whether TLS is enabled or not.
server_name	string		ServerName is the TLS server name that can be used as part of the TLS cert validation process.

Observer

Observer returns a stream of Flows depending on which filter the user want to observe.

Method Name	Request Type	Response Type	Description
GetFlows	GetFlowsRequest	GetFlowsResponse stream	GetFlows returning structured data, meant to eventually obsolete GetLastNFlows.
GetAgentEvents	GetAgentEventsRequest	GetAgentEventsResponse stream	GetAgentEvents returns Cilium agent events.
GetDebugEvents	GetDebugEventsRequest	GetDebugEventsResponse stream	GetDebugEvents returns Cilium datapath debug events.
GetNodes	GetNodesRequest	GetNodesResponse	GetNodes returns information about nodes in a cluster.
GetNamespaces	GetNamespacesRequest	GetNamespacesResponse	GetNamespaces returns information about namespaces in a cluster. The namespaces returned are namespaces which have had network flows in the last hour. The namespaces are returned sorted by cluster name and namespace in ascending order.
ServerStatus	ServerStatusRequest	ServerStatusResponse	ServerStatus returns some details about the running hubble server.

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)