NGINX Agent 설정 가이드

이 문서는 NGINX Agent 설정을 설정 파일, CLI 플래그, 환경 변수를 사용하여 설정하는 방법을 다룹니다.

Note:

– NGINX 에이전트는 다음과 같은 우선 순위에 따라 설정 파일, CLI 플래그 및 환경 변수에 의해 설정된 설정 값을 해석합니다.
1. CLI 플래그는 설정 파일과 환경 변수 값을 덮어씁니다
2. 환경 변수는 설정 파일 값을 덮어씁니다.
3. 설정 파일은 가장 낮은 우선순위를 가지며, 다른 옵션을 사용하면 설정은 해당 옵션으로 대체됩니다.

– 사용할 포트, IP에 대해 필요한 방화벽을 포트를 열거나 SELinux/AppArmor 규칙을 추가해야 합니다.

목차

1. 설정 파일을 통한 NGINX Agent 설정
2. CLI 플래그, 환경 변수를 통한한 NGINX Agent 설정
 2-1. 사용법
 2-2. CLI 플래그와 환경 변수
3. Log rotation

1. 설정 파일을 통한 NGINX Agent 설정

NGINX Agent의 기본 설정 파일 위치는 /etc/nginx-agent/nginx-agent.conf와 /var/lib/nginx-agent/agent-dynamic.conf입니다. FreeBSD에서,  agent-dynamic.conf 파일 위치는  /var/db/nginx-agent/agent-dynamic.conf입니다. 설정 파일 내부의 상단에는 해당 설정을 설명하는 주석이 있습니다.

설정 파일의 예시는 아래와 같습니다.

nginx-agent.conf 파일 예시

Note:

아래의 nginx-agent.conf 파일에서 컨트롤 플레인에 연결하기 위해 server.host와 server.grpcPort을 변경할 수 있습니다.

#
# /etc/nginx-agent/nginx-agent.conf
#
# Configuration file for NGINX Agent.
#
# This file tracks agent configuration values that are meant to be statically set. There
# are additional NGINX Agent configuration values that are set via the API and agent install script
# which can be found in /etc/nginx-agent/agent-dynamic.conf.

# specify the server grpc port to connect to
server:
  # host of the control plane
  host: <FQDN>
  grpcPort: 443
  backoff: # note: default values are prepopulated 
    initial_interval: 100ms # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
    randomization_factor: 0.10 # Add the appropriate float value here, e.g., 0.10
    multiplier: 1.5 # Add the appropriate float value here, e.g., 1.5
    max_interval: 1m # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
    max_elapsed_time: 0 # Add the appropriate duration value here, e.g., "0" for indefinite "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
# tls options
tls:
  # enable tls in the nginx-agent setup for grpcs
  # default to enable to connect with secure connection but without client cert for mtls
  enable: true
  # controls whether the server certificate chain and host name are verified.
  # for production use, see instructions for configuring TLS
  skip_verify: false
log:
  # set log level (panic, fatal, error, info, debug, trace; default "info")
  level: info
  # set log path. if empty, don't log to file.
  path: /var/log/nginx-agent/
nginx:
  # path of NGINX logs to exclude
  exclude_logs: ""
  # Set to true when NGINX configuration should contain no warnings when performing a configuration apply (nginx -t is used to carry out this check)
  treat_warnings_as_errors: false # Default is false
# data plane status message / 'heartbeat'
dataplane:
  status:
    # poll interval for dataplane status - the frequency the NGINX Agent will query the dataplane for changes
    poll_interval: 30s
    # report interval for dataplane status - the maximum duration to wait before syncing dataplane information if no updates have been observed
    report_interval: 24h
metrics:
  # specify the size of a buffer to build before sending metrics
  bulk_size: 20
  # specify metrics poll interval
  report_interval: 1m
  collection_interval: 15s
  mode: aggregated
    backoff: # note: default values are prepopulated 
      initial_interval: 100ms # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
      randomization_factor: 0.10 # Add the appropriate float value here, e.g., 0.10
      multiplier: 1.5 # Add the appropriate float value here, e.g., 1.5
      max_interval: 1m # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
      max_elapsed_time: 0 # Add the appropriate duration value here, e.g., "0" for indefinite "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour

# OSS NGINX default config path
# path to aux file dirs can also be added
config_dirs: "/etc/nginx:/usr/local/etc/nginx"

# Internal queue size
queue_size: 100

extensions:
  - nginx-app-protect

# Enable reporting NGINX App Protect details to the control plane.
nginx_app_protect:
  # Report interval for NGINX App Protect details - the frequency NGINX Agent checks NGINX App Protect for changes.
  report_interval: 15s
  # Enable precompiled publication from the NGINX Management Suite (true) or perform compilation on the data plane host (false).
  precompiled_publication: true

dynamic-agent.conf 파일 예시

Note:

Linux 환경의 기본 위치: /var/lib/nginx-agent/agent-dynamic.conf
FreeBSD 환경의 기본 위치: /var/db/nginx-agent/agent-dynamic.conf

# Dynamic configuration file for NGINX Agent.
#
# The purpose of this file is to track agent configuration
# values that can be dynamically changed via the API and the agent install script.
# You may edit this file, but API calls that modify the tags on this system will
# overwrite the tag values in this file.
#
# The agent configuration values that API calls can modify are as follows:
# tags:
#   - dev
#   - qa
#
# The agent configuration value that the agent install script can modify are as follows:
# instance_group: my-instance-group

instance_group: my-instance-group
tags:
  - dev
  - qa

2. CLI 플래그, 환경 변수를 통한한 NGINX Agent 설정

이 항목은 NGINX Agent 설정에 사용되는 CLI 플래그와 해당하는 환경 변수에 대해 자세히 설명합니다.

2-1. 사용법

CLI 플래그

nginx-agent [flags]

환경 변수

export ENV_VARIABLE_NAME="value"
nginx-agent

2-2. CLI 플래그와 환경 변수

주의:

2.35.0 이전 버전에서는 환경 변수에 NGINX_AGENT_ 대신 NMS_ 가 접두사로 사용되었습니다.

Note:

NGINX Agent가 읽고 쓸 수 있는 디렉토리를 인식할 수 있도록 nginx-agent.conf 파일에서 config_dirs 키를 사용하거나, --config-dirs 커맨드 라인 옵션을 사용하세요.

NGINX Agent는 설정을 업데이트할 때 지정된 위치 외부의 디렉토리에 쓰거나 파일을 업로드할 수 없습니다.

NGINX Agent는 NGINX 구성 지시문에 따라 지정된 디렉토리 외부의 파일 경로를 따르고 인증서의 메타데이터를 읽습니다. NGINX 에이전트는 다음 지시문을 사용합니다.
– ssl_certificate

Note:

동적 설정 파일의 위치를 설정하기 위해 --dynamic-config-path 커맨드 라인 옵션을 사용하세요. 이 설정을 사용하려면 동적 구성을 새 경로로 이동하거나 지정된 위치에 새 동적 구성 파일을 생성해야 합니다.

Linux 환경의 기본 위치: /var/lib/nginx-agent/agent-dynamic.conf
FreeBSD 환경의 기본 위치: /var/db/nginx-agent/agent-dynamic.conf

3. Log Rotation

기본적으로, NGINX Agent는 다음 설정에 따라 logrotate로 매일 로그를 rotate합니다.

NGINX Agent 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 Configuration Options을 참고하세요.