Cilium Hubble Events

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.