NGINX Plus

NGINX Plus API를 사용한 Upstream의 동적 구성

구성을 Reload 하거나 프로세스를 다시 시작하지 않고도 NGINX Plus API를 사용하여 NGINX Plus Upstream 그룹에서 서버를 동적으로 재구성할 수 있습니다.

목차

1. 개요
2. 전제 조건
3. 동적 구성 활성화
4. 동적 구성을 위한 API 사용
5. 동적 구성의 지속성 구성하기

1. 개요

NGINX Plus를 사용하면 서버 그룹에 있는 Upstream 서버의 구성을 서버 및 NGINX 구성을 Reload하지 않고도 실시간으로 수정할 수 있습니다. 이 기능은 다음과 같은 경우에 유용합니다.

  • 서버를 추가해야 하는 경우, Autoscaling 기능
  • 유지 관리, 서버를 제거하거나 백업 서버를 지정하거나 서버를 일시적으로 중단해야 하는 경우
  • 서버 가중치, Active 연결, Slow Start, Failure Timeout과 같은 Upstream 서버 설정을 변경해야 하는 경우 빠른 설정을 사용할 수 있습니다.
  • 모니터링, 하나의 명령으로 서버 또는 서버 그룹의 상태를 확인할 수 있습니다.

이러한 변경은 API 명령이 포함된 NGINX Plus REST API 인터페이스를 통해 이루어집니다.

Note: NGINX Plus 릴리스 12(R12) 이하에서는 upstream_conf Handler를 사용하여 동적 구성을 수행했습니다. 이제 해당 API는 더 이상 사용되지 않으며 NGINX Plus API를 사용합니다.

2. 전제 조건

동적 구성 기능을 사용하기 전에 다음 환경이 갖추어져 있는지 확인하세요.

  1. NGINX Plus R13 이상 버전
  2. HTTP Load Balancing 또는 TCP 및 UDP Load Blancning에 설명된 대로 애플리케이션 또는 웹 서버의 Upstream 그룹을 만들었습니다.
  3. Upstream 서버 그룹은 여러 Worker Processes와 데이터 공유에 설명된 대로 공유 메모리 Zone에 위치합니다.

3. 동적 구성 활성화

1. 서버 그룹에 트래픽 Proxy에 설명된 대로 Upstream 서버 그룹을 만듭니다.

http {
    # ...
    upstream appservers {          
        server appserv1.example.com      weight=5;
        server appserv2.example.com:8080 fail_timeout=5s;
        server reserve1.example.com:8080 backup;
        server reserve2.example.com:8080 backup;
    }

    server {
    # Location that proxies requests to the upstream group
        location / {
            proxy_pass http://appservers;
            health_check;
         }
    }
}

2. upstream 블록에 zone 지시문을 포함합니다. zone 지시문은 공유 메모리에 Zone을 구성하고 Zone 이름과 크기를 설정합니다. 서버 그룹의 구성은 이 Zone에 유지되므로 모든 Worker Processes가 동일한 구성을 사용합니다.

http {
    # ...
    upstream appservers {
        zone appservers 64k;

        server appserv1.example.com      weight=5;
        server appserv2.example.com:8080 fail_timeout=5s;
        server reserve1.example.com:8080 backup;
        server reserve2.example.com:8080 backup;
    }
}

3. server 블록의 전용 location 블록에 api 지시문을 포함하여 read-write 모드에서 NGINX API를 사용하도록 설정합니다.

해당 위치 및 PATCH/POST/DELETE 메서드에 대한 액세스를 제한하는 것이 좋습니다. 이 예에서는 allow 및 deny 지시문을 사용하여 localhost 주소(127.0.0.1)로부터의 접근을 허용하고 다른 모든 주소로부터의 접근을 거부합니다. 또한 HTTP 기본 인증을 사용하여 PATCH/POST/DELETE 메서드에 대한 액세스를 제한합니다.

server {
    location /api {
        limit_except GET {
            auth_basic "NGINX Plus API";
            auth_basic_user_file /path/to/passwd/file;
        }
        api write=on;
        allow 127.0.0.1;
        deny  all;
    }
}

전체 예제.

