TL;DR

Der Prometheus Operator nutzt ServiceMonitor und PodMonitor als Custom Resources, um Scrape-Targets automatisch zu erkennen. ServiceMonitor findet Apps über Kubernetes Services, PodMonitor scrapt Pods direkt. Beide nutzen Label-Selektoren zur Target-Discovery. Dieser Guide zeigt die Konfiguration für eigene Anwendungen mit konkreten YAML-Beispielen.

Custom Apps mit Prometheus überwachen

Prometheus im Kubernetes-Cluster läuft — aber wie überwachst du deine eigenen Anwendungen? Der Prometheus Operator löst das über zwei Custom Resources: ServiceMonitor für Service-basierte Apps und PodMonitor für direktes Pod-Scraping. Beide ersetzen die manuelle scrape_configs-Pflege in der Prometheus-Konfiguration.

So sieht der typische Ablauf aus:

# Prüfen welche CRDs verfügbar sind
kubectl get crd | grep monitoring.coreos.com

# Erwartete Ausgabe (Auszug):
# podmonitors.monitoring.coreos.com
# servicemonitors.monitoring.coreos.com
# prometheusrules.monitoring.coreos.com

Falls die CRDs fehlen, ist der Prometheus Operator nicht installiert. Der kube-prometheus-stack bringt alles mit.

Wie Target Discovery funktioniert

Der Prometheus Operator beobachtet ServiceMonitor- und PodMonitor-Ressourcen im Cluster. Findet er eine neue Ressource, aktualisiert er automatisch die Prometheus-Konfiguration. Der Ablauf:

1. Du erstellst einen ServiceMonitor mit Label-Selektor
2. Der Operator matcht den Selektor gegen vorhandene Services
3. Prometheus erhält die Endpoints als Scrape-Targets
4. Metriken werden im konfigurierten Intervall abgerufen

Wichtig: Prometheus selektiert ServiceMonitors ebenfalls über Labels. Beim kube-prometheus-stack ist das standardmäßig release: kube-prometheus-stack. Ohne dieses Label auf dem ServiceMonitor wird er ignoriert.

ServiceMonitor: Apps über Services scrapen

Ein ServiceMonitor verbindet sich mit einem Kubernetes Service und scrapt alle dahinter liegenden Pods. Das ist der Standard-Weg für die meisten Anwendungen.

Beispiel: Go-App mit /metrics Endpoint

Deine App exponiert Metriken auf Port 8080 unter /metrics. Der Service:

apiVersion: v1
kind: Service
metadata:
  name: my-go-app
  namespace: production
  labels:
    app: my-go-app
spec:
  selector:
    app: my-go-app
  ports:
    - name: http-metrics
      port: 8080
      targetPort: 8080

Der zugehörige ServiceMonitor:

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: my-go-app-monitor
  namespace: monitoring
  labels:
    release: kube-prometheus-stack
spec:
  namespaceSelector:
    matchNames:
      - production
  selector:
    matchLabels:
      app: my-go-app
  endpoints:
    - port: http-metrics
      path: /metrics
      interval: 30s
      scrapeTimeout: 10s

Drei Dinge sind entscheidend:

ServiceMonitor für mehrere Namespaces

Wenn deine App in mehreren Namespaces läuft:

spec:
  namespaceSelector:
    matchNames:
      - production
      - staging
      - development
  selector:
    matchLabels:
      monitoring: enabled

Oder für alle Namespaces:

spec:
  namespaceSelector:
    any: true
  selector:
    matchLabels:
      monitoring: enabled

PodMonitor: Pods direkt scrapen

Nicht jede App hat einen Service — Batch-Jobs, DaemonSets oder Sidecar-Container werden oft direkt gescrapt. Dafür gibt es den PodMonitor.

apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: batch-jobs-monitor
  namespace: monitoring
  labels:
    release: kube-prometheus-stack
spec:
  namespaceSelector:
    matchNames:
      - batch
  selector:
    matchLabels:
      app: data-processor
  podMetricsEndpoints:
    - port: metrics
      path: /metrics
      interval: 60s

Der Hauptunterschied: Statt endpoints nutzt PodMonitor podMetricsEndpoints, und der Selektor matcht direkt gegen Pod-Labels statt Service-Labels.

Wann PodMonitor statt ServiceMonitor?

