agent
v2.39.0
NGINX 에이전트는 NGINX 오픈 소스 또는 NGINX Plus 인스턴스의 동반 데몬입니다. 이를 통해 다음이 가능해집니다.
NGINX 에이전트가 보고한 측정항목을 보여주는 Grafana 대시보드
NGINX 에이전트는 NGINX를 실행하는 시스템에서 동반 프로세스로 실행됩니다. NGINX 프로세스 및 운영 체제에서 구성 관리 및 메트릭 수집을 위한 gRPC 및 REST 인터페이스를 제공합니다. NGINX 에이전트는 일반적인 Linux 도구를 사용하여 NGINX와의 원격 상호 작용을 지원하고 대규모 NGINX 인스턴스 컬렉션을 관리할 수 있는 정교한 모니터링 및 제어 시스템을 구축할 수 있는 기능을 제공합니다.
NGINX 에이전트는 업데이트된 구성 파일 제출을 위한 API 인터페이스를 제공합니다. 새 파일을 받으면 nginx -V 의 출력을 확인하여 기존 구성의 위치를 확인합니다. 그런 다음 신호 HUP를 통해 NGINX 마스터 프로세스에 적용하기 전에 nginx -t 사용하여 새 구성을 검증합니다.
NGINX 에이전트는 NGINX 프로세스 정보와 인터페이스하고 NGINX 로그를 구문 분석하여 측정항목을 계산하고 보고합니다. NGINX Plus와 인터페이스할 때 NGINX 에이전트는 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 아키텍처에서 지원하는 최신 패키지를 다운로드하세요.
시스템의 패키지 관리자를 사용하여 패키지를 설치하십시오. 몇 가지 예:
dpkg 패키지 관리자를 사용하는 Debian, Ubuntu 및 기타 배포판.
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최신 Alpine에서 최신 안정 버전의 NGINX OSS인 최신 NGINX 에이전트가 포함된 이미지를 빌드하려면 다음 명령을 실행하세요.
make official-oss-stable-imageNGINX 에이전트 컨테이너를 실행하는 방법과 NGINX OSS 대신 NGINX Plus를 사용하는 이미지를 빌드하는 방법에 대한 자세한 내용은 Docker 이미지를 참조하세요.
NGINX 에이전트와 NGINX 에이전트가 보고할 모의 인터페이스("제어 플레인")를 구성하고 실행하려면 다음 단계를 따르세요.
NGINX를 다운로드, 설치 및 실행하려면 설치 섹션의 단계를 따르세요.
선호하는 방법을 사용하여 NGINX 에이전트 저장소를 개발 디렉터리에 복제합니다. 추가 도움말은 GitHub 리포지토리 복제를 참조하세요.
NGINX 에이전트와 모의 제어 평면은 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/
NGINX 에이전트를 실행하는 데 필요한 /etc/nginx-agent/ 디렉터리에 agent-dynamic.conf 파일을 생성합니다.
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
웹 브라우저를 열어 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
웹 브라우저를 열어 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 에이전트에 대한 최소 시스템 크기 권장 사항:
| CPU | 메모리 | 회로망 | 저장 |
|---|---|---|---|
| CPU 코어 1개 | 1GB RAM | 1GbE NIC | 20GB |
Slack 채널 #nginx-agent는 질문을 하고 생각을 공유하기 위한 최적의 장소입니다.
GitHub 문제 페이지에서는 원하는 속도에 맞춰 더욱 기술적인 토론을 할 수 있는 공간을 제공합니다.
기여를 통해 프로젝트에 참여해보세요! 자세한 내용은 기여 가이드를 참조하세요.
업데이트를 추적하려면 릴리스 페이지를 참조하세요.
Apache 라이센스, 버전 2.0
