agent
v2.39.0
Агент NGINX — это сопутствующий демон для вашего экземпляра NGINX Open Source или NGINX Plus. Это позволяет:
Панель управления Grafana, показывающая метрики, сообщаемые агентом NGINX.
Агент NGINX работает как сопутствующий процесс в системе, на которой работает NGINX. Он предоставляет интерфейсы gRPC и REST для управления конфигурацией и сбора метрик из процесса и операционной системы NGINX. Агент NGINX обеспечивает удаленное взаимодействие с NGINX с помощью обычных инструментов Linux и открывает возможность создания сложных систем мониторинга и контроля, которые могут управлять большими коллекциями экземпляров NGINX.
Агент NGINX предоставляет интерфейс API для отправки обновленных файлов конфигурации. При получении нового файла он проверяет вывод nginx -V , чтобы определить расположение существующих конфигураций. Затем он проверяет новую конфигурацию с помощью nginx -t прежде чем применить ее через сигнал HUP к главному процессу NGINX.
Агент NGINX взаимодействует с информацией о процессах NGINX и анализирует журналы NGINX для расчета и составления отчетов о показателях. При взаимодействии с NGINX Plus агент NGINX получает соответствующую информацию из API NGINX Plus. Сообщаемые показатели могут быть агрегированы Prometheus и визуализированы с помощью таких инструментов, как Grafana.
Агент NGINX сохраняет соединение с API NGINX Plus открытым и выполняет запросы в зависимости от интервала сбора данных. Об этом соединении сообщается в метриках, и в зависимости от этапа отчетности это соединение может отображаться как бездействующее или активное.
При работе вместе с экземпляром NGINX с открытым исходным кодом агент NGINX требует, чтобы журналы доступа и ошибок NGINX были включены и содержали все переменные по умолчанию.
Чтобы агент NGINX правильно работал с экземпляром NGINX Plus, API необходимо настроить в файле nginx.conf этого экземпляра. Дополнительные сведения см. в разделе Обзор метрик экземпляра. Как только NGINX Plus настроен с конечной точкой /api/ , агент NGINX будет автоматически использовать ее при запуске.
Агент NGINX позволяет системе управления, подключенной к gRPC, зарегистрировать прослушиватель для определенного события. Механизм управления затем вызывается, когда агент NGINX отправляет связанный системный сигнал. Источником уведомления может быть либо экземпляр NGINX, либо сам агент NGINX. Вот список поддерживаемых в настоящее время событий:
| Событие | Описание |
|---|---|
| AGENT_START_MESSAGE | Процесс агента NGINX запущен. |
| AGENT_STOP_MESSAGE | Процесс агента NGINX остановлен |
| NGINX_FOUND_MESSAGE | В системе обнаружен главный процесс NGINX |
| NGINX_STOP_MESSAGE | Главный процесс NGINX остановлен |
| NGINX_RELOAD_SUCCESS_MESSAGE | Главный процесс NGINX успешно перезагружен |
| NGINX_RELOAD_FAILED_MESSAGE | Главный процесс NGINX не удалось перезагрузить |
| NGINX_WORKER_START_MESSAGE | Запущен новый рабочий процесс NGINX |
| NGINX_WORKER_STOP_MESSAGE | Рабочий процесс NGINX остановлен |
| CONFIG_APPLY_SUCCESS_MESSAGE | Успешно применена новая конфигурация NGINX. |
| CONFIG_APPLY_FAILURE_MESSAGE | Не удалось применить новую конфигурацию NGINX. |
| CONFIG_ROLLBACK_SUCCESS_MESSAGE | Конфигурация NGINX успешно откатана. |
| CONFIG_ROLLBACK_FAILURE_MESSAGE | Не удалось откатить конфигурацию NGINX. |
Агент NGINX напрямую взаимодействует с серверным процессом NGINX, установленным в той же системе. Если у вас его еще нет, выполните следующие действия, чтобы установить NGINX Open Source или NGINX Plus. После установки убедитесь, что экземпляр NGINX запущен.
Чтобы установить агент NGINX в вашей системе, перейдите в раздел «Релизы» и загрузите последний пакет, поддерживаемый вашим дистрибутивом ОС и архитектурой ЦП.
Используйте менеджер пакетов вашей системы, чтобы установить пакет. Несколько примеров:
Debian, Ubuntu и другие дистрибутивы используют менеджер пакетов dpkg .
sudo dpkg -i nginx-agent-<agent-version>.deb
RHEL, CentOS RHEL, Amazon Linux, Oracle Linux и другие дистрибутивы с использованием менеджера пакетов yum .
sudo yum localinstall nginx-agent-<agent-version>.rpm
RHEL и другие дистрибутивы, использующие менеджер пакетов rpm
sudo rpm -i nginx-agent-<agent-version>.rpm
Альпийский Линукс
sudo apk add nginx-agent-<agent-version>.apk
FreeBSD
sudo pkg add nginx-agent-<agent-version>.pkg
Чтобы запустить агент NGINX в системах systemd, выполните следующую команду:
sudo systemctl start nginx-agent
Чтобы разрешить запуск агента NGINX при загрузке, выполните следующую команду:
sudo systemctl enable nginx-agent
В Alpine Linux используйте следующую команду для запуска агента:
sudo service nginx-agent start
Чтобы разрешить запуск агента во время загрузки в Alpine Linux, запустите следующее:
sudo rc-update add nginx-agent default
Агент NGINX использует форматированные файлы журналов для сбора метрик. Расширение форматов журналов и количества экземпляров также приведет к увеличению размера файлов журналов агента NGINX. Мы рекомендуем добавить отдельный раздел для /var/log/nginx-agent . Без ротации журналов или их хранения в отдельном разделе файлы журналов могут занять все свободное пространство на диске и привести к тому, что ваша система перестанет отвечать на запросы определенных служб.
По умолчанию агент NGINX ежедневно меняет журналы с помощью logrotate со следующей конфигурацией:
/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
} Если вам нужно внести изменения в конфигурацию по умолчанию, вы можете обновить файл здесь /etc/logrotate.d/nginx-agent
Более подробную информацию о настройке logrotate см. в разделе Параметры конфигурации Logrotate.
Чтобы создать образ, содержащий последнюю версию агента NGINX, последнюю основную версию NGINX OSS на последней версии Alpine, выполните следующую команду:
make official-oss-imageЧтобы создать образ, содержащий последнюю версию агента NGINX, последнюю стабильную версию NGINX OSS на последней версии Alpine, выполните следующую команду:
make official-oss-stable-imageДополнительную информацию о том, как запускать контейнеры агента NGINX и как создавать образ, использующий NGINX Plus вместо NGINX OSS, см. в разделе «Образы Docker».
Выполните следующие действия, чтобы настроить и запустить агент NGINX и макет интерфейса («плоскость управления»), которому будет отправлять отчеты агент NGINX.
Следуйте инструкциям в разделе «Установка», чтобы загрузить, установить и запустить NGINX.
Используя предпочитаемый вами метод, клонируйте репозиторий агента NGINX в каталог разработки. Дополнительные сведения см. в разделе Клонирование репозитория GitHub.
Агент NGINX и Mock Control Plane написаны на Go. Для сборки и запуска любого приложения из каталога исходного кода требуется Go 1.23 или выше. Скачать Go можно с официального сайта.
Запустите фиктивную плоскость управления, выполнив следующую команду из корневого каталога исходного кода 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
Если он еще не существует, создайте каталог /etc/nginx-agent/ и скопируйте в него файл nginx-agent.conf из корневого каталога проекта.
sudo mkdir /etc/nginx-agent
sudo cp <project_root_directory>/nginx-agent.conf /etc/nginx-agent/
Создайте файл agent-dynamic.conf в каталоге /etc/nginx-agent/ , который необходим для запуска агента NGINX.
sudo touch /var/lib/nginx-agent/agent-dynamic.conf
Добавьте следующие настройки в /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 : trueДополнительные сведения см. в разделе «Определения протоколов агентов и документация».
Интерфейс REST агента NGINX можно открыть, проверив наличие следующих строк в файле /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 "Имитационная плоскость управления может использовать протоколы gRPC или REST для связи с агентом NGINX.
Для пользовательского интерфейса Swagger требуется установка goswagger. Дополнительные сведения см. в инструкциях по установке goswagger.
Чтобы запустить пользовательский интерфейс Swagger для интерфейса REST, выполните следующую команду
make launch-swagger-ui
Откройте веб-браузер, чтобы просмотреть пользовательский интерфейс Swagger по адресу http://localhost:8082/docs.
Расширение — это фрагмент кода, не критичный к основному функционалу, за который отвечает агент NGINX. Обычно это выходит за рамки управления конфигурацией NGINX и составления отчетов о показателях NGINX.
Чтобы включить расширение, его необходимо добавить в список расширений в файле /etc/nginx-agent/nginx-agent.conf . Вот пример включения расширения расширенных метрик:
extensions :
- advanced-metrics Если он уже запущен, перезапустите агент NGINX, чтобы применить новую конфигурацию. Альтернативно, если агент NGINX не запущен, вы можете запустить его из корневого каталога исходного кода.
Откройте другое окно терминала и запустите агент NGINX. Введите следующую команду из корневого каталога исходного кода 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
Откройте веб-браузер, чтобы просмотреть макет плоскости управления по адресу http://localhost:54790. В веб-интерфейсе будут показаны следующие ссылки:
Дополнительные варианты использования агента NGINX см. на странице https://github.com/nginx/agent/tree/main/sdk/examples.
Хотя большинство операционных систем Linux или FreeBSD можно использовать для участия в проекте агента NGINX, следующие шаги были разработаны для Ubuntu. Ubuntu поставляется с большинством библиотек, необходимых для сборки и запуска агента NGINX, и является рекомендуемой платформой для разработки агента NGINX.
Следуйте инструкциям в разделе «Установка», чтобы загрузить и установить NGINX. После установки убедитесь, что экземпляр NGINX запущен.
Следуйте инструкциям в разделе «Начало работы с агентом NGINX», чтобы клонировать репозиторий агента NGINX.
В зависимости от дистрибутива операционной системы для сборки агента NGINX может потребоваться установка следующих пакетов.
Перейдите в исходный каталог агента NGINX:
cd <path_to_development_directory>/agent
Установить марку:
sudo apt install make
Агент NGINX написан на Go. Вы можете скачать Go и следовать инструкциям по установке на той же странице или запустить:
sudo apt install golang-go
Установите протокол:
sudo apt install -y protobuf-compiler
Установите инструменты и зависимости агента NGINX:
Прежде чем начать разработку агента NGINX, важно загрузить и установить необходимый инструмент и зависимости, необходимые агенту NGINX. Вы можете сделать это, выполнив следующую команду make :
make install-tools
Выполните следующие команды для сборки и запуска агента NGINX:
make build
sudo make run
Агент NGINX может работать в большинстве сред. Список поддерживаемых дистрибутивов см. в руководстве по техническим характеристикам NGINX.
Агент NGINX можно развернуть в следующих средах:
Агент NGINX работает со всеми поддерживаемыми версиями NGINX Open Source и NGINX Plus.
Рекомендации по минимальной настройке системы для агента NGINX:
| Процессор | Память | Сеть | Хранилище |
|---|---|---|---|
| 1 ядро процессора | 1 ГБ ОЗУ | сетевая карта 1 Гбит/с | 20 ГБ |
Наш канал Slack #nginx-agent — это идеальное место, где можно задавать вопросы и делиться своими мыслями.
Наша страница проблем на GitHub предлагает место для более технических обсуждений в удобном для вас темпе.
Примите участие в проекте, внося свой вклад! Подробности смотрите в нашем руководстве по участию.
Посетите нашу страницу релизов, чтобы следить за обновлениями.
Лицензия Apache, версия 2.0
