agent
v2.39.0
NGINX Agent es un demonio complementario para su instancia NGINX Open Source o NGINX Plus. Permite:
Panel de control de Grafana que muestra las métricas informadas por el agente NGINX
NGINX Agent se ejecuta como un proceso complementario en un sistema que ejecuta NGINX. Proporciona interfaces gRPC y REST para la gestión de la configuración y la recopilación de métricas del proceso y el sistema operativo NGINX. NGINX Agent permite la interacción remota con NGINX utilizando herramientas comunes de Linux y desbloquea la capacidad de crear sistemas sofisticados de monitoreo y control que pueden administrar grandes colecciones de instancias de NGINX.
NGINX Agent proporciona una interfaz API para el envío de archivos de configuración actualizados. Al recibir un nuevo archivo, verifica la salida de nginx -V para determinar la ubicación de las configuraciones existentes. Luego valida la nueva configuración con nginx -t antes de aplicarla mediante una señal HUP al proceso maestro NGINX.
NGINX Agent interactúa con la información del proceso NGINX y analiza los registros de NGINX para calcular e informar métricas. Al interactuar con NGINX Plus, NGINX Agent extrae información relevante de la API de NGINX Plus. Prometheus puede agregar las métricas informadas y visualizarlas con herramientas como Grafana.
El Agente NGINX mantiene una conexión abierta a la API NGINX Plus y realiza consultas según el intervalo de recopilación. Esta conexión se informa en las métricas y, según la fase de generación de informes, esta conexión puede aparecer como inactiva o activa.
Cuando se ejecuta junto con una instancia de código abierto de NGINX, NGINX Agent requiere que los registros de acceso y errores de NGINX estén activados y contengan todas las variables predeterminadas.
Para que NGINX Agent funcione correctamente con una instancia de NGINX Plus, la API debe configurarse en nginx.conf de esa instancia. Consulte Descripción general de las métricas de instancia para obtener más detalles. Una vez que NGINX Plus esté configurado con el punto final /api/ , NGINX Agent lo usará automáticamente al inicio.
NGINX Agent permite que un sistema de control conectado a gRPC registre un oyente para un evento específico. Luego, el mecanismo de control se invoca cuando el Agente NGINX envía una señal del sistema asociada. La fuente de una notificación puede ser la instancia de NGINX o el propio Agente NGINX. Aquí hay una lista de eventos actualmente admitidos:
| Evento | Descripción |
|---|---|
| AGENT_START_MESSAGE | Se inició el proceso del Agente NGINX |
| AGENT_STOP_MESSAGE | El proceso del agente NGINX se detuvo |
| NGINX_FOUND_MESSAGE | Proceso maestro NGINX detectado en el sistema |
| NGINX_STOP_MESSAGE | El proceso maestro NGINX se detuvo |
| NGINX_RELOAD_SUCCESS_MESSAGE | El proceso maestro NGINX se recargó exitosamente |
| NGINX_RELOAD_FAILED_MESSAGE | El proceso maestro de NGINX no pudo recargarse |
| NGINX_WORKER_START_MESSAGE | Se inició un nuevo proceso de trabajo NGINX |
| NGINX_WORKER_STOP_MESSAGE | El proceso de trabajo de NGINX se detuvo |
| CONFIG_APPLY_SUCCESS_MESSAGE | Nueva configuración de NGINX aplicada con éxito |
| CONFIG_APPLY_FAILURE_MESSAGE | No se pudo aplicar la nueva configuración de NGINX |
| CONFIG_ROLLBACK_SUCCESS_MESSAGE | Configuración de NGINX revertida con éxito |
| CONFIG_ROLLBACK_FAILURE_MESSAGE | No se pudo revertir la configuración de NGINX |
NGINX Agent interactúa directamente con un proceso de servidor NGINX instalado en el mismo sistema. Si aún no lo tiene, siga estos pasos para instalar NGINX Open Source o NGINX Plus. Una vez instalada, asegúrese de que la instancia NGINX se esté ejecutando.
Para instalar NGINX Agent en su sistema, vaya a Versiones y descargue el paquete más reciente compatible con la distribución de su sistema operativo y la arquitectura de su CPU.
Utilice el administrador de paquetes de su sistema para instalar el paquete. Algunos ejemplos:
Debian, Ubuntu y otras distribuciones que utilizan el administrador de paquetes dpkg .
sudo dpkg -i nginx-agent-<agent-version>.deb
RHEL, CentOS RHEL, Amazon Linux, Oracle Linux y otras distribuciones que utilizan el administrador de paquetes yum
sudo yum localinstall nginx-agent-<agent-version>.rpm
RHEL y otras distribuciones que utilizan el administrador de paquetes rpm
sudo rpm -i nginx-agent-<agent-version>.rpm
Linux alpino
sudo apk add nginx-agent-<agent-version>.apk
FreeBSD
sudo pkg add nginx-agent-<agent-version>.pkg
Para iniciar el Agente NGINX en sistemas systemd, ejecute el siguiente comando:
sudo systemctl start nginx-agent
Para permitir que el Agente NGINX se inicie en el arranque, ejecute el siguiente comando:
sudo systemctl enable nginx-agent
En Alpine Linux, utilice el siguiente comando para iniciar el agente:
sudo service nginx-agent start
Para permitir que el agente se inicie en el momento del arranque en Alpine Linux, ejecute esto:
sudo rc-update add nginx-agent default
NGINX Agent utiliza archivos de registro formateados para recopilar métricas. La expansión de los formatos de registro y el recuento de instancias también aumentará el tamaño de los archivos de registro del Agente NGINX. Recomendamos agregar una partición separada para /var/log/nginx-agent . Sin rotación de registros o almacenamiento en una partición separada, los archivos de registro podrían consumir todo el espacio libre en el disco y hacer que su sistema deje de responder a ciertos servicios.
De forma predeterminada, NGINX Agent rota los registros diariamente usando logrotate con la siguiente configuración:
/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 necesita realizar cambios en la configuración predeterminada, puede actualizar el archivo aquí /etc/logrotate.d/nginx-agent
Para obtener más detalles sobre la configuración de logrotate, consulte Opciones de configuración de Logrotate.
Para crear una imagen que contenga el último agente NGINX, la última versión principal de NGINX OSS en la última versión de Alpine, ejecute el siguiente comando:
make official-oss-imagePara crear una imagen que contenga el último agente NGINX, la última versión estable de NGINX OSS en el último Alpine, ejecute el siguiente comando:
make official-oss-stable-imagePara obtener más información sobre cómo ejecutar contenedores del Agente NGINX y cómo crear una imagen que utilice NGINX Plus en lugar de NGINX OSS, consulte Imágenes de Docker.
Siga estos pasos para configurar y ejecutar el Agente NGINX y una interfaz simulada ("plano de control") a la que informará el Agente NGINX.
Siga los pasos de la sección Instalación para descargar, instalar y ejecutar NGINX.
Utilizando su método preferido, clone el repositorio del Agente NGINX en su directorio de desarrollo. Consulte Clonar un repositorio de GitHub para obtener ayuda adicional.
El agente NGINX y el plano de control simulado están escritos en Go. Se requiere Go 1.23 o superior para compilar y ejecutar cualquiera de las aplicaciones desde el directorio del código fuente. Puedes descargar Go desde el sitio web oficial.
Inicie el plano de control simulado ejecutando el siguiente comando desde el directorio raíz del código fuente 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
Si aún no existe, cree el directorio /etc/nginx-agent/ y copie el archivo nginx-agent.conf desde el directorio raíz del proyecto.
sudo mkdir /etc/nginx-agent
sudo cp <project_root_directory>/nginx-agent.conf /etc/nginx-agent/
Cree el archivo agent-dynamic.conf en el directorio /etc/nginx-agent/ , que es necesario para que se ejecute NGINX Agent.
sudo touch /var/lib/nginx-agent/agent-dynamic.conf
Agregue las siguientes configuraciones a /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 : truePara obtener más información, consulte Definiciones y documentación del protocolo del agente.
La interfaz REST del Agente NGINX se puede exponer validando que las siguientes líneas en el archivo /etc/nginx-agent/nginx-agent.conf estén presentes:
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 "El plano de control simulado puede utilizar protocolos gRPC o REST para comunicarse con el Agente NGINX.
La interfaz de usuario de Swagger requiere la instalación de goswagger. Consulte las instrucciones para instalar goswagger para obtener ayuda adicional.
Para iniciar la interfaz de usuario de Swagger para la interfaz REST, ejecute el siguiente comando
make launch-swagger-ui
Abra un navegador web para ver la interfaz de usuario de Swagger en http://localhost:8082/docs.
Una extensión es un fragmento de código que no es fundamental para la funcionalidad principal de la que es responsable el agente NGINX. Por lo general, esto queda fuera del ámbito de gestión de la configuración de NGINX y de informes de métricas de NGINX.
Para habilitar una extensión, se debe agregar a la lista de extensiones en /etc/nginx-agent/nginx-agent.conf . A continuación se muestra un ejemplo de cómo habilitar la extensión de métricas avanzadas:
extensions :
- advanced-metrics Si ya se está ejecutando, reinicie NGINX Agent para aplicar la nueva configuración. Alternativamente, si NGINX Agent no se está ejecutando, puede ejecutarlo desde el directorio raíz del código fuente.
Abra otra ventana de terminal e inicie el Agente NGINX. Emita el siguiente comando desde el directorio raíz del código fuente 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
Abra un navegador web para ver el plano de control simulado en http://localhost:54790. Los siguientes enlaces se mostrarán en la interfaz web:
Para obtener más casos de uso del Agente NGINX, consulte https://github.com/nginx/agent/tree/main/sdk/examples
Si bien la mayoría de los sistemas operativos Linux o FreeBSD se pueden utilizar para contribuir al proyecto NGINX Agent, los siguientes pasos se han diseñado para Ubuntu. Ubuntu incluye la mayoría de las bibliotecas necesarias para crear y ejecutar NGINX Agent, y es la plataforma recomendada para el desarrollo de NGINX Agent.
Siga los pasos de la sección Instalación para descargar e instalar NGINX. Una vez instalada, asegúrese de que la instancia NGINX se esté ejecutando.
Siga los pasos de la sección Introducción al agente NGINX para clonar el repositorio del agente NGINX.
Dependiendo de la distribución del sistema operativo, puede que sea necesario instalar los siguientes paquetes para poder compilar NGINX Agent.
Cambie al directorio de origen del Agente NGINX:
cd <path_to_development_directory>/agent
Instalar hacer:
sudo apt install make
El agente NGINX está escrito en Go. Puede descargar Go y seguir las instrucciones de instalación en la misma página o ejecutar:
sudo apt install golang-go
Instalar protocolo:
sudo apt install -y protobuf-compiler
Instale las herramientas y dependencias del Agente NGINX:
Antes de comenzar el desarrollo del Agente NGINX, es importante descargar e instalar la herramienta necesaria y las dependencias que requiere el Agente NGINX. Puedes hacer esto ejecutando el siguiente comando make :
make install-tools
Ejecute los siguientes comandos para compilar y ejecutar el Agente NGINX:
make build
sudo make run
NGINX Agent puede ejecutarse en la mayoría de los entornos. Para obtener una lista de distribuciones compatibles, consulte la guía de especificaciones técnicas de NGINX.
NGINX Agent se puede implementar en los siguientes entornos:
NGINX Agent funciona con todas las versiones compatibles de NGINX Open Source y NGINX Plus.
Recomendaciones mínimas de tamaño del sistema para NGINX Agent:
| UPC | Memoria | Red | Almacenamiento |
|---|---|---|---|
| 1 núcleo de procesador | 1 GB de RAM | Tarjeta de red de 1 GbE | 20 GB |
Nuestro canal de Slack #nginx-agent es el lugar al que acudir para empezar a hacer preguntas y compartir sus pensamientos.
Nuestra página de problemas de GitHub ofrece espacio para una discusión más técnica a su propio ritmo.
¡Participa en el proyecto contribuyendo! Consulte nuestra guía de contribución para obtener más detalles.
Consulte nuestra página de lanzamiento para realizar un seguimiento de las actualizaciones.
Licencia Apache, Versión 2.0
