NGINX Plus の設定

NGINX Plusをインストールしたホストに対し、NGINX Agentをインストールし動作を確認します。 UDF環境で動作する場合、 ubuntu03 (10.1.1.5) で操作することを想定しています

ドキュメントは以下のページの内容を参照しています

0. (事前準備) NGINX Plusのインストール

1. NGINX Plusのインストール・基礎

以下のページの内容を参考にNGINX Plus及びモジュールをインストールします

NGINX Plus Lab 1. NGINX Plusのインストール (15min)

また、このラボは以下の内容を理解していることを前提としています。

初めてNGINX Plusを操作する方は、以下より基本的な挙動について確認をしてください。

NGINX Plus Lab 3. 基本的な動作の確認を参照してください

2. 必要なファイルの取得

NGINX Agent の動作や初期設定で参照するGitHubのレポジトリを取得します

sudo su -
git clone https://github.com/nginx/agent.git

git clone https://github.com/BeF5/f5j-nginx-agent-lab.git

3. Goのインストール

NGINX Agent及びMockアプリケーションはGoを利用します。以下ページよりGoをインストールしてください。このラボでインストールする NGINX Agent v2.23.1 は Go 1.19以上 が必要となります

インストール手順はGoのマニュアルを参照しています

Note

こちらの手順は Go 1.20.1 のインストール手順となります

以下手順を参考にインストールします

sudo su -
# ファイルの取得
wget https://go.dev/dl/go1.20.1.linux-amd64.tar.gz

# ファイルの展開
rm -rf /usr/local/go && tar -C /usr/local -xzf go1.20.1.linux-amd64.tar.gz

# PATHの設定
export PATH=$PATH:/usr/local/go/bin

インストールしたバージョンを確認します

go version

実行結果サンプル

go version go1.20.1 linux/amd64

4. makeのインストール

一部手順で make を利用します。必要に応じてインストールしてください

sudo apt install make

インストールしたバージョンを確認します

make -v

実行結果サンプル

GNU Make 4.2.1
Built for x86_64-pc-linux-gnu
Copyright (C) 1988-2016 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

5. jq のインストール

sudo apt install jq

1. NGINX Agent のインストール

NGINX Agentをインストールする環境のOS/CPUに応じたパッケージを取得します

GitHub nginx / agent Release

1. OS/CPUの確認

cat /etc/os-release

実行結果サンプル

NAME="Ubuntu"
VERSION="20.04.2 LTS (Focal Fossa)"
ID=ubuntu
ID_LIKE=debian
PRETTY_NAME="Ubuntu 20.04.2 LTS"
VERSION_ID="20.04"
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
VERSION_CODENAME=focal
UBUNTU_CODENAME=focal

uname -m

実行結果サンプル

x86_64

この例では OS Version focal CPU amd64 に対応したNGINX Agent v2.23.1 をダウンロードします。

wget https://github.com/nginx/agent/releases/download/v2.23.1/nginx-agent-2.23.1.focal_amd64.deb

2. NGINX Agentのインストール

sudo dpkg -i nginx-agent-2.23.1.focal_amd64.deb

実行結果サンプル

Selecting previously unselected package nginx-agent.
(Reading database ... 148909 files and directories currently installed.)
Preparing to unpack nginx-agent-2.23.1.focal_amd64.deb ...

 --- NGINX Agent Package Installer ---

 --- Will install the NGINX Agent in 5 seconds ---
Sudo permissions detected
Could not find /etc/nginx-agent/agent-dynamic.conf ... Creating file
Successfully created /etc/nginx-agent/agent-dynamic.conf
Updating /etc/nginx-agent/agent-dynamic.conf ...
Agent config file /etc/nginx-agent/nginx-agent.conf does not exist. Could not be updated
Unpacking nginx-agent (2.23.1~focal) ...
Setting up nginx-agent (2.23.1~focal) ...
PostInstall: Reading NGINX systemctl unit file for user information
NGINX processes running as user 'root'. nginx-agent will be configured to run as same user
PostInstall: Reading NGINX process information to determine NGINX user
NGINX processes running as user 'nginx'. nginx-agent will try add that user to 'nginx-agent'
Sudo permissions detected
Found nginx-agent /usr/bin/nginx-agent
PostInstall: Adding nginx-agent group nginx-agent
PostInstall: Adding NGINX / agent user root to group nginx-agent
PostInstall: Adding NGINX Worker user nginx to group nginx-agent
PostInstall: Creating NGINX Agent run directory
PostInstall: Modifying group ownership of NGINX Agent run directory
PostInstall: Modifying NGINX Agent unit file with correct locations and user information
PostInstall: Reload the service unit from disk
PostInstall: Unmask the service unit from disk
PostInstall: Set the preset flag for the service unit
Created symlink /etc/systemd/system/multi-user.target.wants/nginx-agent.service → /etc/systemd/system/nginx-agent.service.
PostInstall: Set the enabled flag for the service unit
----------------------------------------------------------------------
 NGINX Agent package has been successfully installed.

 Please follow the next steps to start the software:
    sudo systemctl start nginx-agent

 Configuration settings can be adjusted here:
    /etc/nginx-agent/nginx-agent.conf

