upstream-jdomain: Asynchrones Modul zur Namensauflösung für NGINX Upstream
Installation
Sie können dieses Modul in jeder RHEL-basierten Distribution installieren, einschließlich, aber nicht beschränkt auf:
- RedHat Enterprise Linux 7, 8, 9 und 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 und Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-upstream-jdomain
yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-upstream-jdomain
Aktivieren Sie das Modul, indem Sie Folgendes an den Anfang von /etc/nginx/nginx.conf hinzufügen:
load_module modules/ngx_http_upstream_jdomain_module.so;
Dieses Dokument beschreibt nginx-module-upstream-jdomain v1.5.2 veröffentlicht am 09. Dezember 2024.
Ein asynchrones Modul zur Namensauflösung für NGINX Upstream.
Dieses Modul ermöglicht es Ihnen, einen Domainnamen in einem Upstream-Block zu verwenden und zu erwarten, dass der Domainname dynamisch aufgelöst wird, sodass Ihr Upstream gegenüber DNS-Eintrag-Updates resilient ist.
Das Modul führt keine DNS-Auflösung automatisch in regelmäßigen Abständen durch. Stattdessen muss die DNS-Auflösung durch eine Anfrage für den angegebenen Upstream angestoßen werden. Wenn NGINX eine Verbindung zu einem jdomain Upstream bedient und das konfigurierte interval abgelaufen ist, führt das Modul eine DNS-Abfrage durch.
Das Modul ist mit anderen upstream-Scope-Direktiven kompatibel. Das bedeutet, dass Sie einen upstream-Block mit mehreren jdomain-Direktiven, mehreren server-Direktiven, keepalive, Lastenausgleichs-Direktiven usw. füllen können. Beachten Sie, dass, es sei denn, eine andere Lastenausgleichsmethode wird im upstream-Block angegeben, dieses Modul den standardmäßigen Round-Robin-Lastenausgleichsalgorithmus verwendet, der in den NGINX-Core integriert ist.
Wichtiger Hinweis: Sollte ein alternativer Lastenausgleichsalgorithmus angegeben werden, muss dieser vor der jdomain-Direktive im Upstream-Block stehen! Wenn dies nicht beachtet wird, wird NGINX abstürzen! Dies liegt daran, dass viele andere Lastenausgleichs-Module explizit den integrierten Round-Robin erweitern und somit die Initialisierungs-Handler von jdomain überschreiben, da jdomain technisch ebenfalls ein Lastenausgleichsmodul ist. Auch wenn dies nicht bei allen Lastenausgleichsmodulen der Fall sein mag, ist es besser, auf der sicheren Seite zu bleiben und jdomain danach zu platzieren.
Wichtiger Hinweis: Aufgrund der nicht blockierenden Natur dieses Moduls und der Tatsache, dass seine DNS-Auflösung durch eingehende Anfragen ausgelöst wird, wird die Anfrage, die eine Abfrage auslöst, tatsächlich weiterhin an den Upstream weitergeleitet, der vor der DNS-Abfrage aufgelöst und zwischengespeichert wurde. Je nach Szenario kann dies zu einem einmaligen Fehler beim Ändern der Zustände von Upstreams führen. Dies ist wichtig zu beachten, um einen reibungslosen Übergang Ihrer Upstreams zu gewährleisten.
Dieses Repository ist ein Fork von einem Repository, das ursprünglich von wdaike erstellt wurde. Da dieses Projekt nicht mehr gewartet wird, zielt dieses Repository darauf ab, sein Nachfolger zu sein und hat nun mehrere Funktionen voraus.
Verwendung
resolver 8.8.8.8; # Ihr lokaler DNS-Server
## Basis-Upstream unter Verwendung des Domainnamens, der standardmäßig auf Port 80 verweist.
upstream backend_01 {
jdomain example.com;
}
## Basis-Upstream mit Angabe eines anderen Ports.
upstream backend_02 {
jdomain example.com port=8080;
}
## Upstream mit einem Backup-Server, der im Falle von Host nicht gefunden oder Formatfehlern bei der DNS-Auflösung verwendet wird.
upstream backend_03 {
server 127.0.0.2 backup;
jdomain example.com;
}
## Upstream, der für alle DNS-Auflösungsfehler ein Backup verwendet.
upstream backend_04 {
server 127.0.0.2 backup;
jdomain example.com strict;
}
server {
listen 127.0.0.2:80;
return 502 'Ein Fehler.';
}
Zusammenfassung
Syntax: jdomain <domain-name> [port=80] [max_ips=4] [interval=1] [strict]
Kontext: upstream
Attribute:
port: Port, auf dem der Backend lauscht. (Standard: 80)
max_ips: IP-Puffergröße. Maximale Anzahl der aufgelösten IPs, die zwischengespeichert werden. (Standard: 4)
interval: Wie viele Sekunden zur Auflösung des Domainnamens. (Standard: 1)
ipver: Es werden nur Adressen der Familie IPv4 oder IPv6 verwendet, wenn definiert (Standard: 0)
strict: Erfordert, dass die DNS-Auflösung erfolgreich ist und Adressen zurückgibt,
andernfalls werden der zugrunde liegende Server und die Peers als ausgefallen markiert und
die Verwendung anderer Server im Upstream-Block erzwungen, falls vorhanden. Ein fehlgeschlagene Auflösung kann ein Timeout, ein DNS-Serverfehler, Verbindungsablehnungen, Antworten ohne
Adressen usw. sein.
Siehe https://www.nginx.com/resources/wiki/modules/domain_resolve/ für Details.
Entwicklung
Voraussetzungen
Um die lokale Entwicklung zu erleichtern und Ihnen zu ermöglichen, das Modul zu erstellen und zu testen, benötigen Sie einige Werkzeuge.
- Docker: um eine Umgebung bereitzustellen, die es einfach macht, ideale Bedingungen für den Aufbau und das Testen zu reproduzieren.
- act: um die Ausführung von GitHub-Aktionen-Workflows lokal zu simulieren, um zu vermeiden, dass Sie Commits pushen müssen, nur um zu sehen, wie der CI fehlschlägt.
- rust: Abhängigkeit von
cargo-make. - cargo-make: um gängige Entwicklungsaufgaben wie Erstellen, Testen und Formatieren von Code auszuführen.
Task Runner
cargo-make ist ein fortgeschrittener Task Runner, der es Ihnen ermöglicht, gängige Entwicklungsoperationen wie das Formatieren des Codes, das Erstellen des Moduls, das Ausführen der Test-Suite und das Ausführen von Code-Analysen einfach durchzuführen. Sie können die Aufgaben-Definitionen in der Datei Makefile.toml einsehen. Die Installation von cargo-make führt zu einer eigenständigen ausführbaren Datei namens makers sowie einer cargo-Erweiterung, die über cargo make ausgeführt werden kann. Da dieses Projekt kein rust-Paket ist, wird empfohlen, einfach makers zu verwenden.
Beachten Sie auch, dass der Task Runner der Einfachheit halber Docker verwendet, um alle Aufgaben auszuführen. Das bedeutet, dass die erstellte Binärdatei nicht für Ihre Host-Plattform bestimmt ist.
Standardaufgabe
Um einen Mehrwert zu bieten, beginnt die Standardaufgabe (d. h. einfach makers allein auszuführen) eine interaktive Bash-Sitzung im Docker-Container, der für dieses Projekt verwendet wird.
Dies sollte bei der Fehlersuche und dem allgemeinen Workflow helfen.
Formatierung
Falsch formatierter Code führt dazu, dass der Linting-Job der GitHub-Aktionen fehlschlägt. Um dies zu vermeiden, können Sie die Formatierungsaufgabe vor dem Pushen neuer Änderungen ausführen, wie folgt:
makers format
Diese Formatierung erfolgt durch ein Tool namens clang-format. Die Konfigurationsoptionen dafür finden Sie in der Datei ./.clang-format.
Statische Code-Analyse
Sie können eine statische Analyse des Codes über die Analyse-Aufgabe durchführen:
makers analyse
Diese Analyse erfolgt durch ein Tool namens clang-tidy. Die Konfigurationsoptionen dafür finden Sie in der Datei ./.clang-tidy.
Testen
Sie können die Test-Suite mit der Test-Aufgabe ausführen, wie folgt:
makers test
Debugging
Wir können valgrind und gdb auf NGINX von innerhalb des Containers verwenden.
Öffnen Sie zuerst eine interaktive Shell im Container mit:
$ makers
Wir werden diese Sitzung verwenden, um valgrind auszuführen:
$ valgrind --vgdb=full --vgdb-error=0 /github/workspace/bin/static/nginx -p/github/workspace/t/servroot -cconf/nginx.conf
==15== Memcheck, ein Speicherfehlerdetektor
==15== Copyright (C) 2002-2017, und GNU GPL'd, von Julian Seward et al.
==15== Verwendung von Valgrind-3.13.0 und LibVEX; erneut mit -h ausführen für Copyright-Informationen
==15== Befehl: /github/workspace/bin/static/nginx -p/github/workspace/t/servroot -cconf/nginx.conf
==15==
==15== (Aktion beim Start) vgdb me ...
==15==
==15== UM DIESEN PROZESS MIT GDB ZU DEBUGGEN: Starten Sie GDB so
==15== /path/to/gdb /github/workspace/bin/static/nginx
==15== und geben Sie dann GDB den folgenden Befehl
==15== target remote | /usr/lib64/valgrind/../../bin/vgdb --pid=15
==15== --pid ist optional, wenn nur ein valgrind-Prozess läuft
==15==
Als Nächstes finden Sie die Container-ID, damit wir eine weitere Sitzung darin öffnen können:
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
55fab1e069ba act-github-actions-nginx-module-toolbox "bash" vor 4 Sekunden Vor 3 Sekunden 0.0.0.0:1984->1984/tcp serene_newton
Verwenden Sie entweder den Namen oder die ID, um eine Bash-Sitzung im Container auszuführen:
$ docker exec -it serene_newton bash
Wir werden diese Sitzung verwenden, um gdb zu starten und den Valgrind-GDB-Server anzusprechen, den wir in der anderen Sitzung gestartet haben:
$ gdb /github/workspace/bin/static/nginx
GNU gdb (GDB) Red Hat Enterprise Linux 8.0.1-30.amzn2.0.3
Copyright (C) 2017 Free Software Foundation, Inc.
Lizenz GPLv3+: GNU GPL-Version 3 oder später <http://gnu.org/licenses/gpl.html>
Dies ist freie Software: Sie dürfen sie ändern und weiterverbreiten.
Es gibt KEINE GARANTIE, soweit es das Gesetz erlaubt. Geben Sie "show copying"
und "show warranty" für Details ein.
Dieses GDB wurde als "x86_64-redhat-linux-gnu" konfiguriert.
Geben Sie "show configuration" für Konfigurationsdetails ein.
Für Anweisungen zum Melden von Fehlern siehe:
<http://www.gnu.org/software/gdb/bugs/>.
Finden Sie das GDB-Handbuch und andere Dokumentationsressourcen online unter:
<http://www.gnu.org/software/gdb/documentation/>.
Für Hilfe geben Sie "help" ein.
Geben Sie "apropos word" ein, um nach Befehlen zu suchen, die mit "word" zu tun haben...
Lese Symbole von /github/workspace/bin/static/nginx...fertig.
(gdb)
Vom gdb-Prompt aus richten Sie den Valgrind-Prozess ein und beginnen mit dem Debuggen:
(gdb) target remote | /usr/lib64/valgrind/../../bin/vgdb --pid=15
Remote-Debugging unter Verwendung von | /usr/lib64/valgrind/../../bin/vgdb --pid=15
Daten werden zwischen gdb und Prozess 15 weitergeleitet
Warnung: Das Remote-Ziel unterstützt keinen Dateitransfer, versucht, auf Dateien vom lokalen Dateisystem zuzugreifen.
Lese Symbole von /lib64/ld-linux-x86-64.so.2...(keine Debug-Symbole gefunden)...fertig.
0x0000000004000ef0 in _start () von /lib64/ld-linux-x86-64.so.2
Fehlende separate Debug-Infos, verwenden Sie: debuginfo-install glibc-2.26-35.amzn2.x86_64
(gdb)
Ausführen von GitHub-Aktionen
Mit act können Sie den Workflow simulieren, der auf den GitHub-Servern ausgeführt wird, sobald Sie Änderungen pushen.
Es gibt mehr als einen Job im Haupt-Workflow, daher müssen Sie den Test-Job angeben, wenn Sie act ausführen. Zum Beispiel können Sie diesen Befehl verwenden, um die Codeformatvalidierung auszuführen:
act -vj lint
Beachten Sie, dass der lint-Job Ihren Code nicht formatiert, sondern nur überprüft, ob die Formatierung wie erwartet ist.
Beachten Sie auch, dass -v verwendet wird, um den ausführlichen Modus zu aktivieren, um mehr Sichtbarkeit darüber zu geben, was act tut.
Die Jobs, die Sie (und sollten) lokal ausführen können, sind lint, build, analyse und test. Der test-Job hängt von der Ausgabe des build-Jobs ab. Um die Ausgabe des Build-Jobs zu behalten, können Sie das -b-Flag zu act hinzufügen, oder Sie können einfach den Task Runner verwenden, um zu bauen.
Bekannte Probleme
Im Moment? Keine! 🎉
Wenn Sie einen Fehler entdecken oder eine Frage haben, die Sie ansprechen möchten, bitte öffnen Sie ein Issue.
Originalautor
wdaike wdaike@163.com (https://github.com/wdaike), Baidu Inc.
GitHub
Sie finden zusätzliche Konfigurationstipps und Dokumentationen für dieses Modul im GitHub-Repository für nginx-module-upstream-jdomain.