Fehlerbehebung beim Ingress

Ziel bei einem Vorfall ist es, den öffentlichen Dienst wiederherzustellen, ohne den Zustand zu zerstören, der den Fehler erklärt. Der Ingress überschreitet mehrere Zuständigkeitsgrenzen – DNS, Netzwerk, Zertifikat, nginx-Konfiguration, Routenrichtlinie, privater Transport und Anwendungslaufzeit –, daher verlängert das gleichzeitige Ändern mehrerer Ebenen meist den Ausfall.

Bestimmen Sie einen Verantwortlichen für den Vorfall, halten Sie die letzte bekannt fehlerfreie Änderung fest und prüfen Sie von außen nach innen. Erfolg bedeutet, dass das externe Verhalten wiederhergestellt ist, Soll- und gemeldeter Zustand in Opfield übereinstimmen und die ausgefallene Ebene sowie die Wiederherstellungsmaßnahme gut genug festgehalten sind, um eine Wiederholung zu verhindern.

Verwenden Sie diese Reihenfolge, um nicht die falsche Ebene zu ändern:

DNS: Lösen Sie den Hostnamen von einem externen Client aus auf und bestätigen Sie, dass er auf den zugewiesenen Ingress Node zeigt.
Netzwerk: Bestätigen Sie die öffentliche Erreichbarkeit von 80/443 und die Firewall-Regeln des Hosts.
TLS: Prüfen Sie Hostname, Kette, Ablauf und Verteilungsstatus des Zertifikats.
nginx-Konfiguration: Prüfen Sie, dass die neueste Revision angewendet wurde und die Validierung der Konfiguration erfolgreich war.
Health-Zustand der Route: Prüfen Sie erwarteten Status bzw. Inhalt und den Wartungszustand.
Upstream: Testen Sie die Anwendung vom nginx-Node aus oder prüfen Sie den Zustand des Secure Links.
Logs: Setzen Sie nginx-Access- und Error-Logs mit Workload-Logs und Request-IDs in Beziehung.

Häufige Fehler sind die Platzierung von Domain und Route auf verschiedenen Nodes, veraltetes externes DNS nach einer Migration, HTTP-01 auf einem Node ohne öffentlichen Port 80, eine WebSocket-Anwendung ohne WebSocket-Weiterleitung und die Wahl eines Workload-Ports, der weder tatsächlich veröffentlicht noch verbunden ist.

Leitfaden nach Symptom

Symptom	Wahrscheinlichste Ebene	Erste Belege
Hostname wird nicht aufgelöst	DNS	Externe `A`/`AAAA`-Abfrage und Platzierung der Domain
Verbindungs-Timeout	Netzwerk	Öffentliche Adresse, Firewall, Ports 80/443, Verfügbarkeit des Nodes
Zertifikatswarnung	TLS	Hostname, Kette und Ablauf des Zertifikats sowie zugewiesene Route
TLS-Handshake schlägt sofort fehl	Routenzuordnung	Keine aktivierte Route auf diesem Node liefert den Hostnamen aus; der Node weist solche Handshakes ab, statt mit der Website einer anderen Route zu antworten
Sofortiges `404`	Routenzuordnung	Hostname, Pfadpräfix, Aktivierungszustand, rohe Konfiguration
Verwaltetes `503`	Wartung oder fehlerhafter Upstream	Wartungszustand und Health-Verlauf
`502`/`504`	Upstream-Transport	Secure Link, Zielport, Health-Zustand des Workloads, Timeout-Einstellungen
WebSocket-Verbindungen brechen ab	Protokollweiterleitung	WebSocket-Option, Anwendungspfad, Proxy- und Lese-Timeouts
Änderungen erscheinen nie	Anwendung/Abgleich	Task-Zustand, nginx-Revision, Node-Verbindung, Validierungsfehler; eine abgelehnte Änderung schlägt mit `422 NGINX_CONFIG_FAILED` fehl und meldet die Ausgabe von `nginx -t`
`502` von einer Docker-Route im Raw Config Mode	Rohe Konfiguration	Die rohe Konfiguration muss weiterhin an den Secure-Link-Upstream der Route weiterleiten; siehe Routen
`502` von einem Deployment	Deployment-Router	Der Header `X-Opfield-Deployment-Router: upstream-unavailable` bedeutet, dass der Router den aktiven Slot nicht erreichen konnte

Belege sammeln, bevor Sie den Zustand ändern

Halten Sie den fehlschlagenden Hostnamen, den Pfad, die Zeit, die Art der Client-IP, die erwartete Antwort, die tatsächliche Antwort, den zugewiesenen Node, die Routen-ID, die neueste Task-ID und die relevante Request-ID fest. Bewahren Sie den Validierungsfehler der generierten Konfiguration und begrenzte Logs, bevor Sie es erneut versuchen; wiederholte Bearbeitungen können die nützlichsten Belege löschen.

Vergleichen Sie drei Sichten:

den Sollzustand in Opfield in den Details von Route und Domain;
den zuletzt bestätigten Zustand vom nginx-Node;
das extern beobachtete Verhalten von DNS, TLS und HTTP.

