agent
v2.39.0
NGINX Agent ist ein begleitender Daemon für Ihre NGINX Open Source- oder NGINX Plus-Instanz. Es ermöglicht:
Das Grafana-Dashboard zeigt die vom NGINX-Agenten gemeldeten Metriken
Der NGINX-Agent wird als Begleitprozess auf einem System ausgeführt, auf dem NGINX ausgeführt wird. Es bietet gRPC- und REST-Schnittstellen für das Konfigurationsmanagement und die Erfassung von Metriken aus dem NGINX-Prozess und dem Betriebssystem. Der NGINX-Agent ermöglicht die Remote-Interaktion mit NGINX mithilfe gängiger Linux-Tools und eröffnet die Möglichkeit, anspruchsvolle Überwachungs- und Steuerungssysteme zu erstellen, die große Sammlungen von NGINX-Instanzen verwalten können.
Der NGINX-Agent bietet eine API-Schnittstelle für die Übermittlung aktualisierter Konfigurationsdateien. Beim Empfang einer neuen Datei prüft es die Ausgabe von nginx -V um den Speicherort vorhandener Konfigurationen zu ermitteln. Anschließend validiert es die neue Konfiguration mit nginx -t bevor es sie über ein Signal-HUP an den NGINX-Masterprozess anwendet.
Der NGINX-Agent stellt eine Schnittstelle zu NGINX-Prozessinformationen her und analysiert NGINX-Protokolle, um Metriken zu berechnen und zu melden. Bei der Verbindung mit NGINX Plus ruft der NGINX-Agent relevante Informationen von der NGINX Plus-API ab. Gemeldete Metriken können von Prometheus aggregiert und mit Tools wie Grafana visualisiert werden.
Der NGINX-Agent hält eine Verbindung zur NGINX Plus-API offen und fragt basierend auf dem Erfassungsintervall ab. Diese Verbindung wird in den Metriken gemeldet und je nach Phase der Meldung kann diese Verbindung als inaktiv oder aktiv angezeigt werden.
Bei der Ausführung neben einer Open-Source-Instanz von NGINX erfordert der NGINX-Agent, dass die NGINX-Zugriffs- und Fehlerprotokolle aktiviert sind und alle Standardvariablen enthalten.
Damit der NGINX-Agent ordnungsgemäß mit einer NGINX Plus-Instanz funktioniert, muss die API in der nginx.conf dieser Instanz konfiguriert werden. Weitere Einzelheiten finden Sie unter Übersicht über Instanzmetriken. Sobald NGINX Plus mit dem /api/ -Endpunkt konfiguriert ist, verwendet der NGINX-Agent ihn automatisch beim Start.
Mit dem NGINX-Agenten kann ein mit gRPC verbundenes Steuerungssystem einen Listener für ein bestimmtes Ereignis registrieren. Der Kontrollmechanismus wird dann aufgerufen, wenn der NGINX-Agent ein zugehöriges Systemsignal sendet. Die Quelle einer Benachrichtigung kann entweder die NGINX-Instanz oder der NGINX-Agent selbst sein. Hier ist eine Liste der derzeit unterstützten Veranstaltungen:
| Ereignis | Beschreibung |
|---|---|
| AGENT_START_MESSAGE | Der NGINX-Agent-Prozess wurde gestartet |
| AGENT_STOP_MESSAGE | Der NGINX-Agent-Prozess wurde gestoppt |
| NGINX_FOUND_MESSAGE | NGINX-Masterprozess auf dem System erkannt |
| NGINX_STOP_MESSAGE | NGINX-Masterprozess gestoppt |
| NGINX_RELOAD_SUCCESS_MESSAGE | Der NGINX-Masterprozess wurde erfolgreich neu geladen |
| NGINX_RELOAD_FAILED_MESSAGE | Der NGINX-Masterprozess konnte nicht neu geladen werden |
| NGINX_WORKER_START_MESSAGE | Neuer NGINX-Workerprozess gestartet |
| NGINX_WORKER_STOP_MESSAGE | Der NGINX-Workerprozess wurde gestoppt |
| CONFIG_APPLY_SUCCESS_MESSAGE | Neue NGINX-Konfiguration erfolgreich angewendet |
| CONFIG_APPLY_FAILURE_MESSAGE | Die neue NGINX-Konfiguration konnte nicht angewendet werden |
| CONFIG_ROLLBACK_SUCCESS_MESSAGE | Die NGINX-Konfiguration wurde erfolgreich zurückgesetzt |
| CONFIG_ROLLBACK_FAILURE_MESSAGE | Das Zurücksetzen der NGINX-Konfiguration ist fehlgeschlagen |
Der NGINX-Agent stellt eine direkte Schnittstelle zu einem NGINX-Serverprozess her, der auf demselben System installiert ist. Wenn Sie es noch nicht haben, befolgen Sie diese Schritte, um NGINX Open Source oder NGINX Plus zu installieren. Stellen Sie nach der Installation sicher, dass die NGINX-Instanz ausgeführt wird.
Um den NGINX-Agenten auf Ihrem System zu installieren, gehen Sie zu „Releases“ und laden Sie das neueste Paket herunter, das von Ihrer Betriebssystemverteilung und CPU-Architektur unterstützt wird.
Verwenden Sie den Paketmanager Ihres Systems, um das Paket zu installieren. Einige Beispiele:
Debian, Ubuntu und andere Distributionen verwenden den dpkg Paketmanager.
sudo dpkg -i nginx-agent-<agent-version>.deb
RHEL, CentOS RHEL, Amazon Linux, Oracle Linux und andere Distributionen, die den yum Paketmanager verwenden
sudo yum localinstall nginx-agent-<agent-version>.rpm
RHEL und andere Distributionen verwenden den rpm Paketmanager
sudo rpm -i nginx-agent-<agent-version>.rpm
Alpine Linux
sudo apk add nginx-agent-<agent-version>.apk
FreeBSD
sudo pkg add nginx-agent-<agent-version>.pkg
Um den NGINX-Agenten auf systemd-Systemen zu starten, führen Sie den folgenden Befehl aus:
sudo systemctl start nginx-agent
Um den Start des NGINX-Agenten beim Booten zu ermöglichen, führen Sie den folgenden Befehl aus:
sudo systemctl enable nginx-agent
Verwenden Sie unter Alpine Linux den folgenden Befehl, um den Agenten zu starten:
sudo service nginx-agent start
Führen Sie Folgendes aus, damit der Agent beim Booten unter Alpine Linux gestartet werden kann:
sudo rc-update add nginx-agent default
Der NGINX-Agent verwendet formatierte Protokolldateien, um Metriken zu sammeln. Durch die Erweiterung der Protokollformate und Instanzzahlen erhöht sich auch die Größe der Protokolldateien des NGINX-Agenten. Wir empfehlen, eine separate Partition für /var/log/nginx-agent hinzuzufügen. Ohne Protokollrotation oder Speicherung auf einer separaten Partition könnten Protokolldateien den gesamten freien Speicherplatz auf dem Laufwerk belegen und dazu führen, dass Ihr System nicht mehr auf bestimmte Dienste reagiert.
Standardmäßig rotiert der NGINX-Agent Protokolle täglich mit logrotate mit der folgenden Konfiguration:
/var/log/nginx-agent/*.log
{
# log files are rotated every day
daily
# log files are rotated if they grow bigger than 5M
size 5M
# truncate the original log file after creating a copy
copytruncate
# remove rotated logs older than 10 days
maxage 10
# log files are rotated 10 times before being removed
rotate 10
# old log files are compressed
compress
# if the log file is missing it will go on to the next one without issuing an error message
missingok
# do not rotate the log if it is empty
notifempty
} Wenn Sie Änderungen an der Standardkonfiguration vornehmen müssen, können Sie die Datei hier /etc/logrotate.d/nginx-agent aktualisieren
Weitere Einzelheiten zur Logrotate-Konfiguration finden Sie unter Logrotate-Konfigurationsoptionen
Um ein Image zu erstellen, das den neuesten NGINX-Agenten, die neueste Hauptversion von NGINX OSS auf dem neuesten Alpine enthält, führen Sie den folgenden Befehl aus:
make official-oss-imageUm ein Image zu erstellen, das den neuesten NGINX-Agenten, die neueste stabile Version von NGINX OSS auf dem neuesten Alpine enthält, führen Sie den folgenden Befehl aus:
make official-oss-stable-imageWeitere Informationen zum Ausführen von NGINX-Agent-Containern und zum Erstellen eines Images, das NGINX Plus anstelle von NGINX OSS verwendet, finden Sie unter Docker-Images
Befolgen Sie diese Schritte, um den NGINX-Agenten und eine Scheinschnittstelle („Steuerungsebene“) zu konfigurieren und auszuführen, an die der NGINX-Agent Berichte sendet.
Befolgen Sie die Schritte im Abschnitt „Installation“, um NGINX herunterzuladen, zu installieren und auszuführen.
Klonen Sie mit Ihrer bevorzugten Methode das NGINX-Agent-Repository in Ihr Entwicklungsverzeichnis. Weitere Hilfe finden Sie unter Klonen eines GitHub-Repositorys.
Der NGINX-Agent und die Mock Control Plane sind in Go geschrieben. Zum Erstellen und Ausführen einer der beiden Anwendungen aus dem Quellcodeverzeichnis ist Go 1.23 oder höher erforderlich. Sie können Go von der offiziellen Website herunterladen.
Starten Sie die Scheinsteuerungsebene, indem Sie den folgenden Befehl im Stammverzeichnis des agent Quellcodes ausführen:
go run sdk/examples/server.go
# Command Output
INFO[0000] http listening at 54790 # mock control plane port
INFO[0000] gRPC listening at 54789 # gRPC control plane port which NGINX Agent will report to
Wenn es noch nicht vorhanden ist, erstellen Sie das Verzeichnis /etc/nginx-agent/ und kopieren Sie die Datei nginx-agent.conf aus dem Stammverzeichnis des Projekts hinein.
sudo mkdir /etc/nginx-agent
sudo cp <project_root_directory>/nginx-agent.conf /etc/nginx-agent/
Erstellen Sie die Datei agent-dynamic.conf im Verzeichnis /etc/nginx-agent/ , die für die Ausführung des NGINX-Agenten erforderlich ist.
sudo touch /var/lib/nginx-agent/agent-dynamic.conf
Fügen Sie die folgenden Einstellungen zu /etc/nginx-agent/nginx-agent.conf hinzu:
server :
host : 127.0.0.1 # mock control plane host
grpcPort : 54789 # mock control plane gRPC port
# gRPC TLS options - DISABLING TLS IS NOT RECOMMENDED FOR PRODUCTION
tls :
enable : false
skip_verify : trueWeitere Informationen finden Sie unter Definitionen und Dokumentation des Agentenprotokolls
Die REST-Schnittstelle des NGINX-Agenten kann verfügbar gemacht werden, indem überprüft wird, ob die folgenden Zeilen in der Datei /etc/nginx-agent/nginx-agent.conf vorhanden sind:
api :
# Set API address to allow remote management
host : 127.0.0.1
# Set this value to a secure port number to prevent information leaks
port : 8038
# REST TLS parameters
cert : " <TLS-CERTIFICATE>.crt "
key : " <PRIVATE-KEY>.key "Die Scheinsteuerungsebene kann entweder gRPC- oder REST-Protokolle verwenden, um mit dem NGINX-Agenten zu kommunizieren.
Für die Swagger-Benutzeroberfläche muss Goswagger installiert sein. Weitere Hilfe finden Sie in den Anweisungen zur Installation von Goswagger.
Um die Swagger-Benutzeroberfläche für die REST-Schnittstelle zu starten, führen Sie den folgenden Befehl aus
make launch-swagger-ui
Öffnen Sie einen Webbrowser, um die Swagger-Benutzeroberfläche unter http://localhost:8082/docs anzuzeigen.
Eine Erweiterung ist ein Codestück, das für die Hauptfunktionalität, für die der NGINX-Agent verantwortlich ist, nicht entscheidend ist. Dies fällt im Allgemeinen nicht in den Zuständigkeitsbereich der Verwaltung der NGINX-Konfiguration und der Berichterstattung über NGINX-Metriken.
Um eine Erweiterung zu aktivieren, muss sie zur Erweiterungsliste in /etc/nginx-agent/nginx-agent.conf hinzugefügt werden. Hier ist ein Beispiel für die Aktivierung der erweiterten Metrikerweiterung:
extensions :
- advanced-metrics Wenn er bereits ausgeführt wird, starten Sie den NGINX-Agenten neu, um die neue Konfiguration anzuwenden. Wenn der NGINX-Agent nicht ausgeführt wird, können Sie ihn alternativ auch aus dem Stammverzeichnis des Quellcodes ausführen.
Öffnen Sie ein weiteres Terminalfenster und starten Sie den NGINX-Agenten. Geben Sie den folgenden Befehl aus dem Stammverzeichnis agent -Quellcodes aus.
sudo make run
# Command Output snippet
WARN[0000] Log level is info
INFO[0000] setting displayName to XXX
INFO[0000] NGINX Agent at with pid 12345, clientID=XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX name=XXX
INFO[0000] NginxBinary initializing
INFO[0000] Commander initializing
INFO[0000] Comms initializing
INFO[0000] OneTimeRegistration initializing
INFO[0000] Registering XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX
INFO[0000] Metrics initializing
INFO[0000] MetricsThrottle initializing
INFO[0000] DataPlaneStatus initializing
INFO[0000] MetricsThrottle waiting for report ready
INFO[0000] Metrics waiting for handshake to be completed
INFO[0000] ProcessWatcher initializing
INFO[0000] Extensions initializing
INFO[0000] FileWatcher initializing
INFO[0000] FileWatchThrottle initializing
INFO[0001] Events initializing
INFO[0001] OneTimeRegistration completed
Öffnen Sie einen Webbrowser, um die Scheinsteuerungsebene unter http://localhost:54790 anzuzeigen. Die folgenden Links werden in der Weboberfläche angezeigt:
Weitere Anwendungsfälle für NGINX-Agenten finden Sie unter https://github.com/nginx/agent/tree/main/sdk/examples
Während die meisten Linux- oder FreeBSD-Betriebssysteme verwendet werden können, um zum NGINX-Agent-Projekt beizutragen, wurden die folgenden Schritte für Ubuntu entwickelt. Ubuntu enthält die meisten Bibliotheken, die zum Erstellen und Ausführen des NGINX-Agenten erforderlich sind, und ist die empfohlene Plattform für die Entwicklung des NGINX-Agenten.
Befolgen Sie die Schritte im Abschnitt „Installation“, um NGINX herunterzuladen und zu installieren. Stellen Sie nach der Installation sicher, dass die NGINX-Instanz ausgeführt wird.
Befolgen Sie die Schritte im Abschnitt „Erste Schritte mit dem NGINX-Agenten“, um das NGINX-Agenten-Repository zu klonen
Abhängig von der Betriebssystemverteilung kann es erforderlich sein, die folgenden Pakete zu installieren, um den NGINX-Agenten zu erstellen.
Wechseln Sie in das Quellverzeichnis des NGINX-Agenten:
cd <path_to_development_directory>/agent
Installieren Sie Make:
sudo apt install make
Der NGINX-Agent ist in Go geschrieben. Sie können Go herunterladen und den Installationsanweisungen auf derselben Seite folgen oder Folgendes ausführen:
sudo apt install golang-go
Protokoll installieren:
sudo apt install -y protobuf-compiler
Installieren Sie die NGINX-Agent-Tools und -Abhängigkeiten:
Bevor Sie mit der Entwicklung des NGINX-Agenten beginnen, ist es wichtig, die für den NGINX-Agenten erforderlichen Tools und Abhängigkeiten herunterzuladen und zu installieren. Sie können dies tun, indem Sie den folgenden make -Befehl ausführen:
make install-tools
Führen Sie die folgenden Befehle aus, um den NGINX-Agenten zu erstellen und auszuführen:
make build
sudo make run
Der NGINX-Agent kann in den meisten Umgebungen ausgeführt werden. Eine Liste der unterstützten Distributionen finden Sie im Leitfaden zu den technischen Daten von NGINX.
Der NGINX-Agent kann in den folgenden Umgebungen bereitgestellt werden:
NGINX Agent funktioniert mit allen unterstützten Versionen von NGINX Open Source und NGINX Plus.
Empfehlungen zur Mindestsystemgröße für NGINX Agent:
| CPU | Erinnerung | Netzwerk | Lagerung |
|---|---|---|---|
| 1 CPU-Kern | 1 GB RAM | 1 GbE-NIC | 20 GB |
Unser Slack-Kanal #nginx-agent ist die Anlaufstelle, um Fragen zu stellen und Ihre Gedanken auszutauschen.
Unsere GitHub-Problemseite bietet Raum für eine technischere Diskussion in Ihrem eigenen Tempo.
Beteiligen Sie sich am Projekt, indem Sie einen Beitrag leisten! Weitere Informationen finden Sie in unserem Beitragsleitfaden.
Besuchen Sie unsere Release-Seite, um den Überblick über Updates zu behalten.
Apache-Lizenz, Version 2.0
