agent
v2.39.0
NGINX Agent は、NGINX オープン ソースまたは NGINX Plus インスタンスのコンパニオン デーモンです。これにより以下が可能になります。
NGINX エージェントによって報告されたメトリクスを表示する Grafana ダッシュボード
NGINX エージェントは、NGINX を実行しているシステム上でコンパニオン プロセスとして実行されます。 NGINX プロセスとオペレーティング システムからの構成管理とメトリクス収集のための gRPC および REST インターフェイスを提供します。 NGINX Agent は、一般的な Linux ツールを使用して NGINX とのリモート対話を可能にし、NGINX インスタンスの大規模なコレクションを管理できる高度な監視および制御システムを構築する機能を解放します。
NGINX エージェントは、更新された構成ファイルを送信するための API インターフェイスを提供します。新しいファイルを受信すると、 nginx -Vの出力をチェックして、既存の構成の場所を特定します。次に、シグナル HUP 経由で NGINX マスター プロセスに適用する前に、 nginx -tで新しい設定を検証します。
NGINX エージェントは、NGINX プロセス情報と連携し、NGINX ログを解析してメトリクスを計算して報告します。 NGINX Plus と接続する場合、NGINX Agent は NGINX Plus API から関連情報を取得します。報告されたメトリクスは Prometheus によって集約され、Grafana などのツールで視覚化される場合があります。
NGINX エージェントは、NGINX Plus API への接続を開いたままにし、収集間隔に基づいてクエリを実行します。この接続はメトリクスでレポートされ、レポートのフェーズに応じて、この接続はアイドルまたはアクティブとして表示されます。
NGINX のオープンソース インスタンスと一緒に実行する場合、NGINX エージェントは、NGINX アクセス ログとエラー ログがオンになっていて、すべてのデフォルト変数が含まれている必要があります。
NGINX エージェントが NGINX Plus インスタンスで適切に動作するには、そのインスタンスの nginx.conf で API を構成する必要があります。詳細については、「インスタンス メトリックの概要」を参照してください。 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 オープンソースまたは NGINX Plus をインストールします。インストールしたら、NGINX インスタンスが実行されていることを確認します。
システムに NGINX エージェントをインストールするには、「リリース」に移動し、OS ディストリビューションと CPU アーキテクチャでサポートされている最新のパッケージをダウンロードします。
システムのパッケージ マネージャーを使用してパッケージをインストールします。いくつかの例:
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
rpmパッケージ マネージャーを使用する RHEL およびその他のディストリビューション
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
systemd システムで NGINX エージェントを起動するには、次のコマンドを実行します。
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 エージェント、最新の Alpine 上の NGINX OSS の最新メインライン バージョンを含むイメージを構築するには、次のコマンドを実行します。
make official-oss-image最新の NGINX エージェント、最新の Alpine 上の NGINX OSS の最新の安定バージョンを含むイメージを構築するには、次のコマンドを実行します。
make official-oss-stable-imageNGINX Agent コンテナを実行する方法と、NGINX OSS の代わりに NGINX Plus を使用するイメージを構築する方法の詳細については、「Docker イメージ」を参照してください。
NGINX エージェントと、NGINX エージェントのレポート先となるモック インターフェイス (「コントロール プレーン」) を構成して実行するには、次の手順に従います。
「インストール」セクションの手順に従って、NGINX をダウンロード、インストール、実行します。
好みの方法を使用して、NGINX エージェント リポジトリのクローンを開発ディレクトリに作成します。詳細については、「GitHub リポジトリのクローン作成」を参照してください。
NGINX エージェントとモック コントロール プレーンは Go で書かれています。ソース コード ディレクトリからいずれかのアプリケーションをビルドして実行するには、Go 1.23 以降が必要です。 Goは公式Webサイトからダウンロードできます。
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/
/etc/nginx-agent/ディレクトリにagent-dynamic.confファイルを作成します。これは 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詳細については、「エージェント プロトコルの定義とドキュメント」を参照してください。
NGINX エージェント REST インターフェイスは、 /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 UI を使用するには、goswagger がインストールされている必要があります。さらに詳しいヘルプについては、goswagger のインストール手順を参照してください。
REST インターフェイスの Swagger UI を起動するには、次のコマンドを実行します。
make launch-swagger-ui
Web ブラウザを開いて、http://localhost:8082/docs にある Swagger UI を表示します。
拡張機能はコードの一部であり、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
Web ブラウザを開いて、http://localhost:54790 にある模擬コントロール プレーンを表示します。次のリンクが Web インターフェイスに表示されます。
NGINX エージェントのその他の使用例については、https://github.com/nginx/agent/tree/main/sdk/examples を参照してください。
ほとんどの Linux または FreeBSD オペレーティング システムは NGINX Agent プロジェクトに貢献するために使用できますが、次の手順は Ubuntu 向けに設計されています。 Ubuntu には、NGINX Agent の構築と実行に必要なほとんどのライブラリがパッケージ化されており、NGINX Agent 開発に推奨されるプラットフォームです。
「インストール」セクションの手順に従って、NGINX をダウンロードしてインストールします。インストールしたら、NGINX インスタンスが実行されていることを確認します。
「NGINX Agent の開始」セクションの手順に従って、NGINX Agent リポジトリのクローンを作成します。
オペレーティング システムのディストリビューションによっては、NGINX エージェントを構築するために次のパッケージをインストールする必要がある場合があります。
NGINX エージェントのソース ディレクトリに移動します。
cd <path_to_development_directory>/agent
Make をインストールします。
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 Agent は、サポートされているすべてのバージョンの NGINX Open Source および NGINX Plus で動作します。
NGINX エージェントの最小システム サイズ推奨事項:
| CPU | メモリ | ネットワーク | ストレージ |
|---|---|---|---|
| 1 CPUコア | 1GBのRAM | 1GbE NIC | 20GB |
Slack チャンネル #nginx-agent は、質問したり、意見を共有したりするのに最適な場所です。
GitHub の問題ページでは、自分のペースでより技術的な議論ができるスペースを提供しています。
貢献してプロジェクトに参加しましょう!詳細については、貢献ガイドをご覧ください。
更新情報を追跡するには、リリース ページを参照してください。
Apache ライセンス、バージョン 2.0