http {
    # ...
    # Configuration of the server group
    upstream appservers {
        zone appservers 64k;
        
        server appserv1.example.com      weight=5;
        server appserv2.example.com:8080 fail_timeout=5s;
        server reserve1.example.com:8080 backup;
        server reserve2.example.com:8080 backup;
    }
    server {
        # Location that proxies requests to the upstream group
        location / {
            proxy_pass http://appservers;
            health_check;
        }
        
        # Location for dynamic configuration requests
        location /api {
            limit_except GET {
                auth_basic "NGINX Plus API";
                auth_basic_user_file /path/to/passwd/file;
            }
            api write=on;
            allow 127.0.0.1;
            deny  all;
        }
    }
}

4. 동적 구성을 위한 API 사용

NGINX Plus REST API는 다음과 같은 HTTP 메서드를 지원합니다.

  • GET – Upstream 그룹 또는 그룹 내 개별 서버에 대한 정보 표시
  • POST – Upstream 그룹에 서버 추가
  • PATCH – 특정 서버의 매개변수 수정
  • DELETE – Upstream 그룹에서 서버 삭제

NGINX Plus API의 Endpoint와 메서드는 NGINX 모듈 참조에 설명되어 있습니다. 또한 API에는 API를 탐색하고 각 리소스의 기능을 이해하는 데 사용할 수 있는 Swagger 사양이 내장되어 있습니다. Swagger 문서는 http://NGINX-host/swagger-ui/ 에서 확인할 수 있습니다.

Upstream 그룹의 구성을 동적으로 변경하려면 적절한 API 메서드를 사용하여 HTTP 요청을 보내세요. 다음 예제에서는 curl 명령을 사용하지만, HTTP 요청을 위한 모든 메커니즘이 지원됩니다. 모든 요청 본문과 응답은 JSON 형식입니다.

URI는 다음 정보를 순서대로 지정합니다.

  • 요청을 처리하는 노드의 호스트 명 또는 IP 주소(다음 예제에서는 127.0.0.1)
  • API 지시문이 표시되는 위치(api)
  • API 버전 (8)
  • Upstream 그룹의 이름, “/”로 구분된 경로(http/upstreams/appservers)로 표시되는 NGINX Plus 구성 계층 구조에서 해당 위치를 완성합니다.

예를 들어, appservers Upstream 그룹에 새 서버를 추가하려면 다음 curl 명령을 전송합니다.

curl -X POST -d '{ \
   "server": "10.0.0.1:8089", \
   "weight": 4, \
   "max_conns": 0, \
   "max_fails": 0, \
   "fail_timeout": "10s", \
   "slow_start": "10s", \
   "backup": true, \
   "down": true \
 }' -s 'http://127.0.0.1/api/8/http/upstreams/appservers/servers'

Upstream 그룹에서 서버를 제거하려면 다음과 같이 하세요.

curl -X DELETE -s 'http://127.0.0.1/api/8/http/upstreams/appservers/servers/0'

그룹의 첫 번째 서버(ID 0)에 대한 down 매개변수를 설정하려면 다음과 같이 하세요.

curl -X PATCH -d '{ "down": true }' -s 'http://127.0.0.1/api/8/http/upstreams/appservers/servers/0'

5. 동적 구성의 지속성 구성하기

API 활성화의 기본 구성을 사용하면 API로 변경한 내용이 공유 메모리 Zone에만 저장됩니다. 변경 사항은 NGINX Plus 구성 파일을 Reload할 때 삭제됩니다.

구성을 Reload할 때 변경 사항을 유지하려면 upstream 블록의 Upstream 서버 목록을 state 지시문으로 정의한 서버 상태 저장을 위한 특수 파일로 이동합니다. Linux 배포판의 경우 권장 경로는 /var/lib/nginx/state/이며, FreeBSD 배포판의 경우 /var/db/nginx/state/입니다.

http {
    # ...
    upstream appservers {
        zone appservers 64;
        state /va lib/nginx/state/appservers.conf;
        
        # All servers are defined in the state file
        # server appserv1.example.com      weight=5;
        # server appserv2.example.com:8080 fail_timeout=5s;
        # server reserve1.example.com:8080 backup;
        # server reserve2.example.com:8080 backup;
    }
}

상태 파일은 API 인터페이스의 구성 명령으로만 수정할 수 있으며, 텍스트 편집기 등을 사용하여 파일을 직접 수정해서는 안 된다는 점에 유의하세요.