ngx_stream_upstream_module

ngx_stream_upstream_module 모듈(1.9.0)은 proxy_pass 명령으로 참조할 수 있는 서버 그룹을 정의하는 데 사용합니다.

예제 구성

upstream backend {
    hash $remote_addr consistent;

    server backend1.example.com:12345  weight=5;
    server backend2.example.com:12345;
    server unix:/tmp/backend3;

    server backup1.example.com:12345   backup;
    server backup2.example.com:12345   backup;
}

server {
    listen 12346;
    proxy_pass backend;
}

정기적 상태 검사를 통해 동적으로 구성 가능한 그룹은 상업용 구독에서 제공합니다.

resolver 10.0.0.1;

upstream dynamic {
    zone upstream_dynamic 64k;

    server backend1.example.com:12345 weight=5;
    server backend2.example.com:12345 fail_timeout=5s slow_start=30s;
    server 192.0.2.1:12345            max_fails=3;
    server backend3.example.com:12345 resolve;
    server backend4.example.com       service=http resolve;

    server backup1.example.com:12345  backup;
    server backup2.example.com:12345  backup;
}

server {
    listen 12346;
    proxy_pass dynamic;
    health_check;
}

Directives

Syntax:  upstream name { ... }
Default: —
Context: stream

서버 그룹을 정의합니다. 서버는 여러 포트에 대해 수신할 수 있습니다. 또한, TCP 및 UNIX 도메인 소켓을 수신하는 서버를 함께 사용할 수 있습니다.

예:

upstream backend {
    server backend1.example.com:12345 weight=5;
    server 127.0.0.1:12345            max_fails=3 fail_timeout=30s;
    server unix:/tmp/backend2;
    server backend3.example.com:12345 resolve;

    server backup1.example.com:12345  backup;
}

기본적으로 연결은 가중치가 적용된 순환 분배 방식으로 서버 간에 분배됩니다. 위의 예시에서 7개의 연결 각각은 다음과 같이 분산됩니다. 5개의 연결은 backend1.example.com:12345에 할당되고, 1개 연결이 각각 두 번째와 세 번째 서버로 할당됩니다. 서버와의 통신 중에 오류가 발생하는 경우, 모든 작동 중인 서버를 시도할 때까지 연결이 다음 서버로 전달됩니다. 모든 서버와의 통신이 실패할 경우, 연결이 종료됩니다.

Syntax:  server address [parameters];
Default: —
Context: upstream

서버의 address와 다른 parameters를 정의합니다. 주소는 필수 포트를 포함한 도메인 이름이나 IP 주소로 지정하거나, “unix:” 접두어 뒤에 UNIX 도메인 소켓 경로로 지정합니다. 여러 IP 주소로 변환되는 도메인 이름으로 여러 서버를 한 번에 정의합니다.

다음의 매개변수를 정의할 수 있습니다.

weight=number

서버 가중치를 설정합니다. 기본값은 1입니다.

max_conns=number

프록시된 서버에 대한 동시 연결의 최대 number를 제한합니다(1.11.5). 기본값은 0인데, 이는 무제한을 나타냅니다. 서버 그룹이 공유된 메모리에 없을 경우, 작업자 프로세스별로 제한이 적용됩니다.

1.11.5버전 이전에서 이 매개변수는 상업용 구독에서 제공되었습니다.

max_fails=number

fail_timeout 매개변수에서 설정한 시간 동안 서버를 사용할 수 없는 것으로 간주되기 전에 fail_timeout 매개변수에서 설정한 시간 동안 서버와의 통신이 실패해야 하는 횟수를 설정합니다. 기본적으로 실패한 시도 횟수는 1로 설정됩니다. 0 값으로 지정하면 시도 횟수를 계산하지 않습니다. 서버와의 연결을 설정하는 동안 시도가 실패하면 오류 또는 시간 초과로 간주됩니다.

fail_timeout=time

sets

