Domains, Routen und TLS

Konfigurieren Sie für verwaltetes Cloudflare-DNS die Cloudflare-Integration, bevor Sie Zonen auswählen und Domain-Einträge erstellen. Ein DNS-Connector ersetzt weder den Ingress Node noch dessen TLS-Konfiguration.

Diese Ressourcenkette macht aus einer Anwendung einen stabilen öffentlichen Endpunkt. Eine Domain stellt den Hostnamen dar und legt fest, wo er ausgeliefert wird, eine Route legt fest, was Opfield mit passenden Anfragen tut, und ein TLS-Zertifikat weist HTTPS-Clients gegenüber den Hostnamen nach. Zusammen geben sie dem Hostnamen verschlüsselten Datenverkehr, einen ausdrücklichen Upstream und einen Rollback-Weg.

In der Konsole sind Routen und Domains Registerkarten der Seite Routes, und TLS-Zertifikate befinden sich auf der Registerkarte SSL der Seite Certificates.

Opfield stellt Let’s-Encrypt-Zertifikate aus und verlängert sie und verwaltet DNS-Einträge in Cloudflare-Zonen, die über die Integration verbunden sind. DNS bei jedem anderen Anbieter und die Bereitschaft der Anwendung selbst bleiben bei Ihnen: Legen Sie vor dem Start fest, wer dafür und für die Produktionsumschaltung zuständig ist.

Erfolg bedeutet, dass der kanonische Hostname auf den vorgesehenen Ingress Node aufgelöst wird, HTTPS das erwartete Zertifikat vorlegt, die Route die vorgesehene Anwendung erreicht und sowohl der Health-Zustand in Opfield als auch eine unabhängige externe Anfrage übereinstimmen.

Domains

Registrieren Sie jeden Hostnamen einmal und weisen Sie ihn einem geeigneten nginx-Node mit einer erkannten öffentlichen Dienstadresse zu. Eine Route und ihre Domain müssen auf demselben Node bleiben. Von Cloudflare verwaltete Domains können A/AAAA-Einträge abgleichen; externes DNS bleibt in der Verantwortung des Betreibers. Das Öffnen einer Domain liest nur ihre DNS-Einträge; Opfield repariert Cloudflare-Einträge nur, wenn Sie es ausdrücklich anfordern.

Über die API und MCP kann nginxNodeId weggelassen werden, wenn genau ein geeigneter Node mit einer erkannten öffentlichen Adresse für die domains:create-Berechtigung des Aufrufers offen ist. Andernfalls schlägt die Anfrage mit 409 DOMAIN_NGINX_NODE_REQUIRED fehl und listet die geeigneten Nodes auf. GET /api/domains/nginx-nodes bzw. manage_domain mit der Operation list_nginx_nodes über MCP listet sie für jeden Inhaber von domains:create auf; eine Node-Berechtigung ist nicht erforderlich.

Zertifikate

Stellen Sie Let’s-Encrypt-Zertifikate über HTTP-01 oder DNS-01 aus oder laden Sie vorhandenes Material hoch. HTTP-01 erfordert, dass der zugewiesene Node öffentlich auf Port 80 erreichbar ist. Opfield verteilt privates Schlüsselmaterial nur an Nodes mit aktivierten TLS-Routen, die es verwenden.

Routen

Wählen Sie Domain, Verhalten, Upstream, TLS-Zertifikat und Health-Richtlinie. Aktivieren Sie WebSockets, Rewrites, Header, Pufferung oder Timeout-Änderungen nur, wenn die Anwendung sie erfordert.

