agent
v2.39.0
NGINX Agent est un démon compagnon pour votre instance NGINX Open Source ou NGINX Plus. Il permet :
Tableau de bord Grafana affichant les métriques rapportées par l'agent NGINX
L'agent NGINX s'exécute en tant que processus compagnon sur un système exécutant NGINX. Il fournit des interfaces gRPC et REST pour la gestion de la configuration et la collecte de métriques à partir du processus et du système d'exploitation NGINX. L'agent NGINX permet une interaction à distance avec NGINX à l'aide d'outils Linux courants et ouvre la possibilité de créer des systèmes de surveillance et de contrôle sophistiqués capables de gérer de grandes collections d'instances NGINX.
L'agent NGINX fournit une interface API pour la soumission des fichiers de configuration mis à jour. Dès réception d'un nouveau fichier, il vérifie la sortie de nginx -V pour déterminer l'emplacement des configurations existantes. Il valide ensuite la nouvelle configuration avec nginx -t avant de l'appliquer via un signal HUP au processus maître NGINX.
L'agent NGINX s'interface avec les informations de processus NGINX et analyse les journaux NGINX pour calculer et rapporter les métriques. Lors de l'interface avec NGINX Plus, l'agent NGINX extrait les informations pertinentes de l'API NGINX Plus. Les métriques rapportées peuvent être agrégées par Prometheus et visualisées avec des outils comme Grafana.
L'agent NGINX maintient une connexion ouverte à l'API NGINX Plus et aux requêtes en fonction de l'intervalle de collecte. Cette connexion est signalée dans les métriques et, selon la phase de reporting, cette connexion peut apparaître comme inactive ou active.
Lorsqu'il est exécuté avec une instance open source de NGINX, l'agent NGINX nécessite que les journaux d'accès et d'erreurs NGINX soient activés et contiennent toutes les variables par défaut.
Pour que l'agent NGINX fonctionne correctement avec une instance NGINX Plus, l'API doit être configurée dans le fichier nginx.conf de cette instance. Voir Présentation des métriques d'instance pour plus de détails. Une fois NGINX Plus configuré avec le point de terminaison /api/ , l'agent NGINX l'utilisera automatiquement au démarrage.
L'agent NGINX permet à un système de contrôle connecté à gRPC d'enregistrer un auditeur pour un événement spécifique. Le mécanisme de contrôle est ensuite invoqué lorsque l'agent NGINX envoie un signal système associé. La source d'une notification peut être soit l'instance NGINX, soit l'agent NGINX lui-même. Voici une liste des événements actuellement pris en charge :
| Événement | Description |
|---|---|
| AGENT_START_MESSAGE | Le processus de l'agent NGINX a démarré |
| AGENT_STOP_MESSAGE | Le processus de l'agent NGINX s'est arrêté |
| NGINX_FOUND_MESSAGE | Processus maître NGINX détecté sur le système |
| NGINX_STOP_MESSAGE | Processus maître NGINX arrêté |
| NGINX_RELOAD_SUCCESS_MESSAGE | Processus maître NGINX rechargé avec succès |
| NGINX_RELOAD_FAILED_MESSAGE | Le processus maître NGINX n'a pas réussi à recharger |
| NGINX_WORKER_START_MESSAGE | Nouveau processus de travail NGINX démarré |
| NGINX_WORKER_STOP_MESSAGE | Le processus de travail NGINX s'est arrêté |
| CONFIG_APPLY_SUCCESS_MESSAGE | Application réussie de la nouvelle configuration NGINX |
| CONFIG_APPLY_FAILURE_MESSAGE | Échec de l'application de la nouvelle configuration NGINX |
| CONFIG_ROLLBACK_SUCCESS_MESSAGE | Configuration NGINX restaurée avec succès |
| CONFIG_ROLLBACK_FAILURE_MESSAGE | Échec de la restauration de la configuration NGINX |
L'agent NGINX s'interface directement avec un processus serveur NGINX installé sur le même système. Si vous ne l'avez pas déjà, suivez ces étapes pour installer NGINX Open Source ou NGINX Plus. Une fois installée, assurez-vous que l'instance NGINX est en cours d'exécution.
Pour installer l'agent NGINX sur votre système, accédez à Versions et téléchargez le dernier package pris en charge par la distribution de votre système d'exploitation et l'architecture de votre processeur.
Utilisez le gestionnaire de packages de votre système pour installer le package. Quelques exemples :
Debian, Ubuntu et autres distributions utilisant le gestionnaire de paquets dpkg .
sudo dpkg -i nginx-agent-<agent-version>.deb
RHEL, CentOS RHEL, Amazon Linux, Oracle Linux et autres distributions utilisant le gestionnaire de packages yum
sudo yum localinstall nginx-agent-<agent-version>.rpm
RHEL et autres distributions utilisant le gestionnaire de packages rpm
sudo rpm -i nginx-agent-<agent-version>.rpm
Linux alpin
sudo apk add nginx-agent-<agent-version>.apk
GratuitBSD
sudo pkg add nginx-agent-<agent-version>.pkg
Pour démarrer l'agent NGINX sur les systèmes systemd, exécutez la commande suivante :
sudo systemctl start nginx-agent
Pour permettre à l'agent NGINX de démarrer au démarrage, exécutez la commande suivante :
sudo systemctl enable nginx-agent
Sous Alpine Linux, utilisez la commande suivante pour démarrer l'agent :
sudo service nginx-agent start
Pour permettre à l'agent de démarrer au démarrage sur Alpine Linux, exécutez ceci :
sudo rc-update add nginx-agent default
L'agent NGINX utilise des fichiers journaux formatés pour collecter des métriques. L'expansion des formats de journaux et du nombre d'instances augmentera également la taille des fichiers journaux de l'agent NGINX. Nous vous recommandons d'ajouter une partition distincte pour /var/log/nginx-agent . Sans rotation des journaux ni stockage sur une partition distincte, les fichiers journaux pourraient utiliser tout l'espace disque libre et empêcher votre système de répondre à certains services.
Par défaut, l'agent NGINX effectue une rotation quotidienne des journaux à l'aide de logrotate avec la configuration suivante :
/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
} Si vous devez apporter des modifications à la configuration par défaut, vous pouvez mettre à jour le fichier ici /etc/logrotate.d/nginx-agent
Pour plus de détails sur la configuration de Logrotate, voir Options de configuration de Logrotate.
Pour créer une image contenant le dernier agent NGINX, la dernière version principale de NGINX OSS sur la dernière version d'Alpine, exécutez la commande suivante :
make official-oss-imagePour créer une image contenant le dernier agent NGINX, la dernière version stable de NGINX OSS sur la dernière version d'Alpine, exécutez la commande suivante :
make official-oss-stable-imagePour plus d'informations sur la façon d'exécuter les conteneurs de l'agent NGINX et de créer une image qui utilise NGINX Plus au lieu de NGINX OSS, consultez Images Docker.
Suivez ces étapes pour configurer et exécuter l'agent NGINX et une interface fictive (« plan de contrôle ») à laquelle l'agent NGINX fera rapport.
Suivez les étapes de la section Installation pour télécharger, installer et exécuter NGINX.
À l'aide de votre méthode préférée, clonez le référentiel de l'agent NGINX dans votre répertoire de développement. Voir Clonage d'un référentiel GitHub pour une aide supplémentaire.
L'agent NGINX et le plan de contrôle simulé sont écrits en Go. Go 1.23 ou supérieur est requis pour créer et exécuter l’une ou l’autre application à partir du répertoire de code source. Vous pouvez télécharger Go depuis le site officiel.
Démarrez le plan de contrôle fictif en exécutant la commande suivante à partir du répertoire racine du code source agent :
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
S'il n'existe pas déjà, créez le répertoire /etc/nginx-agent/ et copiez-y le fichier nginx-agent.conf à partir du répertoire racine du projet.
sudo mkdir /etc/nginx-agent
sudo cp <project_root_directory>/nginx-agent.conf /etc/nginx-agent/
Créez le fichier agent-dynamic.conf dans le répertoire /etc/nginx-agent/ , requis pour l'exécution de l'agent NGINX.
sudo touch /var/lib/nginx-agent/agent-dynamic.conf
Ajoutez les paramètres suivants à /etc/nginx-agent/nginx-agent.conf :
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 : truePour plus d'informations, consultez Définitions et documentation du protocole d'agent.
L'interface REST de l'agent NGINX peut être exposée en validant la présence des lignes suivantes dans le fichier /etc/nginx-agent/nginx-agent.conf :
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 "Le plan de contrôle fictif peut utiliser les protocoles gRPC ou REST pour communiquer avec l'agent NGINX.
L'interface utilisateur de Swagger nécessite que Goswagger soit installé. Consultez les instructions d’installation de goswagger pour obtenir une aide supplémentaire.
Pour lancer l'interface utilisateur Swagger pour l'interface REST, exécutez la commande suivante
make launch-swagger-ui
Ouvrez un navigateur Web pour afficher l'interface utilisateur de Swagger à l'adresse http://localhost:8082/docs.
Une extension est un morceau de code non critique pour la fonctionnalité principale dont l'agent NGINX est responsable. Cela ne relève généralement pas de la gestion de la configuration NGINX et du reporting des métriques NGINX.
Pour activer une extension, elle doit être ajoutée à la liste des extensions dans le /etc/nginx-agent/nginx-agent.conf . Voici un exemple d’activation de l’extension de métriques avancées :
extensions :
- advanced-metrics S'il est déjà en cours d'exécution, redémarrez l'agent NGINX pour appliquer la nouvelle configuration. Alternativement, si l'agent NGINX n'est pas en cours d'exécution, vous pouvez l'exécuter à partir du répertoire racine du code source.
Ouvrez une autre fenêtre de terminal et démarrez l'agent NGINX. Exécutez la commande suivante à partir du répertoire racine du code source agent .
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
Ouvrez un navigateur Web pour afficher le plan de contrôle fictif à l'adresse http://localhost:54790. Les liens suivants seront affichés dans l'interface Web :
Pour plus de cas d'utilisation de l'agent NGINX, reportez-vous à https://github.com/nginx/agent/tree/main/sdk/examples
Bien que la plupart des systèmes d'exploitation Linux ou FreeBSD puissent être utilisés pour contribuer au projet NGINX Agent, les étapes suivantes ont été conçues pour Ubuntu. Ubuntu est fourni avec la plupart des bibliothèques requises pour créer et exécuter l'agent NGINX et constitue la plate-forme recommandée pour le développement de l'agent NGINX.
Suivez les étapes de la section Installation pour télécharger et installer NGINX. Une fois installé, assurez-vous que l'instance NGINX est en cours d'exécution.
Suivez les étapes de la section Mise en route avec l'agent NGINX pour cloner le référentiel de l'agent NGINX.
En fonction de la distribution du système d'exploitation, il peut être nécessaire d'installer les packages suivants afin de créer l'agent NGINX.
Accédez au répertoire source de l'agent NGINX :
cd <path_to_development_directory>/agent
Installer la marque :
sudo apt install make
L'agent NGINX est écrit en Go. Vous pouvez télécharger Go et suivre les instructions d'installation sur la même page ou exécuter :
sudo apt install golang-go
Protocole d'installation :
sudo apt install -y protobuf-compiler
Installez les outils et les dépendances de l'agent NGINX :
Avant de commencer le développement sur l'agent NGINX, il est important de télécharger et d'installer l'outil et les dépendances nécessaires requis par l'agent NGINX. Vous pouvez le faire en exécutant la commande make suivante :
make install-tools
Exécutez les commandes suivantes pour créer et exécuter l'agent NGINX :
make build
sudo make run
L'agent NGINX peut s'exécuter dans la plupart des environnements. Pour une liste des distributions prises en charge, consultez le guide des spécifications techniques NGINX.
L'agent NGINX peut être déployé dans les environnements suivants :
NGINX Agent fonctionne avec toutes les versions prises en charge de NGINX Open Source et NGINX Plus.
Recommandations de taille minimale du système pour l'agent NGINX :
| Processeur | Mémoire | Réseau | Stockage |
|---|---|---|---|
| 1 cœur de processeur | 1 Go de RAM | Carte réseau 1 GbE | 20 Go |
Notre chaîne Slack #nginx-agent est l'endroit idéal pour commencer à poser des questions et à partager vos réflexions.
Notre page des problèmes GitHub offre un espace pour une discussion plus technique à votre rythme.
Impliquez-vous dans le projet en contribuant ! Veuillez consulter notre guide de contribution pour plus de détails.
Consultez notre page de publication pour suivre les mises à jour.
Licence Apache, version 2.0