• 사용할 수 없는 서버로 간주되기 전에 서버와의 통신이 일정 횟수 실패해야 하는 시간과
• 서버를 사용할 수 없는 시간을 설정합니다.

기본적으로 이 매개변수는 10초로 설정됩니다.

backup

서버를 백업 서버로 표시합니다. 기본 서버를 사용할 수 없을 경우 백업 서버로 연결이 전달됩니다.

이 매개변수는 해시 및 무작위 부하 분산 방법과 사용할 수 없습니다.

down

영구적으로 사용할 수 없는 서버로 표시합니다.

또한, 다음 매개변수는 상업용 구독에 제공됩니다.

resolve

서버의 도메인 이름에 해당하는 IP 주소 변경 사항을 모니터링하고, nginx를 다시 시작하지 않고 업스트림 구성을 자동으로 수정합니다. 서버 그룹은 공유 메모리에 있어야 합니다.

이 매개변수가 작동하려면 resolver 명령을 stream 블록이나 해당 upstream 블록에 지정해야 합니다.

service=name

DNS SRV 레코드 변환을 활성화하고 서비스 name을 설정합니다(1.9.13). 이 매개변수가 작동하려면 서버의 resolve 매개변수를 지정하고 포트 번호 없이 호스트 이름을 지정해야 합니다.

서비스 이름에 점(“.”)이 없을 경우, RFC를 준수하는 이름을 생성하고 TCP 프로토콜을 서비스 접두사에 추가합니다. 예를 들어 _http._tcp.backend.example.com SRV 레코드를 검색하려면 다음의 명령을 지정해야 합니다.

server backend.example.com service=http resolve;

서비스 이름에 점이 하나 이상 들어갈 경우, 서비스 접두사와 서버 이름을 결합하여 이름을 생성할 수 있습니다. 예를 들어 _http._tcp.backend.example.com 및 server1.backend.example.com SRV 레코드를 검색하려면 다음의 명령을 지정해야 합니다.

server backend.example.com service=_http._tcp resolve;
server example.com service=server1.backend resolve;

가장 우선순위가 높은 SRV 레코드(우선순위가 가장 낮은 값이 있는 레코드)는 기본 서버로 변환되고, 나머지 SRV 레코드는 백업 서버로 변환됩니다. backup 매개변수를 서버에 지정한 경우, 우선순위가 높은 SRV 레코드는 백업 서버로 변환되고 나머지 SRV 레코드는 무시됩니다.

slow_start=time

비정상적인 서버가 정상이 되거나, 서버가 일정 기간 사용할 수 없는 상태에서 다시 사용할 수 있게 되었을 때 서버가 0에서 명목 값으로 가중치를 회복하는 time을 설정합니다. 기본값은 0입니다. 즉, 느린 시작이 비활성화됩니다.

이 매개변수는 해시 및 무작위 부하 분산 방법과 사용할 수 없습니다.

그룹에 서버가 하나뿐이면 max_fails, fail_timeout 및 slow_start 매개변수가 무시되고 해당 서버는 절대 사용할 수 없는 상태가 되지 않습니다.

Syntax:  zone name [size];
Default: —
Context: upstream

작업자 프로세스 사이에서 공유되는 그룹 구성과 런타임 상태를 저장하는 공유된 메모리 영역의 name과 size를 정의합니다. 여러 그룹이 같은 영역을 공유할 수 있습니다. 이 경우, size는 한 번만 지정해도 됩니다.

또한, 상업용 구독에서는 ngnix를 다시 시작하지 않고도 해당 그룹에서 그룹 멤버십을 변경하거나, 특정 서버의 설정을 수정합니다. 이 구성은 API 모듈을 통해 액세스할 수 있습니다(1.13.3).

1.13.3버전 이전에는 upstream_conf에서 처리하는 특수한 위치를 통해서만 구성에 액세스할 수 있었습니다.

Syntax:  state file;
Default: —
Context: upstream
This directive appeared in version 1.9.7.

동적으로 구성 가능한 그룹의 상태를 저장하는 file을 지정합니다.

예:

state /var/lib/nginx/state/servers.conf; # path for Linux
state /var/db/nginx/state/servers.conf;  # path for FreeBSD

상태는 매개변수를 포함한 서버 목록으로 제한되고 있습니다. 구성을 파싱할 때 파일을 읽고, 업스트림 구성이 변경될 때마다 업데이트합니다. 직접 파일 내용을 변경하는 것은 삼가야 합니다. 이 명령은 server 명령과 함께 사용할 수 없습니다.

구성을 다시 로드하거나 바이너리를 업그레이드하는 동안 변경 사항이 삭제될 수 있습니다.

이 명령은 상업용 구독에서 제공합니다.

Syntax:  hash key [consistent];
Default: —
Context: upstream

해시된 key 값을 기준으로 클라이언트-서버를 매핑하는 서버 그룹의 부하 분산 방법을 지정합니다. key에는 텍스트, 변수 및 그 두 가지 조합을 포함할 수 있습니다(1.11.2). 사용 예제:

hash $remote_addr;

그룹에 서버를 추가하거나 삭제하면 대부분의 키가 다른 서버로 매핑될 수 있습니다. 이 방법은 Cache::Memcached Perl 라이브러리와 호환됩니다.

consistent 매개변수를 지정할 경우, 대신 ketama와 일치하는 해시 방법을 사용합니다. 이 방법을 사용하면 서버를 그룹에 추가하거나 그룹에서 삭제했을 때 일부 키만 다른 서버로 다시 매핑됩니다. 그러면 캐싱 서버의 캐시 히트 비율이 높아집니다. 이 방법은 ketama_points 매개변수를 160으로 설정한 상태에서 Cache::Memcached::Fast Perl 라이브러리와 호환됩니다.

Syntax:  least_conn;
Default: —
Context: upstream

그룹에서 서버 가중치를 고려하여 활성화된 연결이 가장 적은 서버로 연결을 전달하는 부하 분산 방법을 사용하도록 지정합니다. 이런 서버가 여러 개일 경우, 가중치를 적용한 round-robin 부하 분산 방식으로 돌아가면서 시도합니다.

Syntax:  least_time connect | first_byte | last_byte [inflight];
Default: —
Context: upstream

그룹에서 서버 가중치를 고려하여 활성화된 연결과 평균 시간이 가장 적은 서버로 연결을 전달하는 부하 분산 방법을 사용하도록 지정합니다. 이런 서버가 여러 개일 경우, 가중치를 적용한 순환 부하 분산 방식으로 돌아가면서 시도합니다.

connect 매개변수를 지정한 경우, 업스트림 서버로 연결하는 시간을 사용합니다. first_byte 매개변수를 지정한 경우, 데이터의 첫 바이트를 수신하는 시간을 사용합니다. last_byte를 지정한 경우, 데이터의 마지막 바이트를 수신하는 시간을 사용합니다. inflight 매개변수를 지정한 경우(1.11.6), 불완전한 연결도 반영합니다.

1.11.6버전 이전에는 불완전한 연결을 기본적으로 반영했습니다.

이 명령은 상업용 구독에서 제공합니다.

Syntax:  random [two [method]];
Default: —
Context: upstream
This directive appeared in version 1.15.1.

그룹에서 서버 가중치를 고려하여 무작위로 선택된 서버로 연결을 전달하는 부하 분산 방법을 사용하도록 지정합니다.

two 매개변수 옵션을 사용하면 nginx에서 두 개의 서버를 무작위로 선택하고 지정된 method를 사용하여 서버를 선택합니다. 기본 메서드는 least_conn이며, 활성화된 연결이 가장 적은 서버로 연결을 전달합니다.

least_time 메서드는 활성화된 연결과 평균 시간이 가장 적은 서버로 연결을 전달합니다. least_time=connect 매개변수를 지정한 경우, 업스트림 서버로 연결하는 시간을 사용합니다. least_time=first_byte 매개변수를 지정한 경우, 데이터의 첫 바이트를 수신하는 시간을 사용합니다. least_time=last_byte를 지정한 경우, 데이터의 마지막 바이트를 수신하는 시간을 사용합니다.