Eine Abweichung zwischen diesen Sichten zeigt, ob der Fehler im Zustand der Control Plane, bei der Anwendung auf dem Node oder in der externen Infrastruktur liegt.

Secure-Link-Fehler werden einmal pro Link protokolliert, nicht einmal pro Anfrage. Der nginx-Daemon auf dem Ingress Node protokolliert eine Warnung proxy secure-link connections failing mit der link_id, dem letzten Relay, der Phase und dem Fehler, wenn ein Link zu scheitern beginnt, alle 5 Minuten still failing mit einer Anzahl, eine Info-Zeile, wenn Anfragen erst nach Wiederholungen gelingen, und recovered mit der Anzahl fehlgeschlagener und wiederholter Anfragen bei der ersten einwandfreien Verbindung. Der Docker-Daemon des Ziels protokolliert fehlschlagende eingehende Tunnel auf dieselbe Weise pro Endpunkt-Eigentümer (relay endpoint tunnels) und Ablehnungen auf widerrufenen Routen separat (relay endpoint tunnels on revoked routes). Details zu jedem Versuch stehen auf Debug-Ebene.

Sichere Wiederherstellung

Korrigieren Sie DNS erst, nachdem die vorgesehene Node-Platzierung bestätigt ist.
Korrigieren Sie eine Zertifikatszuweisung, statt TLS global zu deaktivieren.
Beheben Sie die Validierung der Konfiguration, bevor Sie eine weitere Anwendung erzwingen.
Verwenden Sie den Wartungsmodus, wenn die Anwendung während der Reparatur nicht verfügbar bleiben muss.
Wiederholen Sie den Abgleich erst, wenn die Abhängigkeit, die den Fehler verursacht hat, fehlerfrei ist.
Setzen Sie die Anwendung oder die Routenkonfiguration zurück, wenn eine bekannt fehlerfreie Revision existiert.

Löschen Sie Domain, Zertifikat oder Route nicht als erste Reaktion, um sie neu zu erstellen. Das zerstört den Beziehungsverlauf und kann einen zweiten Ausfall verursachen.

Prüfung der Wiederherstellung

Testen Sie von einem externen Client aus und bestätigen Sie dann den kanonischen Hostnamen, die Zertifikatskette, den Statuscode, den Inhalt, Umleitungen, WebSockets, den Health-Verlauf und die nginx-Logs. Schließen Sie den Vorfall erst, wenn das öffentliche Verhalten und der Zustand in Opfield übereinstimmen.

Rollback nach ausgefallener Ebene

Ein Rollback sollte die kleinste Änderung rückgängig machen, die den Ausfall verursacht hat. Stellen Sie bei DNS die festgehaltenen Adresswerte wieder her und berücksichtigen Sie Resolver-Caches. Stellen Sie bei TLS die vorherige gültige Zertifikatszuweisung wieder her, ohne HTTPS zu deaktivieren. Kehren Sie bei der nginx-Konfiguration zu den letzten bekannt fehlerfreien verwalteten Einstellungen zurück und warten Sie auf die Bestätigung. Setzen Sie bei einer Regression der Anwendung das zuständige Deployment oder die Compose-Revision zurück, statt die Route um ein fehlerhaftes Release herum umzuschreiben.

Secure-Link-Fehler erfordern die Wiederherstellung der Relay- und Node-Konnektivität oder der Ziellaufzeit; Änderungen an DNS oder Zertifikaten können sie nicht beheben. Fehler in der Zugriffsrichtlinie erfordern die Wiederherstellung der vorherigen Access List oder der Auslegung vertrauenswürdiger Proxys, nicht das Öffnen des Workload-Ports. Der Wartungsmodus ist bei der Reparatur dieser Ebenen nützlich, weil er Hostname und TLS-Pfad ausdrücklich beibehält und versehentlichen Datenverkehr zu einer teilweise wiederhergestellten Anwendung verhindert.

Belege für die Eskalation

Erklärt der erste Wiederherstellungsversuch den Fehler nicht, sammeln Sie vor der Eskalation ein begrenztes Belegpaket:

Kennungen von Domain und Route, zugewiesener Ingress Node und zuletzt bestätigte Konfigurationsrevision;
externe DNS-Antworten und TLS-Zertifikatsdetails, die zum Zeitpunkt des Vorfalls beobachtet wurden;
Health-Verlauf der Route und genauer fehlschlagender Pfad, Methode, Status und Zeitstempel;
relevante nginx-Access- und Error-Einträge sowie die Operation des zuständigen Workloads oder Secure Links;
Versionen von Node und Relay, Konnektivitätszustand und die letzte Fehlermeldung eines Tasks;
die letzte bekannt fehlerfreie Revision von Anwendung, Route und DNS.

Schwärzen Sie Zugangsdaten, Cookies, Authorization-Header, private Schlüssel und sensible Abfragewerte. Ziel ist es, den Ursachenzusammenhang zu bewahren, ohne einen Vorfalleintrag in einen Secret-Speicher zu verwandeln.