Endpoint-Monitoring

Endpoint-Monitoring

Das Endpoint-Monitoring der Polycrate API prüft kontinuierlich, ob externe und interne Dienste erreichbar sind. Es ist das Herzstück der Zustandserfassung für ManagedObjects: aus einer Sammlung regelmäßiger Probes gegen einen Endpoint ergibt sich der aggregierte state eines Objekts (OK / WARNING / CRITICAL) — und daraus wiederum Downtimes und Notifications.

Polycrate trennt dabei was geprüft wird (Endpoint) von wer prüft (Agent).

Modellübersicht

┌──────────────────┐         prüft          ┌────────────┐
│      Agent       │────────────────────────▶│  Endpoint  │
│  (CLI / Operator)│    via Assignment       │            │
└──────────────────┘                         └─────┬──────┘
                                                   │ generic FK
                                                   ▼
                                          ┌──────────────────┐
                                          │   ManagedObject  │
                                          │ (Host, LB, PoP…) │
                                          └──────────────────┘

Endpoint — was geprüft wird

Ein Endpoint beschreibt einen einzelnen Probe. Kernfelder:

Feld Zweck
name / display_name Anzeige
kind icmp, http, tcp, udp
remote_address / remote_port Ziel — Host/IP + Port
interval Sekunden zwischen Checks
timeout Max. Wartezeit pro Check
spec JSON-Detail-Konfiguration (Method, Pfad, Expected-Status, TLS-Optionen, …)
agents M2M zu Agent über EndpointAgentAssignment
content_object Generic FK auf das ManagedObject, das dieser Endpoint prüft

Kinds im Überblick:

  • icmp — klassischer Ping. Gut für Host-Reachability, braucht CAP_NET_RAW beim ausführenden Agent.
  • icmp — Ping inkl. Latenzwerten für Reachability und Edge-Vergleiche (CAP_NET_RAW).
  • http — HTTP(S) mit Pfad, Methode, Expected-Status; Dashboard zeigt Remote Port und TLS-Status.
  • tcp / udp — Connect-/Probe-Checks (DB, Broker, DNS, VPN, …).
  • TLS-Inspektion — Expiry, Issuer und Chain aus Agent-Check-Ergebnissen.

Agent Check Result History (API) liefert die letzten N Ergebnisse pro Check für Trends. Check-Result-Retention beträgt typischerweise 1 Tag (batched Cleanup).

Agent — wer prüft

Ein Agent ist der ausführende Akteur, der Endpoints tatsächlich probiert. Er meldet sich mit einem Token an der API an und pullt seine Arbeit:

Agent-Kind Beschreibung
CLI-Agent Eigener Prozess, startbar mit polycrate api agent --agent-token .... Gut für Bare-Metal, Windows, air-gapped Standorte
Operator Der Polycrate-Operator agiert im Kubernetes-Cluster als Agent mit kind=operator. Der Operator registriert sich automatisch und erscheint in der Agent-Liste

Jeder Agent sendet Heartbeats und Probe-Ergebnisse an die API. Felder wie last_seen, health_status, effective_capacity und monitored_endpoints_count machen seinen Zustand transparent.

EndpointAgentAssignment — wer prüft was

Die M2M-Zuweisung zwischen Endpoint und Agent ist explizit: ein Endpoint kann von mehreren Agents parallel geprüft werden (für Multi-Region-Monitoring), und ein Agent prüft typischerweise viele Endpoints.

Die Zuweisung kann

  • manuell erfolgen (Admin wählt pro Endpoint passende Agents),
  • automatisch über Scheduler-Logik, die freie Agent-Kapazität nutzt.

Von Probe zum Objekt-State

Ein einzelner Probe hat ein Ergebnis (up/down, Latenz, Statuscode, TLS-Details). Daraus wird pro Endpoint gerollt:

  1. Hot-Path — Status-Diffs aus Agent-Check-Results aktualisieren Endpoint-State/Downtime sofort (nicht erst am nächsten Reconcile-Tick).
  2. Reconcile — Stale-/Recovery-Logik im längeren Intervall (typisch 300s).
  3. Metriken — VictoriaMetrics für Uptime/Latenz-Tabs (status_blocks, latency, uptime).
  4. ManagedObject-State — angehängte Endpoints fließen in Conditions / Object-State: * OK — aktive Probes erfolgreich * WARNING — Teilfehler / Latenz * CRITICAL — harte Schwellen → Downtime + Notifications