least_time 메서드는 상업용 구독에서 제공합니다.

Syntax:  resolver address ... [valid=time] [ipv6=on|off] [status_zone=zone];
Default: —
Context: upstream
This directive appeared in version 1.17.5.

업스트림 서버의 이름을 주소로 변환하는 데 사용하는 이름 서버를 구성합니다. 예를 들어, 다음과 같습니다.

resolver 127.0.0.1 [::1]:5353;

이 주소는 포트 옵션을 포함하여 도메인 이름이나 IP 주소로 지정할 수 있습니다. 포트를 지정하지 않는 경우 53 포트를 사용합니다. 네임 서버는 순환 방식으로 쿼리합니다.

기본적으로 nginx는 변경 중에 IPv4와 IPv6 주소를 모두 검색합니다. IPv6 주소를 검색하고 싶지 않은 경우, ipv6=off 매개변수를 지정할 수 있습니다.

기본적으로 nginx 캐시는 응답의 TTL 값을 사용하여 응답합니다. valid 매개변수 옵션으로 재정의할 수 있습니다.

resolver 127.0.0.1 [::1]:5353 valid=30s;

DNS 스푸핑을 방지하려면 적절히 보안이 되는 신뢰할 수 있는 로컬 네트워크에 DNS 서버를 구성하는 것이 좋습니다.

선택적 status_zone 매개변수를 사용하면 지정된 zone에서 요청 및 응답의 DNS 서버 통계를 수집할 수 있습니다.

이 명령은 상업용 구독에서 제공합니다.

Syntax:  resolver_timeout time;
Default: resolver_timeout 30s;
Context: upstream
This directive appeared in version 1.17.5.

이름 변환에 대한 시간제한을 설정합니다. 예를 들어, 다음과 같습니다.

resolver_timeout 5s;

이 명령은 상업용 구독에서 제공합니다.

임베디드 변수

ngx_stream_upstream_module 모듈은 다음의 임베디드 변수를 지원합니다.

$upstream_addr

IP 주소와 포트, 또는 업스트림 서버의 UNIX 도메인 소켓으로 연결되는 경로를 저장합니다(1.11.4). 프록시를 실행하는 동안 여러 서버에 접촉할 경우, 주소는 쉼표(,)로 구분합니다(예: “192.168.1.1:12345, 192.168.1.2:12345, unix:/tmp/sock”). 서버를 선택할 수 없을 경우, 변수에 서버 그룹 이름을 저장합니다.

$upstream_bytes_received

업스트림 서버에서 수신한 바이트 용량입니다(1.11.4). 서버 연결에서 얻은 값은 $upstream_addr 변수의 주소와 마찬가지로 쉼표(,)로 구분합니다.

$upstream_bytes_sent

업스트림 서버로 전송된 바이트 용량입니다(1.11.4). 서버 연결에서 얻은 값은 $upstream_addr 변수의 주소와 마찬가지로 쉼표(,)로 구분합니다.

$upstream_connect_time

업스트림 서버로 연결하는 시간입니다(1.11.4). 이 시간은 ms 자리까지 초 단위로 저장됩니다. 여러 연결에 대한 시간은 $upstream_addr 변수의 주소와 마찬가지로 쉼표(,)로 구분됩니다.

$upstream_first_byte_time

데이터의 첫 바이트를 수신하는 시간입니다(1.11.4). 이 시간은 ms 자리까지 초 단위로 저장됩니다. 여러 연결에 대한 시간은 $upstream_addr 변수의 주소와 마찬가지로 쉼표(,)로 구분됩니다.

$upstream_session_time

세션 시간을 나타내며, ms 자리까지 초 단위로 나타냅니다(1.11.4). 여러 연결에 대한 시간은 $upstream_addr 변수의 주소와 마찬가지로 쉼표(,)로 구분됩니다.