asyncapi: 2.6.0 info: title: Cilium Hubble Events description: >- The Hubble event streaming API provides real-time observability into network flows, DNS queries, HTTP requests, and service-to-service communication within Kubernetes clusters. Hubble exposes gRPC-based Observer and Peer services that clients can subscribe to for streaming network visibility data. Events include Layer 3/4 flows with IP and transport metadata, Layer 7 flows with application protocol details, DNS resolution events, and service drop/forward decisions. The Hubble Relay aggregates events from all nodes in a cluster for cluster-wide observability. version: '1.0.0' contact: name: Cilium Community url: https://cilium.io/get-help/ externalDocs: description: Hubble Observability Documentation url: https://docs.cilium.io/en/stable/observability/hubble/ servers: hubbleRelay: url: '{hostname}:4245' protocol: grpc description: >- Hubble Relay gRPC server providing cluster-wide aggregated flow observability. The relay aggregates flows from all Hubble-enabled Cilium agents. variables: hostname: default: hubble-relay.kube-system.svc.cluster.local description: Hostname or IP address of the Hubble Relay service. hubbleLocal: url: '{hostname}:4244' protocol: grpc description: >- Per-node Hubble gRPC server embedded in the Cilium agent, providing local node flow observability. variables: hostname: default: localhost description: Hostname of the Cilium agent node. channels: /observer.Observer/GetFlows: description: >- Streaming channel for network flow events. Clients send a GetFlowsRequest specifying filters and receive a continuous stream of Flow messages representing network connections observed by the eBPF datapath. subscribe: operationId: getFlows summary: Stream network flow events description: >- Subscribes to a real-time stream of network flow events from the Hubble Observer service. Flows include L3/L4 TCP/UDP connections, ICMP packets, and L7 application-layer events for HTTP, DNS, Kafka, gRPC, and other supported protocols. message: $ref: '#/components/messages/Flow' /observer.Observer/GetAgentEvents: description: >- Streaming channel for Cilium agent state change events. Reports significant state transitions in the Cilium agent such as endpoint regeneration, policy updates, and service changes. subscribe: operationId: getAgentEvents summary: Stream agent events description: >- Subscribes to a stream of Cilium agent-level events that reflect changes to endpoint state, policy configuration, service definitions, and identity allocations. message: $ref: '#/components/messages/AgentEvent' /observer.Observer/GetDebugEvents: description: >- Streaming channel for internal Cilium debug events generated by the eBPF datapath, used for troubleshooting and development. subscribe: operationId: getDebugEvents summary: Stream debug events description: >- Subscribes to a stream of low-level eBPF datapath debug events, including policy verdict events, NAT translation events, and load balancer decisions. message: $ref: '#/components/messages/DebugEvent' /observer.Observer/GetNodes: description: >- Streaming channel that provides a snapshot and updates of all Hubble nodes visible to the relay, including their connectivity status. subscribe: operationId: getNodes summary: Stream node status updates description: >- Subscribes to Hubble node status notifications, receiving the current list of connected nodes and subsequent join/leave events. message: $ref: '#/components/messages/NodeStatus' /observer.Observer/GetNamespaces: description: >- Streaming channel providing Kubernetes namespace information visible through network flow data observed by Hubble. subscribe: operationId: getNamespaces summary: Stream namespace updates description: >- Streams the set of Kubernetes namespaces with active network flows observed by the Hubble relay. message: $ref: '#/components/messages/NamespaceStatus' components: messages: Flow: name: Flow title: Network Flow Event summary: A single observed network flow or connection event description: >- Represents a single network event captured by the Cilium eBPF datapath. Flows carry source and destination endpoint information, verdict (forwarded or dropped), Layer 3/4 protocol metadata, and optionally Layer 7 application-layer details for supported protocols. contentType: application/grpc+proto payload: $ref: '#/components/schemas/Flow' AgentEvent: name: AgentEvent title: Cilium Agent Event summary: A state change event from the Cilium agent description: >- Represents a significant state change in the Cilium agent, such as endpoint creation or deletion, policy updates, service changes, or identity allocations. contentType: application/grpc+proto payload: $ref: '#/components/schemas/AgentEvent' DebugEvent: name: DebugEvent title: eBPF Debug Event summary: A low-level debug event from the eBPF datapath description: >- Internal debug event generated by the Cilium eBPF programs, used for troubleshooting datapath behavior. contentType: application/grpc+proto payload: $ref: '#/components/schemas/DebugEvent' NodeStatus: name: NodeStatus title: Hubble Node Status summary: Status notification for a Hubble-enabled node description: >- Notification about the connectivity status of a Hubble node, delivered when nodes join or leave the relay mesh. contentType: application/grpc+proto payload: $ref: '#/components/schemas/NodeStatusEvent' NamespaceStatus: name: NamespaceStatus title: Kubernetes Namespace Status summary: Namespace visibility update from Hubble flow data description: >- Notification about Kubernetes namespaces observed through network flow data collected by Hubble. contentType: application/grpc+proto payload: $ref: '#/components/schemas/NamespaceEvent' schemas: Flow: type: object description: >- A network flow event captured by the Cilium eBPF datapath, representing a connection, packet, or application-layer event. properties: time: type: string format: date-time description: Timestamp when the flow event was observed. verdict: type: string description: Policy verdict applied to this flow. enum: [VERDICT_UNKNOWN, FORWARDED, DROPPED, ERROR, AUDIT] drop_reason: type: integer description: Numeric drop reason code (populated when verdict is DROPPED). ethernet: $ref: '#/components/schemas/Ethernet' IP: $ref: '#/components/schemas/IP' l4: $ref: '#/components/schemas/Layer4' source: $ref: '#/components/schemas/Endpoint' destination: $ref: '#/components/schemas/Endpoint' type: type: string description: Flow type classification. enum: [UNKNOWN_TYPE, L3_L4, L7, SOCK] node_name: type: string description: Name of the node where this flow was observed. source_names: type: array items: type: string description: DNS names resolving to the source IP. destination_names: type: array items: type: string description: DNS names resolving to the destination IP. l7: $ref: '#/components/schemas/Layer7' reply: type: boolean description: Whether this flow is a reply to a previous flow. ingress: type: boolean description: >- Whether this is an ingress flow (true) or egress flow (false) from the perspective of the destination endpoint. event_type: $ref: '#/components/schemas/CiliumEventType' source_service: $ref: '#/components/schemas/Service' destination_service: $ref: '#/components/schemas/Service' traffic_direction: type: string description: Traffic direction relative to the policy enforcement point. enum: [TRAFFIC_DIRECTION_UNKNOWN, INGRESS, EGRESS] policy_match_type: type: integer description: Bitmask indicating which policy types matched. summary: type: string description: Human-readable summary of the flow event. Ethernet: type: object description: Ethernet frame header information. properties: source: type: string description: Source MAC address. destination: type: string description: Destination MAC address. IP: type: object description: IP layer header information for a flow. properties: source: type: string description: Source IP address. destination: type: string description: Destination IP address. ipVersion: type: string description: IP version. enum: [IP_NOT_USED, IPv4, IPv6] encrypted: type: boolean description: Whether the packet was encrypted (e.g., via WireGuard or IPsec). Layer4: type: object description: Transport layer (L4) protocol information. properties: TCP: $ref: '#/components/schemas/TCP' UDP: $ref: '#/components/schemas/UDP' ICMPv4: $ref: '#/components/schemas/ICMPv4' ICMPv6: $ref: '#/components/schemas/ICMPv6' TCP: type: object description: TCP segment metadata. properties: source_port: type: integer description: TCP source port number. destination_port: type: integer description: TCP destination port number. flags: type: object description: TCP flag bits set on this segment. properties: FIN: type: boolean SYN: type: boolean RST: type: boolean PSH: type: boolean ACK: type: boolean URG: type: boolean UDP: type: object description: UDP datagram metadata. properties: source_port: type: integer description: UDP source port number. destination_port: type: integer description: UDP destination port number. ICMPv4: type: object description: ICMPv4 message metadata. properties: type: type: integer description: ICMP message type. code: type: integer description: ICMP message code. ICMPv6: type: object description: ICMPv6 message metadata. properties: type: type: integer description: ICMPv6 message type. code: type: integer description: ICMPv6 message code. Layer7: type: object description: Application layer (L7) protocol information for supported protocols. properties: type: type: string description: L7 event type (request, response, sample). enum: [UNKNOWN_L7_TYPE, REQUEST, RESPONSE, SAMPLE] latency_ns: type: integer format: int64 description: Round-trip latency in nanoseconds (populated for response events). dns: $ref: '#/components/schemas/DNS' http: $ref: '#/components/schemas/HTTP' kafka: $ref: '#/components/schemas/Kafka' DNS: type: object description: DNS query or response details for L7 DNS flow events. properties: query: type: string description: DNS query name. ips: type: array items: type: string description: IP addresses in the DNS response. ttl: type: integer description: DNS TTL value. cnames: type: array items: type: string description: CNAME records in the response. observation_source: type: string description: Source of the DNS observation (proxy or socket). rcode: type: integer description: DNS response code. qtypes: type: array items: type: string description: DNS query types (A, AAAA, CNAME, etc.). rrtypes: type: array items: type: string description: DNS resource record types in the response. HTTP: type: object description: HTTP request or response details for L7 HTTP flow events. properties: code: type: integer description: HTTP response status code. method: type: string description: HTTP request method (GET, POST, PUT, DELETE, etc.). url: type: string description: Full request URL. protocol: type: string description: HTTP protocol version (HTTP/1.1, HTTP/2). headers: type: array items: type: object properties: key: type: string description: Header field name. value: type: string description: Header field value. description: HTTP headers from request or response. Kafka: type: object description: Kafka protocol details for L7 Kafka flow events. properties: error_code: type: integer description: Kafka error code. api_version: type: integer description: Kafka API version. api_key: type: integer description: Kafka API key (operation type). correlation_id: type: integer description: Kafka correlation ID for request/response matching. topic: type: string description: Kafka topic name. Endpoint: type: object description: Network endpoint identified in a flow event. properties: ID: type: integer format: int64 description: Numeric Cilium endpoint ID. identity: type: integer format: int64 description: Cilium security identity ID. namespace: type: string description: Kubernetes namespace. labels: type: array items: type: string description: Security labels associated with this endpoint. pod_name: type: string description: Kubernetes pod name. workloads: type: array items: $ref: '#/components/schemas/Workload' description: Kubernetes workload information for this endpoint. Workload: type: object description: Kubernetes workload associated with an endpoint. properties: name: type: string description: Workload name (Deployment, StatefulSet, DaemonSet name). kind: type: string description: Kubernetes workload kind. Service: type: object description: Kubernetes service associated with a flow endpoint. properties: name: type: string description: Service name. namespace: type: string description: Kubernetes namespace of the service. CiliumEventType: type: object description: Cilium monitor event type information. properties: type: type: integer description: Cilium monitor event type code. sub_type: type: integer description: Cilium monitor event sub-type code. AgentEvent: type: object description: A state change event emitted by the Cilium agent. properties: type: type: string description: Type of agent event. enum: - AGENT_EVENT_UNKNOWN - AGENT_STARTED - POLICY_UPDATED - POLICY_DELETED - ENDPOINT_REGENERATE_SUCCESS - ENDPOINT_REGENERATE_FAILURE - ENDPOINT_CREATED - ENDPOINT_DELETED - IPCACHE_UPSERTED - IPCACHE_DELETED - SERVICE_UPSERTED - SERVICE_DELETED agent_start: $ref: '#/components/schemas/AgentStart' policy_update: $ref: '#/components/schemas/PolicyUpdate' endpoint_regenerate: $ref: '#/components/schemas/EndpointRegenerate' endpoint_update: $ref: '#/components/schemas/EndpointUpdate' ipcache_update: $ref: '#/components/schemas/IPCacheUpdate' service_upsert: $ref: '#/components/schemas/ServiceUpsert' service_delete: $ref: '#/components/schemas/ServiceDelete' AgentStart: type: object description: Cilium agent startup event details. properties: time: type: string format: date-time description: Time when the agent started. PolicyUpdate: type: object description: Details of a policy add or delete event. properties: labels: type: array items: type: string description: Labels of the updated policy rule. revision: type: integer format: int64 description: New policy revision number after the update. rule_count: type: integer format: int64 description: Total number of active policy rules after the update. EndpointRegenerate: type: object description: Details of an endpoint regeneration event. properties: id: type: integer format: int64 description: Endpoint ID that was regenerated. labels: type: array items: type: string description: Security labels of the regenerated endpoint. error: type: string description: Error message if regeneration failed. EndpointUpdate: type: object description: Details of an endpoint creation or deletion event. properties: id: type: integer format: int64 description: Endpoint ID. labels: type: array items: type: string description: Security labels of the endpoint. pod_name: type: string description: Kubernetes pod name associated with this endpoint. namespace: type: string description: Kubernetes namespace of the endpoint. IPCacheUpdate: type: object description: Details of an IP cache (identity mapping) update event. properties: cidr: type: string description: CIDR prefix being upserted or deleted. identity: type: integer description: Security identity associated with this CIDR. old_identity: type: integer description: Previous identity (for upsert events showing a change). hostIP: type: string description: Host IP address associated with this entry. oldHostIP: type: string description: Previous host IP address. encryptKey: type: integer description: Encryption key index. namespace: type: string description: Kubernetes namespace associated with this entry. podName: type: string description: Kubernetes pod name associated with this entry. ServiceUpsert: type: object description: Details of a service creation or update event. properties: id: type: integer description: Cilium service numeric ID. frontend_address: $ref: '#/components/schemas/ServiceAddress' backend_addresses: type: array items: $ref: '#/components/schemas/BackendAddress' description: Backend endpoint addresses for this service. type: type: string description: Kubernetes service type. traffic_policy: type: string description: Traffic routing policy. name: type: string description: Service name. namespace: type: string description: Service namespace. ServiceAddress: type: object description: IP address and port for a service frontend or backend. properties: ip: type: string description: IP address. port: type: integer description: Port number. proto: type: string description: Protocol (TCP, UDP, SCTP). BackendAddress: type: object description: Backend address details in a service event. properties: ip: type: string description: Backend IP address. port: type: integer description: Backend port. nodeName: type: string description: Node hosting this backend. ServiceDelete: type: object description: Details of a service deletion event. properties: id: type: integer description: Cilium service ID that was deleted. DebugEvent: type: object description: A low-level debug event from the eBPF datapath. properties: type: type: string description: Debug event type. enum: - DBG_EVENT_UNKNOWN - DBG_GENERIC - DBG_LOCAL_DELIVERY - DBG_ENCAP - DBG_LXC_FOUND - DBG_POLICY_DENIED - DBG_CT_VERDICT source: $ref: '#/components/schemas/Endpoint' hash: type: integer description: Event hash for correlation. arg1: type: integer description: First event-type-specific argument. arg2: type: integer description: Second event-type-specific argument. arg3: type: integer description: Third event-type-specific argument. message: type: string description: Human-readable debug message. cpu: type: integer description: CPU core that generated this debug event. NodeStatusEvent: type: object description: Status notification for a Hubble-enabled Cilium node. properties: state: type: string description: Node connection state. enum: [UNKNOWN_NODE_STATE, NODE_CONNECTED, NODE_UNAVAILABLE, NODE_GONE, NODE_ERROR] name: type: string description: Node name. message: type: string description: Additional state message or error description. tls: type: object description: TLS certificate information for this node's Hubble server. NamespaceEvent: type: object description: Kubernetes namespace observed through Hubble flow data. properties: namespace: type: object description: Namespace identifier. properties: cluster: type: string description: Cluster name (for multi-cluster setups). namespace: type: string description: Kubernetes namespace name.