Ein Ingress Node beantwortet TLS nur für Hostnamen, die eine seiner Routen ausliefert. Eine TLS-Anfrage für einen anderen Namen wird während des Handshakes abgewiesen, statt das Zertifikat und die Website einer anderen Route zu erhalten. Das Daemon-Update installiert dies auf bestehenden Nodes; wo das eigene nginx des Nodes bereits einen Standardserver auf Port 443 hat, überspringt das Update diesen Schritt und protokolliert eine Warnung. Lehnt nginx eine Konfigurationsänderung ab, schlägt die Änderung bei HTTP- und HTTPS-Routen gleichermaßen mit 422 NGINX_CONFIG_FAILED fehl, und der Fehler enthält die Ausgabe von nginx -t; der Node behält seine vorherige Konfiguration. Eine Route ohne Health Checks zeigt ihren Health-Zustand als Unknown.

Raw Config Mode überträgt Ihnen die gesamte nginx-Konfiguration der Route. Er beginnt mit der gerenderten Konfiguration, und Opfield rendert die Route nicht mehr, bis der Raw-Modus ausgeschaltet wird. Eine Route zu einem Docker-Workload behält im Raw-Modus ihren Secure Link: Der vorbelegte upstream, der Socket der Verbindung auf dem Ingress Node, erreicht den Workload weiterhin und folgt ihm, wenn sein Container neu erstellt wird; bearbeiten Sie die Konfiguration also nach Bedarf, leiten Sie aber weiterhin an diesen Upstream weiter. Rohe Konfiguration, Inhalte von nginx-Vorlagen und die erweiterte Konfiguration von Additional Routes durchlaufen dieselben Direktivenprüfungen: Ohne proxy:unrestricted werden gesperrte Direktiven abgelehnt, und nginx-Logs können nur unter /var/log/nginx geschrieben werden.

Zwei aktivierte Routen auf demselben Node können nicht denselben Namen ausliefern, weil nginx nur eine von beiden ausliefern würde. Eine Route so zu erstellen, zu aktivieren, zu bearbeiten oder auf einen anderen Node zu verschieben, dass sie einen Namen ausliefert, den bereits eine andere aktivierte Route auf diesem Node ausliefert, schlägt mit 409 PROXY_HOST_DOMAIN_CONFLICT fehl, das die andere Route benennt. Namen werden ohne Berücksichtigung der Groß- und Kleinschreibung verglichen. Routen, die sich bereits vor dem Update auf 2.11 überschnitten, behalten ihre Konfiguration; siehe Durch das Update auf 2.11 gelöste Konflikte.

Den Ingress Node wählen

Eine Route läuft auf einem nginx-Ingress-Node oder auf jedem Mitglied einer Ingress-Gruppe. Im Dialog Create Route füllt die Auswahl einer registrierten Domain deren Node aus. Benutzer, die Routen breit oder in einem Ordner erstellen dürfen, können außerdem Automatic (from the registered domain) wählen und Opfield entscheiden lassen; gelingt das nicht, listet der Fehler die Nodes zur Auswahl auf. Über die API und MCP ist nodeId bei POST /api/proxy-hosts und create_route optional, und Opfield ermittelt den Node in dieser Reihenfolge:

1. Eine ausdrückliche nodeId wird wie angegeben verwendet.
2. Registrierte Domains unter den Namen der Route legen ihren Ingress Node fest, genau oder über einen abdeckenden Wildcard abgeglichen. Registrierte Domains auf verschiedenen Nodes können sich keine Route teilen: 409 DOMAIN_NGINX_NODE_MISMATCH.
3. Andernfalls wird der einzige nginx-Node verwendet, auf dem der Aufrufer am jeweiligen Ziel Routen erstellen darf, sofern er online ist. Nodes, deren Registrierung noch aussteht, werden nie gewählt oder angeboten. Eine Route wird nie automatisch auf einem getrennten Node platziert; übergeben Sie dessen ID ausdrücklich, wenn Sie sie dort haben möchten.
4. Andernfalls schlägt die Anfrage fehl: 409 ROUTE_INGRESS_NODE_REQUIRED, wenn mehrere Nodes infrage kommen oder der einzige offline ist, wobei die Nodes in der Meldung und in details.eligibleNodes aufgeführt werden; 409 ROUTE_INGRESS_NODE_UNAVAILABLE, wenn keiner verfügbar ist; oder 403, wenn der Aufrufer keine proxy:create-Berechtigung für das Ziel hat.