----------------------------------------------------------------------

正しくインストールしたことを確認します

dpkg -l | grep nginx-agent

実行結果サンプル

ii  nginx-agent                        2.23.1~focal                          amd64        NGINX Agent

3. NGINX Agent の起動・自動起動を有効にする

NGINX Agentを起動、自動起動を有効にします

sudo systemctl start nginx-agent
sudo systemctl enable nginx-agent

正しく起動したことを確認します

ps -ef | grep nginx-agent

実行結果サンプル

root        2027       1 99 14:25 ?        00:00:08 /usr/bin/nginx-agent

sudo systemctl status nginx-agent

実行結果サンプル

● nginx-agent.service - NGINX Agent
     Loaded: loaded (/etc/systemd/system/nginx-agent.service; enabled; vendor preset: enabled)
     Active: active (running) since Fri 2023-03-03 15:32:49 JST; 5s ago
       Docs: https://github.com/nginx/agent#readme
    Process: 5375 ExecStartPre=/bin/mkdir -p /var/run/nginx-agent (code=exited, status=0/SUCCESS)
    Process: 5376 ExecStartPre=/bin/mkdir -p /var/log/nginx-agent (code=exited, status=0/SUCCESS)
   Main PID: 5377 (nginx-agent)
      Tasks: 5 (limit: 2327)
     Memory: 4.0M
     CGroup: /system.slice/nginx-agent.service
             └─5377 /usr/bin/nginx-agent

Mar 03 15:32:49 ip-10-1-1-7 systemd[1]: Starting NGINX Agent...
Mar 03 15:32:49 ip-10-1-1-7 systemd[1]: Started NGINX Agent.
Mar 03 15:32:49 ip-10-1-1-7 nginx-agent[5377]: time="2023-03-03T15:32:49+09:00" level=warning msg="Log level is info"
Mar 03 15:32:49 ip-10-1-1-7 nginx-agent[5377]: time="2023-03-03T15:32:49+09:00" level=info msg="setting displayName to ip-10-1-1-7"
Mar 03 15:32:49 ip-10-1-1-7 nginx-agent[5377]: time="2023-03-03T15:32:49+09:00" level=info msg="NGINX Agent v2.23.1 at 8fa9a62e wi>
Mar 03 15:32:49 ip-10-1-1-7 nginx-agent[5377]: time="2023-03-03T15:32:49+09:00" level=error msg="Unable to create command channel:>
Mar 03 15:32:49 ip-10-1-1-7 nginx-agent[5377]: time="2023-03-03T15:32:49+09:00" level=info msg="Commander retrying to connect to 1>

NGINX Agentのログは以下に出力されます

ls /var/log/nginx-agent/

実行結果サンプル

agent.log

2. NGINX Agent 設定ファイルの確認

NGINX Agent の設定ファイルに必要な内容を追加します。

# フォルダが存在しない場合
# sudo mkdir /etc/nginx-agent
sudo cp /etc/nginx-agent/nginx-agent.conf /etc/nginx-agent/nginx-agent.conf-
sudo touch /etc/nginx-agent/agent-dynamic.conf

sudo cp ~/f5j-nginx-agent-lab/config/nginx-agent.conf /etc/nginx-agent/

外部からの接続を受けるため、以下のような設定となります

tail -13 /etc/nginx-agent/nginx-agent.conf

実行結果サンプル

api:
  # default port for Agent API, this is for the server configuration of the REST API
  port: 8081

server:
  # host of the control plane
  host: 127.0.0.1
  grpcPort: 54789
