# camilb/prometheus-kubernetes architecture

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

- Interactive diagram: https://gitdiagram.com/camilb/prometheus-kubernetes
- Repository: https://github.com/camilb/prometheus-kubernetes

## Overview

##### Project type and purpose
- This is an open‑source Kubernetes monitoring “stack” for AWS/GCP/Azure clusters, delivered as pure manifests, scripts and assets (no Helm).
- It provides a turnkey Prometheus Operator‑based solution, comprising Prometheus v2, Alertmanager, Grafana, and exporters (node‑exporter, kube‑state‑metrics, cAdvisor) all wired together by Kubernetes ServiceMonitors/CRDs.

##### Key directories and what they imply
- assets/…: user‑modifiable configuration templates (Alertmanager YAML, Grafana dashboards, Prometheus rules)
- manifests/…: Kubernetes YAML definitions organized by component (alertmanager, grafana, prometheus, exporters, self‑hosted core‑k8s)
- scripts/: helper scripts to assemble ConfigMaps or Secrets from assets
- tools/: shell wrappers for ingress, port‑forwarding and custom‑configuration workflows
- deploy & teardown: entry‑point scripts that apply or delete the whole monitoring stack

##### Main components
a. Kubernetes Cluster
- API Server & Control Plane (Scheduler, Controller Manager) – these are monitored via ServiceMonitors in manifests/k8s/self‑hosted
- Worker Nodes running kubelet, kube‑proxy, Docker/Container runtime
b. Prometheus Operator (Deployment + CRDs)
- Watches ServiceMonitor, Prometheus, Alertmanager CRs
- Dynamically instantiates Prometheus StatefulSet, Alertmanager StatefulSet, Service objects, RBAC
c. Prometheus StatefulSet
- Scrapes metrics from:
– kube‑api, kubelet (10250/TCP)
– kube‑dns (10054/10055)
– node‑exporter DaemonSet on each node (9100/TCP)
– kube‑state‑metrics Deployment
– Prometheus Operator metrics, Kubernetes components
- Persists TSDB in PVC
d. Alertmanager StatefulSet
- Receives alerts from Prometheus
- Routes notifications via email (SMTP) or Slack (token)
e. Grafana Deployment
- Reads dashboards from ConfigMaps (generated by scripts)
- Queries Prometheus via HTTP Service
f. Exporters & Metrics Providers
- node‑exporter (DaemonSet + Service) – host metrics
- kube‑state‑metrics (Deployment + Service) – cluster object metrics
- (Optional) cAdvisor on host port 4194 for container metrics on K8s ≥1.12
g. Ingress / Proxies (optional)
- NGINX Ingress Controller + BasicAuth Secret
- tools/*_proxy.sh for local port‑forwarding

##### Architectural patterns & design principles
- Operator pattern: declarative CRDs drive dynamic creation of StatefulSets, RBAC, Services
- Separation of concerns:
- Stateful workloads (Prometheus, Alertmanager)
- Stateless dashboards (Grafana)
- DaemonSets for per‑node exporters
- Dedicated namespace (e.g. “monitoring”)
- Immutability: YAML manifests under version control, generated ConfigMaps via scripts
- Extensibility: assets/ and tools/custom‑configuration allow injection of custom dashboards, alert rules, Prometheus operator flags

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        direction TB
        APIServer["API Server"]:::coreComp
        Scheduler["Scheduler"]:::coreComp
        Controller["Controller Manager"]:::coreComp
        DNS["kube-dns"]:::coreComp
        Worker["Worker Nodes"]:::coreComp
    end

    %% Monitoring Namespace
    subgraph "Namespace: monitoring"
        direction TB

        ServiceMonitors["ServiceMonitor CRDs"]:::crd
        Operator["Prometheus Operator\n(CRDs & Controller)"]:::operator
        PromStateful["Prometheus StatefulSet"]:::stateful
        AlertStateful["Alertmanager StatefulSet"]:::stateful
        GrafanaDep["Grafana Deployment"]:::stateless
        NodeExporter["node-exporter DaemonSet"]:::exporter
        KSM["kube-state-metrics Deployment"]:::exporter
        PromPVC[(Prometheus PVC)]:::pvc
        AlertPVC[(Alertmanager PVC)]:::pvc
    end

    %% External Integrations
    SMTP[(SMTP / Slack)]:::external
    Ingress["NGINX Ingress Controller"]:::optional
    ProxyTools["kubectl Proxy Tools"]:::optional

    %% Asset & Scripts
    Assets["User Asset Templates"]:::assets
    Scripts["ConfigMap/Secret Generation Scripts"]:::scripts
    CustomConf["Custom Configuration Overrides"]:::optional

    %% Relationships
    ServiceMonitors --> Operator
    Operator -->|"manages StatefulSets/Services"| PromStateful
    Operator -->|"manages StatefulSets/Services"| AlertStateful

    %% Scraping flows
    NodeExporter -->|"HTTP scrape - 9100/TCP"| PromStateful
    KSM -->|"HTTP scrape - 8080/TCP"| PromStateful
    APIServer -->|"HTTP scrape - 443/TCP"| PromStateful
    Controller -->|"HTTP scrape - metrics/TCP"| PromStateful
    Scheduler -->|"HTTP scrape - metrics/TCP"| PromStateful
    DNS -->|"HTTP scrape - 10055/TCP"| PromStateful
    Worker -.->|"hosts node-exporter"| NodeExporter

    PromStateful --> PromPVC
    AlertStateful --> AlertPVC

    %% Alerting and visualization
    PromStateful -->|"alerts API"| AlertStateful
    AlertStateful -->|"routes notifications"| SMTP
    GrafanaDep -->|"query API - HTTP"| PromStateful

    %% Assets and scripts pipeline
    Assets -->|"generate ConfigMaps"| Scripts
    Scripts -->|"populate manifests"| GrafanaDep
    Scripts -->|"populate manifests"| PromStateful
    Scripts -->|"populate manifests"| AlertStateful

    %% Ingress and proxy
    Ingress -->|"expose UIs"| GrafanaDep
    Ingress -->|"expose UIs"| PromStateful
    Ingress -->|"expose UIs"| AlertStateful
    ProxyTools -->|"port-forward UIs"| GrafanaDep
    ProxyTools -->|"port-forward UIs"| PromStateful
    ProxyTools -->|"port-forward UIs"| AlertStateful

    %% External custom overrides
    CustomConf -->|"override manifests"| PromStateful

    %% Click Events
    click APIServer "https://github.com/camilb/prometheus-kubernetes/tree/master/manifests/k8s/self-hosted/"
    click Scheduler "https://github.com/camilb/prometheus-kubernetes/tree/master/manifests/k8s/self-hosted/"
    click Controller "https://github.com/camilb/prometheus-kubernetes/tree/master/manifests/k8s/self-hosted/"
    click DNS "https://github.com/camilb/prometheus-kubernetes/tree/master/manifests/k8s/self-hosted/"
    click Operator "https://github.com/camilb/prometheus-kubernetes/tree/master/manifests/prometheus-operator/"
    click PromStateful "https://github.com/camilb/prometheus-kubernetes/tree/master/manifests/prometheus/"
    click AlertStateful "https://github.com/camilb/prometheus-kubernetes/tree/master/manifests/alertmanager/"
    click GrafanaDep "https://github.com/camilb/prometheus-kubernetes/tree/master/manifests/grafana/"
    click NodeExporter "https://github.com/camilb/prometheus-kubernetes/tree/master/manifests/node-exporter/"
    click KSM "https://github.com/camilb/prometheus-kubernetes/tree/master/manifests/kube-state-metrics/"
    click Assets "https://github.com/camilb/prometheus-kubernetes/tree/master/assets/"
    click Scripts "https://github.com/camilb/prometheus-kubernetes/tree/master/scripts/"
    click Ingress "https://github.com/camilb/prometheus-kubernetes/tree/master/tools/ingress/"
    click ProxyTools "https://github.com/camilb/prometheus-kubernetes/tree/master/tools/"
    click CustomConf "https://github.com/camilb/prometheus-kubernetes/tree/master/tools/custom-configuration/"

    %% Styles
    classDef coreComp fill:#cce5ff,stroke:#004085,color:#004085
    classDef operator fill:#d4edda,stroke:#155724,color:#155724
    classDef stateful fill:#fff3cd,stroke:#856404,color:#856404
    classDef stateless fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef exporter fill:#e2e3e5,stroke:#6c757d,color:#6c757d,shape:roundrect
    classDef pvc fill:#e2e3e5,stroke:#6c757d,color:#6c757d,shape:stadium
    classDef crd fill:#d1ecf1,stroke:#0c5460,color:#0c5460
    classDef assets fill:#f0f0f0,stroke:#666666,color:#333333,stroke-dasharray: 5 5
    classDef scripts fill:#f0f0f0,stroke:#666666,color:#333333,stroke-dasharray: 5 5
    classDef optional fill:#fff5e6,stroke:#cc7a00,color:#cc7a00
    classDef external fill:#ffffff,stroke:#999999,color:#999999,shape:cylinder
```