Agent-Health: Unhealthy erst nach längerer Stille (SLA typisch 300s).

Edge-Pop-Latencies

PoP-Detail und zugehörige Tabs zeigen ICMP-Reachability aus Edge-Workspaces (Latenz pro PoP). S3-/Region-API-Endpoints können ebenfalls gemonitort werden. Workspace-lose Endpoints werden an den Operator ausgeliefert (inkl. ICMP-Seed).

SLO / SLA

Jedes ManagedObject, das Endpoints trägt, kann SLO/SLA-Ziele definieren:

  • target_availability_percent — z. B. 99.9 %
  • actual_availability_percent — berechnet aus Probe-Historie
  • error_budget_* — abgeleitetes Fehlerbudget

Die Werte erscheinen auf dem Detail-View des Objekts und fließen in Reports.

Source-Klassifikation (API-seitig)

Wenn Endpoints aus mehreren Quellen kommen, klassifiziert die API sie, damit Ownership klar bleibt:

Source Beschreibung
api Endpoint wurde direkt in der Polycrate API angelegt (z. B. über die UI/REST)
discovery Endpoint entstand aus einer automatischen Erkennung (Operator erkennt Ingress- oder HTTPRoute-Objekte und legt einen Endpoint an)
manual Endpoint wurde aus dem Cluster heraus manuell erstellt

Aus API-Sicht sind alle drei Sources gleichwertig: derselbe Probe-Pfad (HTTP/TLS, Agent-Assignment, Conditions, Downtime). Wer den Endpoint angelegt hat, ändert nicht, wie er geprüft wird.

Operator-Discovery (Ingress und Gateway API)

Der Polycrate Operator legt für öffentliche Hostnamen Endpoint-CRs an und sync't sie in die API (source=discovery, typisch kind=http). Annotations auf der Source steuern Pfad, Intervall, Timeout, Expected-Status, TLS und Port — siehe Operator Endpoint Discovery.

Source Wann aktiv Hosts TLS / Port
Ingress immer, wenn endpoint_discovery.enabled spec.rules[].host Ingress-TLS bzw. polycrate_endpoint_tls / _port
HTTPRoute wenn Gateway-API-CRDs (HTTPRoute v1) im Cluster liegen und endpoint_discovery.enabled — kein Extra-Flag spec.hostnames (leer = kein Endpoint) Parent-Gateway-Listener (sectionName, sonst erster HTTPS-, sonst HTTP-Listener)
Gateway nie als Quelle — ändert nur Listener; Operator queued abhängige HTTPRoutes neu

Gleicher Hostname im selben Namespace: HTTPRoute gewinnt den Endpoint-CR (hostToName). Ingress überschreibt ihn nicht. Filter: ingress_classes bzw. gateway_classes (leer = alle). GRPCRoute/TLSRoute werden nicht beobachtet.

Modus annotation (Standard): ohne polycrate_endpoint_monitor=true kein Endpoint. Modus auto: alle außer polycrate_endpoint_monitor=false.

polycrate_k8sapp_name claimed den Endpoint an eine K8sApp (discovery-source=ingress bzw. httproute). Ohne Name: Monitoring ja, keine App-Downtime. polycrate_k8sapp_byoa=true setzt API K8sApp.byoa nur auf diesen sourced CRs.

Der BYOA-Block schreibt denselben Vertrag auf Ingress und HTTPRoute.

TLS-Monitoring

HTTP-Endpoints mit HTTPS erhalten automatisch TLS-Monitoring. Die API erzeugt Alerts bei:

  • Zertifikat abgelaufen / noch nicht gültig
  • Zertifikats-Chain ungültig
  • Hostname-Mismatch
  • TLS-Expiry < 30 Tagen (Schwelle pro Endpoint konfigurierbar)