GET /api/proxy-hosts/ingress-nodes bzw. list_route_ingress_nodes über MCP listet die geeigneten Nodes nur mit ihrer ID, ihrem Anzeigenamen, Hostnamen und Status auf. Dafür genügt eine beliebige proxy:create-Berechtigung, eine Node-Berechtigung ist nicht erforderlich. Eine breite oder ordnerbezogene proxy:create-Berechtigung deckt jeden nginx-Node ab, eine Berechtigung auf node/<nodeId> nur diesen Node, und Nodes, die für neue Dienste gesperrt sind, werden nie angeboten. Übergeben Sie folderId, wenn die Route in einem Ordner erstellt wird; ein auf Ordner beschränkter Ersteller muss es in jedem Fall übergeben. Der ermittelte Node durchläuft die üblichen Prüfungen: die Node-Berechtigung, den Zielordner, die Platzierung der Domain und die Sperre für neue Dienste.

Migration

Verwenden Sie den ausdrücklichen Ablauf zur Ingress-Migration, um eine Domain und ihre Routen zu verschieben. Cloudflare-DNS kann während der Umschaltung geändert werden; externes DNS erfordert ein vom Operator bestätigtes Update. Prüfen Sie das Ziel, bevor Sie die Quellplatzierung entfernen. Liefert eine aktivierte Route auf dem Ziel-Node bereits einen der zu verschiebenden Namen aus, wird die Migration mit 409 DOMAIN_INGRESS_TARGET_DOMAIN_CONFLICT abgelehnt, bevor sich etwas ändert.

Voraussetzungen und Berechtigungen

Der Ziel-Ingress-Node muss online sein, eine nutzbare Dienstadresse melden und die vorgesehene Zertifikats-Challenge unterstützen. Der Aufrufer benötigt Zugriff auf die Domain, die Route, das Zertifikat, den Ziel-Workload und jede wiederverwendbare Access List, die an der Änderung beteiligt ist.

Senken Sie bei extern verwaltetem DNS die TTL vor einer geplanten Migration und halten Sie die aktuellen Einträge fest. Prüfen Sie bei von Cloudflare verwaltetem DNS den Geltungsbereich des Connectors und die Zonen-Allowlist, bevor Sie Opfield bitten, Einträge zu ändern.

Die vollständige Kette konfigurieren

1. Erstellen oder wählen Sie die Domain und platzieren Sie sie auf einem Ingress Node.
2. Bestätigen Sie, dass DNS auf die ausgewählte öffentliche Dienstadresse zeigt.
3. Stellen Sie ein Zertifikat aus oder laden Sie eines hoch, das den genauen Hostnamen abdeckt.
4. Erstellen Sie die Route und wählen Sie das Verhalten Proxy, Umleitung oder 404.
5. Wählen Sie den Upstream und das Anwendungsprotokoll.
6. Hängen Sie TLS, Zugriffsrichtlinie, Health Checks und Protokolloptionen an.
7. Speichern Sie und warten Sie auf die Validierung und Anwendung durch nginx.
8. Prüfen Sie den öffentlichen Endpunkt von außerhalb des verwalteten Netzwerks.

Prüfen Sie bei Wildcard- oder Mehrnamenzertifikaten jeden Hostnamen vor der Wiederverwendung. Dass ein Zertifikat existiert, bedeutet nicht, dass es verteilt ist; die Verteilung folgt der Platzierung aktivierter TLS-Routen.

Folgen von Änderungen und Löschungen

