# cilium/hubble architecture

> Architecture diagram of the GitHub repository cilium/hubble, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cilium/hubble
- Repository: https://github.com/cilium/hubble

## Overview

##### Main Components Overview

a) Core Components (Stable):
- Hubble CLI
- Hubble Server
- Hubble Metrics
- Hubble Relay (Multinode support)
- Hubble UI (Beta)

##### Integration Layer
Integration with:
- Cilium (as the underlying platform)
- eBPF (for deep visibility)
- Kubernetes (as the target environment)

##### Data Flow Architecture

a) Data Collection Layer:
- eBPF hooks in the kernel
- Network flow monitoring points
- Service dependency tracking points

b) Processing Layer:
- Flow visibility processing
- Metrics aggregation
- Service mapping analysis

c) Presentation Layer:
- CLI interface
- UI dashboard
- Metrics endpoints
- Service dependency visualization

##### Specific Design Elements

Use the following visual elements:

##### Component Relationships

Key interactions:
**[Kubernetes Cluster]**
- ↓
**[eBPF (Kernel Level)]**
- ↓
**[Cilium]**
- ↓
**[Hubble Server] ←→ [Hubble Relay]**
- ↓
**[Hubble CLI] [Hubble UI] [Metrics Systems]**

##### Monitoring Features

Dedicated sections for:
- Service Dependency Graph monitoring
- Network Policy enforcement
- HTTP/DNS monitoring
- TCP/UDP flow tracking
- Metrics collection points

##### Integration Points

Connections with:
- CoreDNS for DNS monitoring
- Prometheus for metrics
- Kubernetes API server
- External monitoring tools

##### Implementation Notes

Annotations for:
- eBPF integration points
- Network policy enforcement locations
- Metrics collection endpoints
- API communication paths

For the principal software engineer, emphasize:
- The distributed nature of the system
- The deep integration with kernel-level monitoring
- The scalability aspects of the architecture
- The security observability features
- The multiple monitoring dimensions (L3/L4/L7)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Kernel["Kernel Layer"]
        eBPF["eBPF Hooks"]
    end

    subgraph Platform["Platform Layer"]
        Cilium["Cilium Integration"]
        K8s["Kubernetes"]
        click K8s "https://github.com/cilium/hubble/tree/main/install/kubernetes"
    end

    subgraph Core["Core Components"]
        HS["Hubble Server"]
        HR["Hubble Relay"]
        HC["Hubble CLI"]
        HM["Hubble Metrics"]
        HUI["Hubble UI"]:::beta
        click HS "https://github.com/cilium/hubble/blob/main/main.go"
    end

    subgraph Monitoring["Monitoring Layer"]
        SDG["Service Dependency Graph"]
        NPE["Network Policy Enforcement"]
        HDM["HTTP/DNS Monitoring"]
        FT["TCP/UDP Flow Tracking"]
        MC["Metrics Collection"]
        click NPE "https://github.com/cilium/hubble/blob/main/policies/l7_80_53.yaml"
    end

    subgraph Integration["Integration Points"]
        DNS["CoreDNS"]
        Prom["Prometheus"]
        K8sAPI["Kubernetes API"]
        ExtTools["External Tools"]
    end

    subgraph CI["CI/CD"]
        Tests["Integration Tests"]
        Release["Release Pipeline"]
        QA["Quality Assurance"]
        click Tests "https://github.com/cilium/hubble/blob/main/.github/workflows/integration-tests.yaml"
        click Release "https://github.com/cilium/hubble/blob/main/.github/workflows/release.yml"
    end

    subgraph Docs["Documentation"]
        TechDocs["Technical Documentation"]
        API["API Reference"]
        click TechDocs "https://github.com/cilium/hubble/tree/main/Documentation"
    end

    %% Relationships
    eBPF --> Cilium
    Cilium --> HS
    K8s --> Cilium
    
    HS --> HR
    HR --> HC
    HR --> HUI
    HS --> HM
    
    HS --> SDG
    HS --> NPE
    HS --> HDM
    HS --> FT
    HS --> MC
    
    MC --> Prom
    HDM --> DNS
    HS --> K8sAPI
    MC --> ExtTools

    %% Styling
    classDef default fill:#ddd,stroke:#000,stroke-width:1px
    classDef beta fill:#FFE873,stroke:#000
    classDef stable fill:#7BB2D9,stroke:#000
    classDef external fill:#D9B8D7,stroke:#000
    classDef kernel fill:#C1E1C1,stroke:#000
    
    class eBPF kernel
    class HUI beta
    class HS,HR,HC,HM stable
    class DNS,Prom,K8sAPI,ExtTools external

    %% Legend
    subgraph Legend
        L1["Stable Component"]:::stable
        L2["Beta Component"]:::beta
        L3["External Integration"]:::external
        L4["Kernel Component"]:::kernel
    end
```