• DaemonSets ohne Service (z.B. Log-Collector, Node-Exporter)
• CronJobs/Jobs die kurzlebig sind
• Pods mit mehreren Containern, wo nur ein bestimmter Container Metriken liefert
• Headless Services, bei denen kein ClusterIP existiert

Probe: Blackbox Monitoring

Neben ServiceMonitor und PodMonitor gibt es die Probe-Ressource für Blackbox-Monitoring. Sie prüft Erreichbarkeit von Endpoints über den Blackbox Exporter:

apiVersion: monitoring.coreos.com/v1
kind: Probe
metadata:
  name: external-api-probe
  namespace: monitoring
  labels:
    release: kube-prometheus-stack
spec:
  jobName: external-apis
  interval: 60s
  module: http_2xx
  prober:
    url: blackbox-exporter.monitoring.svc:9115
  targets:
    staticConfig:
      static:
        - https://api.example.com/health
        - https://payment.example.com/ping

Die Probe nutzt den Blackbox Exporter, um HTTP-, TCP- oder ICMP-Checks durchzuführen — nützlich für externe Abhängigkeiten, die du nicht direkt scrapen kannst.

Debugging: Warum taucht mein Target nicht auf?

Das häufigste Problem: Der ServiceMonitor existiert, aber Prometheus scrapt die App nicht. Systematische Fehlersuche:

# 1. ServiceMonitor vorhanden?
kubectl get servicemonitor -n monitoring

# 2. Labels korrekt? Prometheus selektiert ServiceMonitors über Labels
kubectl get servicemonitor my-go-app-monitor -n monitoring -o yaml | grep -A5 labels

# 3. Service-Labels prüfen — müssen zum selector im ServiceMonitor passen
kubectl get svc my-go-app -n production --show-labels

# 4. Prometheus-Targets direkt prüfen
kubectl port-forward svc/kube-prometheus-stack-prometheus -n monitoring 9090:9090
# Browser: http://localhost:9090/targets

Wenn der Target als "down" angezeigt wird, liegt es meist an:

# 5. Kann Prometheus den Metrics-Endpoint erreichen?
kubectl exec -it prometheus-kube-prometheus-stack-prometheus-0 -n monitoring -- \
  wget -qO- http://my-go-app.production.svc:8080/metrics | head -5

# 6. NetworkPolicy blockiert den Zugriff?
kubectl get networkpolicy -n production

Metriken mit relabelings filtern

Manchmal liefert eine App hunderte Metriken, von denen du nur wenige brauchst. Mit metricRelabelings filterst du direkt beim Scrapen:

endpoints:
  - port: http-metrics
    interval: 30s
    metricRelabelings:
      - sourceLabels: [__name__]
        regex: 'go_gc_.*|go_memstats_.*'
        action: drop

Das reduziert die Anzahl gespeicherter Zeitreihen und spart Storage.

FAQ

In welchem Namespace muss der ServiceMonitor liegen?

Der ServiceMonitor kann in jedem Namespace liegen, den Prometheus beobachtet. Beim kube-prometheus-stack ist das standardmäßig der monitoring-Namespace. Über serviceMonitorNamespaceSelector in der Prometheus-CR kannst du das erweitern.

Kann ich mehrere Ports in einem ServiceMonitor scrapen?

Ja, liste einfach mehrere Einträge unter endpoints auf. Jeder Eintrag kann einen eigenen Port, Pfad und Intervall haben.

Wie häufig sollte ich scrapen?

Für die meisten Apps sind 30 Sekunden ein guter Standard. Hochfrequente Metriken (z.B. Request-Latenz) können auf 15s reduziert werden. Batch-Jobs mit langer Laufzeit reichen 60s oder mehr.

Was ist der Unterschied zwischen metricRelabelings und relabelings?

relabelings modifizieren Labels vor dem Scrape (Target-Konfiguration). metricRelabelings filtern oder ändern Metriken nach dem Scrape. Zum Droppen unnötiger Metriken brauchst du metricRelabelings.

Funktionieren ServiceMonitor und PodMonitor auch ohne Prometheus Operator?

Nein, beide sind Custom Resources des Prometheus Operators. Ohne den Operator musst du Scrape-Targets manuell in der prometheus.yml konfigurieren oder Annotations-basiertes Discovery nutzen.

Nächster Schritt: Kombiniere deine ServiceMonitors mit Prometheus Recording Rules, um häufig genutzte Aggregationen vorzuberechnen und Dashboard-Performance zu verbessern.