• Das Verschieben einer Domain ändert, wo alle ihre Routen ausgeliefert werden.
• Der Austausch eines Zertifikats wirkt sich nach der Verteilung auf jede angehängte TLS-Route aus.
• Das Deaktivieren einer Route bewahrt die Konfiguration, stoppt aber den verwalteten virtuellen Host.
• Das Löschen einer Route setzt die Secure Links der Route außer Kraft, löscht aber keine wiederverwendbaren Zertifikate oder Access Lists.
• Das Löschen einer Domain erfordert, dass ihre abhängigen Routen zuerst entfernt oder migriert werden.
• Ein Zertifikat, das eine Route oder das Wildcard-Profil von Pages verwendet, kann nicht gelöscht werden: Die Anfrage schlägt mit 409 CERT_IN_USE und den IDs der Routen fehl, die es verwenden. Lösen Sie das Zertifikat zuerst; das Löschen entfernt dann die von Opfield verwaltete Kopie.

Prüfliste

• Externes DNS wird auf den vorgesehenen Node aufgelöst.
• Das HTTP-Verhalten ist beabsichtigt: Umleitung, Antwort oder deaktiviert.
• HTTPS liefert das erwartete Zertifikat und die vollständige Kette.
• Health Checks verwenden den vorgesehenen Pfad und den erwarteten Status.
• WebSocket- und Timeout-Einstellungen passen zur Anwendung.
• Die nginx-Konfiguration ist gültig, und die neueste Revision ist bestätigt.
• Access- und Error-Logs zeigen die externe Prüfanfrage.

Verlängerung und Platzierungsänderungen

Zertifikatsverlängerung und Domain-Migration sind getrennte Operationen. Ein verlängertes Zertifikat muss erfolgreich ausgestellt, von Opfield gespeichert, an jeden geeigneten Ingress Node verteilt werden, der eine angehängte TLS-Route ausliefert, und von nginx bestätigt werden. Prüfen Sie den neuen Gültigkeitszeitraum und das extern ausgelieferte Zertifikat; ein erfolgreicher Ausstellungseintrag allein ist nicht die abschließende Prüfung.

Bereiten Sie bei Platzierungsänderungen den Ziel-Node vor, bevor Sie DNS ändern. Bestätigen Sie auf dem Ziel die nginx-Fähigkeit, öffentliche Dienstadressen, Verfügbarkeit des Zertifikats, Routenkonfiguration, Erreichbarkeit des Upstreams und Health Checks. Ist DNS extern, ändern Sie die Einträge erst, wenn das Ziel bereit ist, und halten Sie die Quelle mindestens für die erwartete TTL und das Cache-Fenster verfügbar. Verwaltet Opfield Cloudflare-DNS, prüfen Sie dennoch die resultierenden öffentlichen Antworten, statt anzunehmen, dass die Anbieteroperation sofort überall abgeschlossen ist.

Grenzen bei Fehlern und Rollback

Schlägt die Validierung der Konfiguration fehl, darf die ungültige Revision die zuletzt bestätigte nginx-Konfiguration nicht ersetzen. Lesen Sie den Validierungsfehler, korrigieren Sie die kleinste relevante Einstellung und wenden Sie erneut an. Lösen Sie kein funktionierendes Zertifikat und verschieben Sie die Domain nicht, nur um einen Syntax- oder Upstream-Auswahlfehler zu umgehen.

Schlägt eine Migration vor der DNS-Umschaltung fehl, belassen Sie den Datenverkehr auf der Quelle und reparieren Sie das Ziel. Wurde externes DNS bereits geändert, stellen Sie die festgehaltenen Quelleinträge wieder her oder schließen Sie die Reparatur des Ziels gemäß der Entscheidung zum Vorfall ab; vermeiden Sie wiederholtes Hin- und Herschalten der Einträge, da rekursive Resolver unterschiedliche Zustände sehen können. Prüfen Sie nach einem Rollback sowohl die öffentliche Adressauflösung als auch das tatsächlich von der Quelle ausgelieferte Zertifikat.

Opfield kann keine Schreibvorgänge der Anwendung oder externen DNS-Änderungen zurücksetzen, die außerhalb seines verwalteten Ablaufs stattgefunden haben. Bewahren Sie die vorherigen DNS-Werte, die Zertifikatszuweisung und die Anwendungsrevision als Teil des Änderungseintrags.