agent
v2.39.0
Agen NGINX adalah daemon pendamping untuk instans NGINX Open Source atau NGINX Plus Anda. Ini memungkinkan:
Dasbor Grafana menampilkan metrik yang dilaporkan oleh Agen NGINX
Agen NGINX dijalankan sebagai proses pendamping pada sistem yang menjalankan NGINX. Ini menyediakan antarmuka gRPC dan REST untuk manajemen konfigurasi dan pengumpulan metrik dari proses dan sistem operasi NGINX. Agen NGINX memungkinkan interaksi jarak jauh dengan NGINX menggunakan alat umum Linux dan membuka kemampuan untuk membangun sistem pemantauan dan kontrol canggih yang dapat mengelola koleksi besar instans NGINX.
Agen NGINX menyediakan antarmuka API untuk pengiriman file konfigurasi yang diperbarui. Setelah menerima file baru, ia memeriksa output nginx -V untuk menentukan lokasi konfigurasi yang ada. Kemudian memvalidasi konfigurasi baru dengan nginx -t sebelum menerapkannya melalui sinyal HUP ke proses master NGINX.
Agen NGINX berinteraksi dengan informasi proses NGINX dan mengurai log NGINX untuk menghitung dan melaporkan metrik. Saat berinteraksi dengan NGINX Plus, Agen NGINX mengambil informasi yang relevan dari NGINX Plus API. Metrik yang dilaporkan dapat dikumpulkan oleh Prometheus dan divisualisasikan dengan alat seperti Grafana.
Agen NGINX menjaga koneksi tetap terbuka ke API NGINX Plus dan kueri berdasarkan interval pengumpulan. Koneksi ini dilaporkan dalam metrik dan bergantung pada fase pelaporan, koneksi ini dapat muncul sebagai tidak aktif atau aktif.
Saat dijalankan bersama instance sumber terbuka NGINX, Agen NGINX mengharuskan NGINX Access dan Error logs diaktifkan dan berisi semua variabel default.
Agar Agen NGINX dapat bekerja dengan baik dengan instans NGINX Plus, API perlu dikonfigurasi di nginx.conf instans tersebut. Lihat Ikhtisar Metrik Instance untuk detail selengkapnya. Setelah NGINX Plus dikonfigurasi dengan endpoint /api/ , Agen NGINX akan secara otomatis menggunakannya saat startup.
Agen NGINX memungkinkan sistem kontrol yang terhubung dengan gRPC mendaftarkan pendengar untuk peristiwa tertentu. Mekanisme kontrol kemudian dipanggil ketika Agen NGINX mengirimkan sinyal sistem terkait. Sumber notifikasi dapat berupa instans NGINX atau Agen NGINX itu sendiri. Berikut daftar acara yang didukung saat ini:
| Peristiwa | Keterangan |
|---|---|
| AGENT_START_MESSAGE | Proses Agen NGINX dimulai |
| AGENT_STOP_MESSAGE | Proses Agen NGINX terhenti |
| NGINX_FOUND_MESSAGE | Proses master NGINX terdeteksi pada sistem |
| NGINX_STOP_MESSAGE | Proses master NGINX terhenti |
| NGINX_RELOAD_SUCCESS_MESSAGE | Proses master NGINX berhasil dimuat ulang |
| NGINX_RELOAD_FAILED_MESSAGE | Proses master NGINX gagal dimuat ulang |
| NGINX_WORKER_START_MESSAGE | Proses pekerja NGINX baru dimulai |
| NGINX_WORKER_STOP_MESSAGE | Proses pekerja NGINX terhenti |
| CONFIG_APPLY_SUCCESS_MESSAGE | Berhasil menerapkan konfigurasi NGINX baru |
| CONFIG_APPLY_FAILURE_MESSAGE | Gagal menerapkan konfigurasi NGINX baru |
| CONFIG_ROLLBACK_SUCCESS_MESSAGE | Berhasil mengembalikan konfigurasi NGINX |
| CONFIG_ROLLBACK_FAILURE_MESSAGE | Gagal mengembalikan konfigurasi NGINX |
Agen NGINX berinteraksi langsung dengan proses server NGINX yang diinstal pada sistem yang sama. Jika Anda belum memilikinya, ikuti langkah-langkah berikut untuk menginstal NGINX Open Source atau NGINX Plus. Setelah terinstal, pastikan instance NGINX berjalan.
Untuk menginstal Agen NGINX di sistem Anda, buka Rilis dan unduh paket terbaru yang didukung oleh distribusi OS dan arsitektur CPU Anda.
Gunakan manajer paket sistem Anda untuk menginstal paket. Beberapa contoh:
Debian, Ubuntu, dan distribusi lainnya menggunakan pengelola paket dpkg .
sudo dpkg -i nginx-agent-<agent-version>.deb
RHEL, CentOS RHEL, Amazon Linux, Oracle Linux, dan distribusi lainnya menggunakan manajer paket yum
sudo yum localinstall nginx-agent-<agent-version>.rpm
RHEL dan distribusi lainnya menggunakan manajer paket rpm
sudo rpm -i nginx-agent-<agent-version>.rpm
Linux Alpen
sudo apk add nginx-agent-<agent-version>.apk
FreeBSD
sudo pkg add nginx-agent-<agent-version>.pkg
Untuk memulai Agen NGINX pada sistem systemd, jalankan perintah berikut:
sudo systemctl start nginx-agent
Untuk mengaktifkan Agen NGINX untuk memulai saat boot, jalankan perintah berikut:
sudo systemctl enable nginx-agent
Di Alpine Linux, gunakan perintah berikut untuk memulai agen:
sudo service nginx-agent start
Untuk mengaktifkan agen untuk memulai saat boot di Alpine Linux, jalankan ini:
sudo rc-update add nginx-agent default
Agen NGINX menggunakan file log yang diformat untuk mengumpulkan metrik. Memperluas format log dan jumlah instans juga akan meningkatkan ukuran file log Agen NGINX. Kami menyarankan untuk menambahkan partisi terpisah untuk /var/log/nginx-agent . Tanpa rotasi log atau penyimpanan pada partisi terpisah, file log dapat menghabiskan seluruh ruang drive kosong dan menyebabkan sistem Anda menjadi tidak responsif terhadap layanan tertentu.
Secara default, Agen NGINX merotasi log setiap hari menggunakan logrotate dengan konfigurasi berikut:
/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
} Jika Anda perlu melakukan perubahan pada konfigurasi default, Anda dapat memperbarui file di sini /etc/logrotate.d/nginx-agent
Untuk detail lebih lanjut tentang konfigurasi logrotate, lihat Opsi Konfigurasi Logrotate
Untuk membuat image yang berisi Agen NGINX terbaru, NGINX OSS versi utama terbaru di Alpine terbaru, jalankan perintah berikut:
make official-oss-imageUntuk membuat image yang berisi Agen NGINX terbaru, NGINX OSS versi stabil terbaru di Alpine terbaru, jalankan perintah berikut:
make official-oss-stable-imageUntuk informasi selengkapnya tentang cara menjalankan kontainer Agen NGINX dan cara membuat image yang menggunakan NGINX Plus, bukan NGINX OSS, lihat Gambar Docker
Ikuti langkah-langkah berikut untuk mengonfigurasi dan menjalankan Agen NGINX dan antarmuka tiruan ("bidang kendali") yang akan dilaporkan oleh Agen NGINX.
Ikuti langkah-langkah di bagian Instalasi untuk mengunduh, menginstal, dan menjalankan NGINX.
Dengan menggunakan metode pilihan Anda, kloning repositori Agen NGINX ke direktori pengembangan Anda. Lihat Mengkloning Repositori GitHub untuk bantuan tambahan.
Agen NGINX dan Mock Control Plane ditulis dalam Go. Go 1.23 atau lebih tinggi diperlukan untuk membangun dan menjalankan aplikasi mana pun dari direktori kode sumber. Anda dapat mengunduh Go dari situs resminya.
Mulai bidang kendali tiruan dengan menjalankan perintah berikut dari direktori akar kode sumber 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
Jika belum ada, buat direktori /etc/nginx-agent/ dan salin file nginx-agent.conf ke dalamnya dari direktori root proyek.
sudo mkdir /etc/nginx-agent
sudo cp <project_root_directory>/nginx-agent.conf /etc/nginx-agent/
Buat file agent-dynamic.conf di direktori /etc/nginx-agent/ , yang diperlukan untuk menjalankan Agen NGINX.
sudo touch /var/lib/nginx-agent/agent-dynamic.conf
Tambahkan pengaturan berikut ke /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 : trueUntuk informasi selengkapnya, lihat Definisi dan Dokumentasi Protokol Agen
Antarmuka NGINX Agent REST dapat diekspos dengan memvalidasi baris berikut di file /etc/nginx-agent/nginx-agent.conf yang ada:
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 "Bidang kontrol tiruan dapat menggunakan protokol gRPC atau REST untuk berkomunikasi dengan Agen NGINX.
Swagger UI mengharuskan goswagger diinstal. Lihat petunjuk pemasangan goswagger untuk bantuan tambahan.
Untuk meluncurkan UI Swagger untuk antarmuka REST, jalankan perintah berikut
make launch-swagger-ui
Buka browser web untuk melihat UI Swagger di http://localhost:8082/docs.
Ekstensi adalah sepotong kode, tidak penting untuk fungsi utama yang menjadi tanggung jawab agen NGINX. Hal ini umumnya berada di luar tanggung jawab pengelolaan Konfigurasi NGINX dan pelaporan metrik NGINX.
Untuk mengaktifkan ekstensi, ekstensi harus ditambahkan ke daftar ekstensi di /etc/nginx-agent/nginx-agent.conf . Berikut adalah contoh mengaktifkan ekstensi metrik lanjutan:
extensions :
- advanced-metrics Jika sudah berjalan, restart NGINX Agent untuk menerapkan konfigurasi baru. Alternatifnya, jika Agen NGINX tidak berjalan, Anda dapat menjalankannya dari direktori root kode sumber.
Buka jendela terminal lain dan mulai Agen NGINX. Keluarkan perintah berikut dari direktori akar kode sumber 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
Buka browser web untuk melihat bidang kontrol tiruan di http://localhost:54790. Tautan berikut akan ditampilkan di antarmuka web:
Untuk kasus penggunaan Agen NGINX lainnya, lihat https://github.com/nginx/agent/tree/main/sdk/examples
Meskipun sebagian besar sistem operasi Linux atau FreeBSD dapat digunakan untuk berkontribusi pada proyek Agen NGINX, langkah-langkah berikut telah dirancang untuk Ubuntu. Ubuntu dikemas dengan sebagian besar perpustakaan yang diperlukan untuk membangun dan menjalankan Agen NGINX, dan merupakan platform yang direkomendasikan untuk pengembangan Agen NGINX.
Ikuti langkah-langkah di bagian Instalasi untuk mengunduh dan menginstal NGINX. Setelah terinstal, pastikan instance NGINX berjalan.
Ikuti langkah-langkah di bagian Memulai Agen NGINX untuk mengkloning Repositori Agen NGINX
Tergantung pada distribusi sistem operasi, mungkin perlu menginstal paket berikut untuk membangun Agen NGINX.
Ubah ke direktori sumber Agen NGINX:
cd <path_to_development_directory>/agent
Instal Pembuatan:
sudo apt install make
Agen NGINX ditulis dalam Go. Anda dapat mengunduh Go dan mengikuti petunjuk instalasi di halaman yang sama atau menjalankan:
sudo apt install golang-go
Instal Protokol:
sudo apt install -y protobuf-compiler
Instal alat dan dependensi Agen NGINX:
Sebelum memulai pengembangan Agen NGINX, penting untuk mengunduh dan menginstal alat dan dependensi yang diperlukan oleh Agen NGINX. Anda dapat melakukannya dengan menjalankan perintah make berikut:
make install-tools
Jalankan perintah berikut untuk membangun dan menjalankan Agen NGINX:
make build
sudo make run
Agen NGINX dapat berjalan di sebagian besar lingkungan. Untuk daftar distribusi yang didukung, lihat panduan Spesifikasi Teknis NGINX.
Agen NGINX dapat diterapkan di lingkungan berikut:
Agen NGINX bekerja dengan semua versi NGINX Open Source dan NGINX Plus yang didukung.
Rekomendasi ukuran sistem minimum untuk Agen NGINX:
| CPU | Ingatan | Jaringan | Penyimpanan |
|---|---|---|---|
| 1 inti CPU | RAM 1 GB | 1 GbE NIC | 20 GB |
Saluran Slack kami #nginx-agent, adalah tempat yang tepat untuk mulai mengajukan pertanyaan dan berbagi pemikiran Anda.
Halaman masalah GitHub kami menawarkan ruang untuk diskusi yang lebih teknis sesuai keinginan Anda.
Terlibatlah dalam proyek ini dengan berkontribusi! Silakan lihat panduan kontribusi kami untuk detailnya.
Lihat halaman rilis kami untuk melacak pembaruan.
Lisensi Apache, Versi 2.0
