agent
v2.39.0
O Agente NGINX é um daemon complementar para sua instância NGINX Open Source ou NGINX Plus. Ele permite:
Painel Grafana mostrando métricas relatadas pelo agente NGINX
O Agente NGINX é executado como um processo complementar em um sistema que executa o NGINX. Ele fornece interfaces gRPC e REST para gerenciamento de configuração e coleta de métricas do processo e sistema operacional NGINX. O Agente NGINX permite a interação remota com o NGINX usando ferramentas Linux comuns e desbloqueia a capacidade de construir sistemas sofisticados de monitoramento e controle que podem gerenciar grandes coleções de instâncias NGINX.
O Agente NGINX fornece uma interface API para envio de arquivos de configuração atualizados. Ao receber um novo arquivo, ele verifica a saída do nginx -V para determinar a localização das configurações existentes. Em seguida, ele valida a nova configuração com nginx -t antes de aplicá-la por meio de um sinal HUP ao processo mestre NGINX.
O Agente NGINX faz interface com as informações do processo NGINX e analisa os logs do NGINX para calcular e relatar métricas. Ao fazer interface com o NGINX Plus, o Agente NGINX extrai informações relevantes da API NGINX Plus. As métricas relatadas podem ser agregadas pelo Prometheus e visualizadas com ferramentas como o Grafana.
O Agente NGINX mantém uma conexão aberta com a API NGINX Plus e consultas com base no intervalo de coleta. Esta conexão é reportada nas métricas e dependendo da fase de reporte esta conexão pode aparecer como inativa ou ativa.
Ao executar junto com uma instância de código aberto do NGINX, o Agente NGINX exige que os logs de acesso e erros do NGINX estejam ativados e contenham todas as variáveis padrão.
Para que o Agente NGINX funcione corretamente com uma instância NGINX Plus, a API precisa ser configurada no nginx.conf dessa instância. Consulte Visão geral das métricas da instância para obter mais detalhes. Depois que o NGINX Plus estiver configurado com o endpoint /api/ , o Agente NGINX o usará automaticamente na inicialização.
O Agente NGINX permite que um sistema de controle conectado ao gRPC registre um ouvinte para um evento específico. O mecanismo de controle é então invocado quando o Agente NGINX envia um sinal de sistema associado. A origem de uma notificação pode ser a instância NGINX ou o próprio Agente NGINX. Aqui está uma lista de eventos atualmente suportados:
| Evento | Descrição |
|---|---|
| AGENT_START_MESSAGE | Processo do agente NGINX iniciado |
| AGENT_STOP_MESSAGE | Processo do agente NGINX interrompido |
| NGINX_FOUND_MESSAGE | Processo mestre NGINX detectado no sistema |
| NGINX_STOP_MESSAGE | Processo mestre NGINX interrompido |
| NGINX_RELOAD_SUCCESS_MESSAGE | Processo mestre NGINX recarregado com sucesso |
| NGINX_RELOAD_FAILED_MESSAGE | O processo mestre NGINX falhou ao recarregar |
| NGINX_WORKER_START_MESSAGE | Novo processo de trabalho NGINX iniciado |
| NGINX_WORKER_STOP_MESSAGE | Processo de trabalho NGINX interrompido |
| CONFIG_APPLY_SUCCESS_MESSAGE | Nova configuração NGINX aplicada com sucesso |
| CONFIG_APPLY_FAILURE_MESSAGE | Falha ao aplicar a nova configuração do NGINX |
| CONFIG_ROLLBACK_SUCCESS_MESSAGE | Configuração NGINX revertida com sucesso |
| CONFIG_ROLLBACK_FAILURE_MESSAGE | Falha ao reverter a configuração do NGINX |
O Agente NGINX faz interface diretamente com um processo do servidor NGINX instalado no mesmo sistema. Se ainda não o fez, siga estas etapas para instalar o NGINX Open Source ou o NGINX Plus. Depois de instalado, certifique-se de que a instância NGINX esteja em execução.
Para instalar o Agente NGINX em seu sistema, acesse Versões e baixe o pacote mais recente compatível com sua distribuição de sistema operacional e arquitetura de CPU.
Use o gerenciador de pacotes do seu sistema para instalar o pacote. Alguns exemplos:
Debian, Ubuntu e outras distribuições usando o gerenciador de pacotes dpkg .
sudo dpkg -i nginx-agent-<agent-version>.deb
RHEL, CentOS RHEL, Amazon Linux, Oracle Linux e outras distribuições usando o gerenciador de pacotes yum
sudo yum localinstall nginx-agent-<agent-version>.rpm
RHEL e outras distribuições usando o gerenciador de pacotes rpm
sudo rpm -i nginx-agent-<agent-version>.rpm
Alpino Linux
sudo apk add nginx-agent-<agent-version>.apk
FreeBSD
sudo pkg add nginx-agent-<agent-version>.pkg
Para iniciar o Agente NGINX em sistemas systemd, execute o seguinte comando:
sudo systemctl start nginx-agent
Para permitir que o agente NGINX seja iniciado na inicialização, execute o seguinte comando:
sudo systemctl enable nginx-agent
No Alpine Linux, use o seguinte comando para iniciar o agente:
sudo service nginx-agent start
Para permitir que o agente seja iniciado no momento da inicialização no Alpine Linux, execute isto:
sudo rc-update add nginx-agent default
O Agente NGINX usa arquivos de log formatados para coletar métricas. A expansão dos formatos de log e das contagens de instâncias também aumentará o tamanho dos arquivos de log do Agente NGINX. Recomendamos adicionar uma partição separada para /var/log/nginx-agent . Sem rotação de log ou armazenamento em uma partição separada, os arquivos de log podem usar todo o espaço livre na unidade e fazer com que o sistema pare de responder a determinados serviços.
Por padrão, o Agente NGINX alterna os logs diariamente usando logrotate com a seguinte configuração:
/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
} Se precisar fazer alterações na configuração padrão, você pode atualizar o arquivo aqui /etc/logrotate.d/nginx-agent
Para obter mais detalhes sobre a configuração do logrotate, consulte Opções de configuração do logrotate
Para construir uma imagem que contenha o agente NGINX mais recente, a versão principal mais recente do NGINX OSS no Alpine mais recente, execute o seguinte comando:
make official-oss-imagePara construir uma imagem que contenha o agente NGINX mais recente, a versão estável mais recente do NGINX OSS no Alpine mais recente, execute o seguinte comando:
make official-oss-stable-imagePara obter mais informações sobre como executar contêineres do agente NGINX e como construir uma imagem que use o NGINX Plus em vez do NGINX OSS, consulte Docker Images
Siga estas etapas para configurar e executar o Agente NGINX e uma interface simulada ("plano de controle") à qual o Agente NGINX se reportará.
Siga as etapas na seção Instalação para baixar, instalar e executar o NGINX.
Usando seu método preferido, clone o repositório do Agente NGINX em seu diretório de desenvolvimento. Consulte Clonando um repositório GitHub para obter ajuda adicional.
O Agente NGINX e o Plano de Controle Simulado são escritos em Go. É necessária a versão 1.23 ou superior para criar e executar qualquer aplicativo a partir do diretório do código-fonte. Você pode baixar o Go no site oficial.
Inicie o plano de controle simulado executando o seguinte comando no diretório raiz do código-fonte 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
Se ainda não existir, crie o diretório /etc/nginx-agent/ e copie o arquivo nginx-agent.conf do diretório raiz do projeto.
sudo mkdir /etc/nginx-agent
sudo cp <project_root_directory>/nginx-agent.conf /etc/nginx-agent/
Crie o arquivo agent-dynamic.conf no diretório /etc/nginx-agent/ , que é necessário para a execução do Agente NGINX.
sudo touch /var/lib/nginx-agent/agent-dynamic.conf
Adicione as seguintes configurações 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 obter mais informações, consulte Definições e documentação do protocolo do agente
A interface REST do agente NGINX pode ser exposta validando as seguintes linhas no arquivo /etc/nginx-agent/nginx-agent.conf estão 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 "O plano de controle simulado pode usar protocolos gRPC ou REST para se comunicar com o Agente NGINX.
A UI do Swagger requer que o goswagger esteja instalado. Consulte as instruções para instalar o goswagger para obter ajuda adicional.
Para iniciar a UI do Swagger para a interface REST, execute o seguinte comando
make launch-swagger-ui
Abra um navegador da web para visualizar a UI do Swagger em http://localhost:8082/docs.
Uma extensão é um trecho de código que não é crítico para a funcionalidade principal pela qual o agente NGINX é responsável. Isso geralmente está fora da responsabilidade de gerenciar a configuração do NGINX e relatar métricas do NGINX.
Para habilitar uma extensão, ela deve ser adicionada à lista de extensões em /etc/nginx-agent/nginx-agent.conf . Aqui está um exemplo de ativação da extensão de métricas avançadas:
extensions :
- advanced-metrics Se já estiver em execução, reinicie o Agente NGINX para aplicar a nova configuração. Como alternativa, se o Agente NGINX não estiver em execução, você poderá executá-lo no diretório raiz do código-fonte.
Abra outra janela de terminal e inicie o Agente NGINX. Emita o comando a seguir no diretório raiz do código-fonte 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 um navegador da web para visualizar o plano de controle simulado em http://localhost:54790. Os seguintes links serão mostrados na interface da web:
Para mais casos de uso do Agente NGINX, consulte https://github.com/nginx/agent/tree/main/sdk/examples
Embora a maioria dos sistemas operacionais Linux ou FreeBSD possam ser usados para contribuir com o projeto do Agente NGINX, as etapas a seguir foram projetadas para Ubuntu. O Ubuntu vem com a maioria das bibliotecas necessárias para construir e executar o Agente NGINX e é a plataforma recomendada para o desenvolvimento do Agente NGINX.
Siga as etapas na seção Instalação para baixar e instalar o NGINX. Depois de instalado, certifique-se de que a instância NGINX esteja em execução.
Siga as etapas na seção Introdução ao agente NGINX para clonar o repositório do agente NGINX
Dependendo da distribuição do sistema operacional, pode ser necessário instalar os pacotes a seguir para construir o Agente NGINX.
Mude para o diretório de origem do Agente NGINX:
cd <path_to_development_directory>/agent
Instale o Make:
sudo apt install make
O Agente NGINX está escrito em Go. Você pode baixar Go e seguir as instruções de instalação na mesma página ou executar:
sudo apt install golang-go
Instale o Protocolo:
sudo apt install -y protobuf-compiler
Instale as ferramentas e dependências do agente NGINX:
Antes de iniciar o desenvolvimento no Agente NGINX, é importante baixar e instalar a ferramenta e as dependências necessárias exigidas pelo Agente NGINX. Você pode fazer isso executando o seguinte comando make :
make install-tools
Execute os seguintes comandos para criar e executar o Agente NGINX:
make build
sudo make run
O Agente NGINX pode ser executado na maioria dos ambientes. Para obter uma lista de distribuições suportadas, consulte o guia de especificações técnicas do NGINX.
O Agente NGINX pode ser implantado nos seguintes ambientes:
O Agente NGINX funciona com todas as versões suportadas do NGINX Open Source e NGINX Plus.
Recomendações mínimas de dimensionamento do sistema para o Agente NGINX:
| CPU | Memória | Rede | Armazenar |
|---|---|---|---|
| 1 núcleo de CPU | 1 GB de RAM | Placa de rede de 1 GbE | 20GB |
Nosso canal Slack #nginx-agent é o lugar certo para começar a fazer perguntas e compartilhar suas ideias.
Nossa página de problemas do GitHub oferece espaço para uma discussão mais técnica no seu próprio ritmo.
Envolva-se com o projeto contribuindo! Consulte nosso guia de contribuição para obter detalhes.
Consulte nossa página de lançamento para acompanhar as atualizações.
Licença Apache, versão 2.0