Pro Endpoint kann optional ignore_tls_errors=true gesetzt werden — nötig für interne Services mit selbstsignierten Zertifikaten.

Metrik-Funktionen

Jeder Endpoint stellt die Standard-Metrik-Funktionen zur Verfügung (siehe Metriken):

Funktion Bedeutung
status_blocks Lückenlose Block-Darstellung des Probe-Ergebnisses (grün/rot/gelb)
latency Antwortzeit pro Probe über die Zeit
uptime Uptime in % pro Zeitraum

Zusätzlich exportiert der Agent Prometheus-Metriken wie polycrate_io_endpoint_up, polycrate_io_endpoint_response_time_ms, polycrate_io_endpoint_certificate_expiry_timestamp.

Multi-Region- und Multi-Agent-Monitoring

Ein Endpoint lässt sich an mehrere Agents zuweisen, die ihn parallel aus verschiedenen Regionen prüfen. Das Ergebnis:

  • Probe-Daten pro Agent — die Tabelle zeigt pro Probe, welcher Agent geantwortet hat.
  • Matrix-Darstellung — PoP-zu-PoP-Latenz als Metrik (siehe Metriken → PoP-zu-PoP-Latenz).
  • Aggregierter is_up-Wert — "Endpoint ist online" bedeutet "mindestens n Agents melden OK" (Schwelle pro Endpoint einstellbar).

Für Plattformen mit verteilten Standorten genügt es, pro Standort einen Operator oder CLI-Agent laufen zu lassen; die Zuweisung zu den Endpoints erfolgt dann zentral.

Stale Checks und fehlende Monitore

Keine Evidenz ist kein Down. Reachability (ENDPOINT_UNREACHABLE) setzt erst nach SYSTEM_DEGRADATION_THRESHOLD_SECONDS (Default 300) und nur aus frischen Checks (UP% unter 50%).

Situation Condition Severity
Checks veraltet ENDPOINT_RECENT_CHECK_RESULTS_MISSING WARNING
Keine Agent-Zuweisung ENDPOINT_NO_MONITORS_ASSIGNED WARNING
Frische Checks, UP% < 50%, Schwelle erreicht ENDPOINT_UNREACHABLE / _PARTIALLY_UNREACHABLE CRITICAL (Downtime)

Downtimes folgen der Ownership: claimed inkl. BYOA ja; unclaimed Endpoint (Ingress oder HTTPRoute ohne polycrate_k8sapp_name) nein. Edge-PoPs ohne aktiven Reachability-Endpoint erzeugen keine künstliche Unerreichbarkeit.

Agent-Lifecycle

Ein Agent ist selbst ein ManagedObject und hat Metrik-Funktionen wie health_status und last_seen. Bleibt der Heartbeat aus, wird der Agent auf state=CRITICAL gesetzt und erzeugt — wie jedes andere ManagedObject — eine Downtime. So erkennt die Plattform selbst, wenn ein Monitor-Standort ausfällt.

API-Endpunkte

  • GET /api/v1/endpoints/ — Endpoints auflisten, filtern nach kind, content_type (also welches Objekt geprüft wird), is_up.
  • POST /api/v1/endpoints/ — Endpoint anlegen (inkl. Agent-Zuweisung).
  • GET /api/v1/agents/ — Liste der registrierten Agents.
  • GET /api/v1/endpoint/{id}/metrics/?function=status_blocks&range=24h — Metrik pro Endpoint.

Typischer Workflow

  1. Host / LoadBalancer / Service anlegen — das Objekt, dessen Zustand du kennen willst.
  2. Endpoint(s) anhängen — einer oder mehrere Probes pro Objekt.
  3. Agent(s) zuweisen — entweder den lokalen Operator, externe CLI-Agents oder beides.
  4. SLO definieren — optional, für Availability-Reports und Fehlerbudgets.
  5. Observability — Metrik-Tabs, Downtimes, Notifications laufen automatisch.

Verwandte Themen