# tls options - NOT RECOMMENDED FOR PRODUCTION
tls:
  enable: false
  skip_verify: true

これらの設定が完了することでNGINX Agentはステータスを以下ポートでの処理が可能な状態となります

gRPC Port	54789
REST Port	8081

設定を反映します

sudo systemctl restart nginx-agent

3. Swagger のインストール

1. インストール

NGINX Agent及びMockアプリケーションはGoを利用します。以下ページよりGoをインストールしてください。このラボでインストールする NGINX Agent v2.23.1 は Go 1.19以上 が必要となります

インストール手順はGoのマニュアルを参照しています

Swagger Installs

Note

こちらの手順は Go 1.20.1 のインストール手順となります

以下手順を参考にインストールします

download_url=$(curl -s https://api.github.com/repos/go-swagger/go-swagger/releases/latest | \
  jq -r '.assets[] | select(.name | contains("'"$(uname | tr '[:upper:]' '[:lower:]')"'_amd64")) | .browser_download_url')
sudo curl -o /usr/local/bin/swagger -L'#' "$download_url"
sudo chmod +x /usr/local/bin/swagger

Swagger UIの実行

cd ~/agent/
make launch-swagger-ui
# 2回目以降は make launch-swagger-ui & によりバックグラウンドでSwaggerUIを実行できます

実行結果サンプル

** 省略 **
go run github.com/go-swagger/go-swagger/cmd/swagger serve ./docs/swagger.json -F=swagger --port=8082 --no-open
2023/03/03 17:09:42 serving docs at http://localhost:8082/docs

踏み台ホストでChromeを起動し、 http://10.1.1.5:8082/docs に接続してください

2. curl を使った Statusの確認

NGINX Agent が 8081 で待ち受けるREST APIに対してステータスの確認が出来ます。参考情報は Tips1. curl によるNGINX Agent RESTの結果を参照してください。

4. Grafana / Prometheus のインストール

NGINX Agent が提供する Metrics 情報を表示するためGrafanaを実行します

cd ~/f5j-nginx-agent-lab/docker-compose
docker-compose -f docker-compose.yml up -d

正しくコンテナが起動すると、以下ポートでサービスが起動します

Grafana	3000
Prometheus	9090

踏み台ホストでChromeを起動し、 Prometheus http://10.1.1.5:9090 に接続してください。正しく起動している場合、以下のような画面が表示されます

../../_images/nginx-agent-prometheus-top.png

踏み台ホストでChromeを起動し、 Grafana http://10.1.1.5:3000 に接続してください。正しく起動している場合、以下のような画面が表示されます

../../_images/nginx-agent-grafana-top.png

以下の情報でログインします。初回時にパスワードを変更するよう促されますので適宜パスワードを指定してください

Top画面の下部に表示された NGINX Agent のダッシュボードをクリックするとステータスが取得できます。 (すべての項目が表示されるまで5分ほど必要となります)

../../_images/nginx-agent-grafana-dashboard.png

5. モックアプリケーションの起動

1. インストール

こちらのモックアプリケーションはGoを利用します。 Goのインストールの手順を参考にGoのインストールを行ってください

モックアプリケーションを実行します

cd ~/agent/
go run sdk/examples/server.go
# 初回は必要なファイルのダウンロードなどプログラムの実行に約1分かかります
# 2回目以降は go run sdk/examples/server.go & によりバックグラウンドでモックアップアプリケーションを実行できます

実行結果サンプル

** 省略 **
INFO[0000] http listening
INFO[0000] gRPC listening

踏み台ホストでChromeを起動し、 http://10.1.1.5:54790 に接続してください

提供されている情報は以下となります

registered - マネージメントプレーンとして動作するモックアップに登録されているデータプレーンの情報を表示
nginxes - データプレーンのNGINXインスタンス情報のリスト表示
configs - マネージメントプレーンに送付されたProtobufペイロードのNGINX設定を表示
configs/chunked - マネージメントプレーンに送付された分割されたペイロードを表示
configs/raw - データプレーンに設定されている実際のNGINX設定を表示
metrics - マネージメントプレーンに送付されたメトリクスの情報を表示（REST APIで送付されるものと同じ)

2. curl を使った Statusの確認

モックアップアプリケーションがNGINX Agentの 54790 にgRPCで接続し、取得した情報の確認が出来ます。参考情報は Tips2. curlによるモックアプリケーションの結果を参照してください。