ngx_http_upstream_module

ngx_http_upstream_module 모듈은 proxy_pass, fastcgi_pass, uwsgi_pass, scgi_pass, memcached_pass 및 grpc_pass 명령으로 참조할 수 있는 서버 그룹을 정의하는 데 사용됩니다.keepalive connections

예제 구성

upstream backend {
    server backend1.example.com       weight=5;
    server backend2.example.com:8080;
    server unix:/tmp/backend3;

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

server {
    location / {
        proxy_pass http://backend;
    }
}

주기적인 상태 검사를 포함하는 동적으로 구성 가능한 그룹은 상업용 구독의 일부로 사용할 수 있습니다.

resolver 10.0.0.1;

upstream dynamic {
    zone upstream_dynamic 64k;

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

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

server {
    location / {
        proxy_pass http://dynamic;
        health_check;
    }
}

Directives

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

서버 그룹을 정의합니다. 서버는 다양한 포트에서 수신 대기할 수 있습니다. 또한, TCP 및 UNIX-도메인 소켓에서 수신 대기하는 서버는 혼합될 수 있습니다

예:

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

    server backup1.example.com  backup;
}

기본적으로 요청은 가중치가 매겨진 라운드 로빈 부하 분산 방법을 사용하여 서버 사이에서 분산됩니다. 위의 예에서 7개의 요청은 각각 다음과 같이 분산됩니다. 5개의 요청은 backend1.example.com으로 이동하고 두 번째와 세 번째 서버로 1개의 요청이 각각 이동합니다. 서버와의 통신 중에 오류가 발생하면 요청은 다음 서버로 전달되고, 작동하는 서버가 모두 시도될 때까지 다음 서버로의 전달이 계속 이어집니다. 어떤 서버에서도 요청이 성공하지 못하면 클라이언트는 마지막 서버와의 통신 결과를 수신합니다.

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

서버의 주소와 기타 매개변수를 정의합니다. 주소는 포트 옵션과 함께 도메인 이름 또는 IP 주소로 또는 “unix:” 접두사 다음에 지정되는 UNIX-도메인 소켓 경로로 지정할 수 있습니다. 포트가 지정되지 않으면 포트 80이 사용됩니다. 여러 IP 주소로 확인하는 도메인 이름은 한 번에 여러 서버를 정의합니다.

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

max_conns=number

프록시 설정된 서버(1.11.5)에 대한 최대 동시 활성 연결 수를 제한합니다. 기본값은 0으로 제한 없음을 의미합니다. 서버 그룹이 공유 메모리에 상주하지 않으면 제한이 작업자 프로세스당 작동합니다.

유휴 keepalive 연결, 여러 작업자 및 공유 메모리가 활성화된 경우 프록시 설정된 서버에 대한 전체 활성 및 유휴 연결 수는 max_conns 값을 초과할 수 있습니다.

max_fails=number

fail_timeout 매개변수로 설정된 기간에 발생해야 하는 서버와의 실패한 통신 시도 수를 설정하여 fail_timeout 매개변수로도 설정되는 기간에 사용할 수 없는 서버를 고려합니다. 기본적으로 실패한 시도 수는 1로 설정됩니다. 0 값은 시도 계산을 비활성화합니다. 실패한 시도로 간주되는 것은 proxy_next_upstream, fastcgi_next_upstream, uwsgi_next_upstream, scgi_next_upstream, memcached_next_upstream 및 grpc_next_upstream 명령으로 정의됩니다.

fail_timeout=time

다음을 설정합니다.

  • 서버와의 실패한 통신 시도의 지정된 횟수가 일어나 서버를 사용 불가로 간주해야 하는 기간
  • 서버가 사용 불가로 간주되는 기간

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

backup

서버를 백업 서버로 표시합니다. 기본 서버를 사용할 수 없을 때 요청이 전달됩니다.

매개변수는 hash, ip_hash 및 random 부하 분산 방법과 함께 사용할 수 없습니다.

down

서버를 영구적 사용 불가로 표시합니다.

또한 다음 매개변수가 상업용 구독의 일부로 사용 가능합니다.

resolve

서버의 도메인 이름에 해당하는 IP 주소의 변경 사항을 모니터링하고 nginx(1.5.12)를 재시작할 필요 없이 업스트림 구성을 자동으로 수정합니다. 서버 그룹은 공유 메모리에 상주해야 합니다.

이 매개변수가 작동하려면 확인자 명령이 http 블록 또는 해당하는 업스트림 블록에 지정되어야 합니다.

route=string

서버 경로 이름을 설정합니다.

service=name

DNS SRV 레코드의 확인을 활성화하고 서비스 이름(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에서 명목 값으로 가중치를 복구하는 시간을 설정합니다. 기본값은 0입니다. 즉, 느린 시작이 비활성화됩니다.

매개변수는 hash, ip_hash 및 random 부하 분산 방법과 함께 사용할 수 없습니다.

drain

서버를”드레이닝” 모드(1.13.6)로 전환합니다. 이 모드에서는 서버에 바인딩된 요청만 프록시 설정됩니다.

버전 1.13.6 이전에는 매개변수를 API 모듈로만 변경할 수 있었습니다.

그룹에 단일 서버만 있는 경우 max_fails, fail_timeout 및 slow_start 매개변수는 무시되고 그러한 서버는 절대로 사용 불가로 간주되지 않습니다.

Syntax:  zone name [size];
Default: —
Context: upstream
This directive appeared in version 1.9.0.

작업자 프로세스 사이에 공유되는 그룹의 구성 및 런타임 상태를 유지하는 공유 메모리 영역의 이름 및 크기를 정의합니다. 여러 그룹이 동일한 영역을 공유할 수 있습니다. 이 경우, 크기를 한 번만 지정하는 것으로 충분합니다.

또한, 상업용 구독의 일부로 그러한 그룹을 사용하여 그룹 멤버십을 변경하거나 nginx를 다시 시작할 필요 없이 특정한 서버의 설정을 수정할 수 있습니다. 구성은 API 모듈(1.13.3)을 통해 액세스할 수 있습니다.

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

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

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

예:

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

상태는 현재 매개변수를 포함하는 서버의 목록으로 제한됩니다. 파일은 구성을 구문 분석할 때 읽히고 업스트림 구성이 변경될 때마다 업데이트됩니다. 파일 콘텐츠를 직접 변경하는 것은 피해야 합니다. 명령은 서버 명령과 함께 사용할 수 없습니다.

구성 다시 로드 또는 바이너리 업그레이드 동안 변경된 사항은 손실될 수 있습니다.

이 명령은 상업용 구독의 일부로 사용 가능합니다.

Syntax:  hash key [consistent];
Default: —
Context: upstream
This directive appeared in version 1.7.2.

클라이언트-서버 매핑이 해시된 키 값을 기반으로 하는 서버 그룹에 대해 부하 분산 방법을 지정합니다. 키는 텍스트, 변수 및 그 조합을 포함할 수 있습니다. 그룹에 서버를 추가하거나 그룹에서 서버를 제거하면 대부분의 키가 다른 서버에 다시 매핑될 수 있습니다. 이 방법은 Cache::Memcached Perl 라이브러리와 호환됩니다.

consistent 매개변수가 지정되면 ketama 일치 해싱 방법이 대신 사용됩니다. 이 방법은 서버가 그룹에 추가되거나 그룹에서 제거되는 경우 몇 개 키만 다른 서버에 다시 매핑되도록 합니다. 이렇게 하면 캐싱 서버에 대한 더 높은 캐시 적중률을 달성하는 데 도움이 됩니다. 이 방법은 ketama_points 매개변수가 160으로 설정된 Cache::Memcached::Fast Perl 라이브러리와 호환됩니다.

Syntax:  ip_hash;
Default: —
Context: upstream

그룹에서 클라이언트 IP 주소를 기준으로 서버 사이에서 요청이 분산되는 부하 분산 방법을 사용해야 한다고 지정합니다. 클라이언트 IPv4 주소의 처음 3개의 옥텟 또는 전체 IPv6 주소가 해싱 키로 사용됩니다. 이 방법은 동일한 클라이언트의 요청이 해당 서버가 사용 불가능한 경우를 제외하고 항상 동일한 서버로 전달되도록 합니다. 서버가 사용 불가능한 경우에는 클라이언트 요청은 다른 서버로 전달됩니다. 항상 동일한 서버로 전달될 확률이 가장 높습니다.

IPv6 주소는 버전 1.3.2 및 1.2.2부터 지원됩니다.

서버 중 하나를 일시적으로 제거해야 하는 경우 클라이언트 IP 주소의 현재 해싱을 보존하기 위해 해당 서버가 down 매개변수로 표시되어야 합니다.

예:

upstream backend {
    ip_hash;

    server backend1.example.com;
    server backend2.example.com;
    server backend3.example.com down;
    server backend4.example.com;
}

버전 1.3.1 및 1.2.2까지 ip_hash 부하 분산 방법을 사용하여 서버에 대한 가중치를 지정하는 것이 가능하지 않았습니다.

Syntax:  keepalive connections;
Default: —
Context: upstream
This directive appeared in version 1.1.4.

업스트림 서버에 대한 연결의 캐시를 활성화합니다.

connections 매개변수는 각 작업자 프로세스의 캐시에서 보존되는 업스트림 서버에 대한 유휴 keepalive 연결의 최대 수를 설정합니다. 이 수를 초과하면 최소 최근 사용 연결이 닫힙니다.

특히 keepalive 명령이 nginx 작업자 프로세스가 열 수 있는 업스트림 서버에 대한 전체 연결 수를 제한하지 않는다는 점을 특별히 주목해야 합니다. connections 매개변수는 업스트림 서버가 새로운 수신 연결도 처리할 수 있을 만큼 숫자를 작게 설정해야 합니다.

기본 라운드 로빈 방법이 아닌 부하 분산 방법을 사용하는 경우 keepalive 명령 앞에서 해당 방법을 활성화해야 합니다.

keepalive 연결이 있는 memcached 업스트림의 예제 구성:

upstream memcached_backend {
    server 127.0.0.1:11211;
    server 10.0.0.2:11211;

    keepalive 32;
}

server {
    ...

    location /memcached/ {
        set $memcached_key $uri;
        memcached_pass memcached_backend;
    }

}

HTTP의 경우 proxy_http_version 명령은 “1.1”로 설정되어야 하고 “Connection” 헤더 필드는 지워야 합니다.

upstream http_backend {
    server 127.0.0.1:8080;

    keepalive 16;
}

server {
    ...

    location /http/ {
        proxy_pass http://http_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        ...
    }
}

또는, HTTP/1.0 영구 연결은 “Connection: Keep-Alive” 헤더 필드를 업스트림 서버로 전달하여 사용할 수 있습니다. 하지만 이 방법은 권장되지 않습니다.

FastCGI 서버의 경우 keepalive 연결이 작동하려면 fastcgi_keep_conn을 설정해야 합니다.

upstream fastcgi_backend {
    server 127.0.0.1:9000;

    keepalive 8;
}

server {
    ...

    location /fastcgi/ {
        fastcgi_pass fastcgi_backend;
        fastcgi_keep_conn on;
        ...
    }
}

SCGI 및 uwsgi 프로토콜에는 keepalive 연결의 개념이 없습니다.

Syntax:  keepalive_requests number;
Default: keepalive_requests 1000;
Context: upstream
This directive appeared in version 1.15.3.

하나의 keepalive 연결을 통해 제공할 수 있는 최대 요청 수를 설정합니다. 최대 요청 수가 실행된 후 연결이 닫힙니다.

각 연결에 할당된 메모리를 해제하려면 정기적으로 연결을 닫아야 합니다. 그러므로 지나치게 요청 수가 많으면 과도한 메모리를 사용할 수 있으므로, 권장하지 않습니다.

버전 1.19.10 이전에는 기본값이 100이었습니다.

Syntax:  keepalive_time time;
Default: keepalive_time 1h;
Context: upstream
This directive appeared in version 1.19.10.

요청이 하나의 keepalive 연결을 통해 처리될 수 있는 최대 시간을 제한합니다. 이 시간에 도달하고 나면 하위 요청을 처리한 후 연결이 종료됩니다.

Syntax:  keepalive_timeout timeout;
Default: keepalive_timeout 60s;
Context: upstream
This directive appeared in version 1.15.3.

업스트림 서버에 대한 유휴 keepalive 연결이 계속 열려 있는 시간제한을 설정합니다.

Syntax:  ntlm;
Default: —
Context: upstream
This directive appeared in version 1.9.2.

NTLM 인증을 통한 프록시 사용 요청을 허용합니다. 업스트림 연결은 클라이언트가 “Negotiate” 또는 “NTLM”으로 시작하는 “권한 부여” 헤더 필드 값을 가진 요청을 전송하면 클라이언트 연결에 바인딩됩니다. 추가 클라이언트 요청은 동일한 업스트림 연결을 통해 프록시 설정되어 인증 컨텍스트를 유지합니다.

NTLM 인증이 작동하려면 업스트림 서버에 대한 keepalive 연결을 활성화해야 합니다. proxy_http_version 명령은 “1.1”로 설정되어야 하고 “Connection” 헤더 필드는 지워야 합니다.

upstream http_backend {
    server 127.0.0.1:8080;

    ntlm;
}

server {
    ...

    location /http/ {
        proxy_pass http://http_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        ...
    }
}

기본 라운드 로빈 방법이 아닌 분산 장치 방법을 사용하는 경우 ntlm 명령 앞에서 해당 방법을 활성화해야 합니다.

이 명령은 상업용 구독의 일부로 사용 가능합니다.

Syntax:  least_conn;
Default: —
Context: upstream
This directive appeared in versions 1.3.1 and 1.2.2.

그룹에서 최소 활성 연결 수를 가진 서버로 요청이 전달되는 부하 분산 방법을 사용해야 한다고 지정하여 서버의 계정 가중치를 고려합니다. 그러한 서버가 여러 개 있는 경우 가중치가 매겨진 라운드 로빈 부하 분산 방법을 사용하여 해당 서버가 차례로 시도됩니다.

Syntax:  least_time header | last_byte [inflight];
Default: —
Context: upstream
This directive appeared in version 1.7.10.

그룹에서 평균 응답 시간이 가장 적고 최소 활성 연결 수를 가진 서버로 요청이 전달되는 부하 분산 방법을 사용해야 한다고 지정하여 서버의 계정 가중치를 고려합니다. 그러한 서버가 여러 개 있는 경우 가중치가 매겨진 라운드 로빈 부하 분산 방법을 사용하여 해당 서버가 차례로 시도됩니다.

header 매개변수가 지정되면 응답 헤더를 수신한 시간이 사용됩니다. last_byte 매개변수가 지정되면 전체 응답을 수신한 시간이 사용됩니다. inflight 매개변수가 지정되면(1.11.6) 완료되지 않은 요청도 고려됩니다.

버전 1.11.6 이전에는 완료되지 않은 요청이 기본적으로 고려되었습니다.

이 명령은 상업용 구독의 일부로 사용 가능합니다.

Syntax:  queue number [timeout=time];
Default: —
Context: upstream
This directive appeared in version 1.5.12.

요청을 처리하는 동안 즉시 업스트림 서버를 선택할 수 없는 경우 요청은 대기열에 배치됩니다. 명령은 동시에 대기열에 있을 수 있는 최대 요청 수를 지정합니다. 대기열이 가득 차거나 요청을 전달할 서버를 timeout 매개변수에 지정된 기간 내에 선택할 수 없는 경우 502(잘못된 게이트웨이) 오류가 클라이언트에 반환됩니다.

timeout 매개변수의 기본값은 60초입니다.

기본 라운드 로빈 방법이 아닌 부하 분산 장치 방법을 사용하는 경우 queue 명령 앞에서 해당 방법을 활성화해야 합니다.

이 명령은 상업용 구독의 일부로 사용 가능합니다.

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

그룹에서 요청이 임의로 선택된 서버로 전달되는 부하 분산 방법을 사용해야 한다고 지정하여 서버 가중치를 고려합니다.

two 매개변수 옵션은 무작위로 2개의 서버를 선택한 다음 지정된 방법을 사용하여 서버를 선택하도록 nginx에 지시합니다. 기본 방법은 최소 활성 연결 수를 가진 서버에 요청을 전달하는 least_conn입니다.

least_time 방법은 최소 평균 응답 시간과 최소 활성 연결 수를 가진 서버에 요청을 전달합니다. least_time=header가 지정되면 응답 헤더 수신 시간이 사용됩니다. 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 매개변수 옵션은 지정된 영역에서 요청 및 응답의 DNS 서버 통계 수집을 활성화합니다.

이 명령은 상업용 구독의 일부로 사용 가능합니다.

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

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

resolver_timeout 5s;

Syntax:  sticky cookie name [expires=time] [domain=domain] [httponly] [samesite=strict|lax|none] [secure] 
         [path=path];
         sticky route $variable ...;
         sticky learn create=$variable lookup=$variable zone=name:size [timeout=time] [header] [sync];
Default: —
Context: upstream
This directive appeared in version 1.5.7.

세션 선호도를 활성화합니다. 그러면 동일한 클라이언트의 요청이 서버 그룹의 동일한 서버로 전달됩니다. 다음 3가지 방법을 사용할 수 있습니다.

cookie

쿠키 방법이 사용되면 지정된 서버에 대한 정보가 nginx가 생성한 HTTP 쿠키로 전달됩니다.

upstream backend {
    server backend1.example.com;
    server backend2.example.com;

    sticky cookie srv_id expires=1h domain=.example.com path=/;
}

아직 특정한 서버에 바인딩되지 않은 클라이언트에서 나온 요청은 구성된 분산 방법으로 선택된 서버로 전달됩니다. 이 쿠키를 포함하는 추가 요청은 지정된 서버로 전달됩니다. 지정된 서버가 요청을 처리할 수 없는 경우 클라이언트가 아직 바운딩되지 않은 것처럼 새로운 서버가 선택됩니다.

로드 밸런싱 방식은 항상 이미 바인딩된 요청을 고려하여 부하를 고르게 분산하려고 하므로 활성 바인딩된 요청 수가 많은 서버는 바인딩되지 않은 새로운 요청을 받을 가능성이 적습니다.

첫 번째 매개변수는 설정되거나 검사되도록 쿠키의 이름을 설정합니다. 쿠키 값은 IP 주소 및 포트의 MD5 해시 또는 UNIX-도메인 소켓 경로의 16진수 표현입니다. 그러나 서버 명령의 “route” 명령이 지정되는 경우 쿠키 값은 “route” 매개변수의 값이 됩니다.

upstream backend {
    server backend1.example.com route=a;
    server backend2.example.com route=b;

    sticky cookie srv_id expires=1h domain=.example.com path=/;
}

이 경우 “srv_id” 쿠키의 값은 a 또는 b가 됩니다.

추가 매개변수는 다음과 같을 수 있습니다.

expires=time

브라우저가 쿠키를 유지해야 하는 시간을 설정합니다.  특수 값 max로 인해 쿠키는 “2037년 12월 31일 23:55:55 GMT”에 만료됩니다. 매개변수가 지정되지 않으면 쿠키는 브라우저 세션이 끝날 때 만료됩니다.

domain=domain

쿠키가 설정되는 도메인을 정의합니다. 매개변수 값에는 변수(1.11.5)가 포함될 수 있습니다.

httponly

HttpOnly 특성을 쿠키에 추가합니다(1.7.11).

samesite=strict | lax | none

SameSite 특성을 다음 값 중 하나를 가진 쿠키에 추가합니다(1.19.4). Strict, Lax 또는 None.

secure

Secure 특성을 쿠키에 추가합니다(1.7.11).

path=path

쿠키가 설정되는 경로를 정의합니다.

매개변수가 생략되면 해당하는 쿠키 필드가 설정되지 않습니다.

route

경로 방법이 사용되면 프록시 설정된 서버가 첫 번째 요청 수신 시 클라이언트에 경로를 할당합니다. 이 클라이언트의 모든 후속 요청은 쿠키 또는 URI에 라우팅 정보를 전달합니다. 이 정보가 서버 명령의 “route” 매개변수와 비교되어 요청이 프록시 설정되어야 하는 서버를 식별합니다. “route” 매개변수가 지정되지 않으면 경로 이름은 IP 주소 및 포트의 MD5 해시의 16진수 표현 또는 UNIX-도메인 소켓 경로가 됩니다. 지정된 서버에서 요청을 처리할 수 없는 경우 요청에 라우팅 정보가 없는 것처럼 구성된 분산 방법으로 새 서버가 선택됩니다.

경로 방법의 매개변수는 라우팅 정보를 포함할 수 있는 변수를 지정합니다. 첫 번째 비어 있지 않은 변수는 일치하는 서버를 찾는 데 사용됩니다.

예:

map $cookie_jsessionid $route_cookie {
    ~.+\.(?P<route>\w+)$ $route;
}

map $request_uri $route_uri {
    ~jsessionid=.+\.(?P<route>\w+)$ $route;
}

upstream backend {
    server backend1.example.com route=a;
    server backend2.example.com route=b;

    sticky route $route_cookie $route_uri;
}

여기에서 경로는 요청에 있는 경우 “JSESSIONID” 쿠키에서 가져옵니다. 그렇지 않으면 URI의 경로가 사용됩니다.

learn

학습 방법(1.7.1)이 사용되면 nginx는 업스트림 서버 응답을 분석하고 일반적으로 HTTP 쿠키에 전달되는 서버 시작 세션을 학습합니다.

upstream backend {
   server backend1.example.com:8080;
   server backend2.example.com:8081;

   sticky learn
          create=$upstream_cookie_examplecookie
          lookup=$cookie_examplecookie
          zone=client_sessions:1m;
}

이 예에서 업스트림 서버는 응답에서 쿠키 “EXAMPLECOOKIE”를 설정하여 세션을 생성합니다. 이 쿠키를 포함하는 추가 요청은 동일한 서버로 전달됩니다. 서버가 요청을 처리할 수 없는 경우 클라이언트가 아직 바운딩되지 않은 것처럼 새 서버가 선택됩니다.

매개변수 create 및 lookup은 각각 새 세션이 생성되는 방법과 기존 세션이 검색되는 방법을 나타내는 변수를 지정합니다. 두 매개변수 모두 한 번 이상 지정될 수 있고 이 경우 첫 번째 비어 있지 않은 변수가 사용됩니다.

세션은 공유 메모리 영역에 저장되고 이 영역의 이름 및 크기는 zone 매개변수로 구성됩니다. 하나의 메가바이트 영역은 64비트 플랫폼의 약 4,000개 세션을 저장할 수 있습니다. timeout 매개변수로 지정된 시간 동안 액세스되지 않은 세션은 영역에서 제거됩니다. 기본적으로 시간제한은 10분으로 설정됩니다.

header 매개변수(1.13.1)를 통해 업스트림 서버에서 응답 헤더를 수신한 직후에 세션을 생성할 수 있습니다.

sync 매개변수(1.13.8)는 공유 메모리 영역의 동기화를 활성화합니다.

이 명령은 상업용 구독의 일부로 사용 가능합니다.

Syntax:  sticky_cookie_insert name [expires=time] [domain=domain] [path=path];
Default: —
Context: upstream

이 명령은 버전 1.5.7 이후 사용되지 않습니다. 새 구문을 사용하는 해당하는 고정 명령이 대신 사용됩니다.

sticky cookie name [expires=time] [domain=domain] [path=path];

임베디드 변수

ngx_http_upstream_module 모듈은 다음 포함된 변수를 지원합니다.

$upstream_addr

업스트림 서버의 IP 주소 및 포트 또는 UNIX-도메인 소켓에 대한 경로를 유지합니다. 요청 처리 중에 여러 서버에 연결되면 해당 주소는 쉼표로 구분됩니다. 예: e.g. “192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock”. “X-Accel-Redirect” 또는 error_page에 의해 한 서버 그룹에서 다른 서버 그룹으로 내부 리디렉션이 발생하면 다른 그룹의 서버 주소는 콜론으로 구분됩니다. 예: “192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80”. 서버를 선택할 수 없으면 변수가 서버 그룹의 이름을 유지합니다.

$upstream_bytes_received

업스트림 서버에서 수신된 바이트 수 (1.11.4). 여러 연결의 값은 $upstream_addr 변수의 주소와 같이 쉼표 및 콜론으로 구분됩니다.

$upstream_bytes_sent

업스트림 서버에 전송된 바이트 수(1.15.8). 여러 연결의 값은 $upstream_addr 변수의 주소와 같이 쉼표 및 콜론으로 구분됩니다.

$upstream_cache_status

응답 캐시 액세스 상태를 유지합니다(0.8.3). 상태는 “MISS”, “BYPASS”, “EXPIRED”, “STALE”, “UPDATING”, “REVALIDATED” 또는 “HIT”가 될 수 있습니다.

$upstream_connect_tim

업스트림 서버로 연결을 설정하는 데 보낸 시간을 유지합니다(1.9.1). 시간은 밀리초 해상도로 초 단위로 유지됩니다. SSL의 경우 핸드셰이크에 보낸 시간을 포함합니다. 여러 연결의 시간은 $upstream_addr 변수의 주소와 같이 쉼표 및 콜론으로 구분됩니다.

$upstream_cookie_name

“Set-Cookie” 응답 헤더 필드에서 업스트림 서버가 보낸 지정된 이름의 쿠키(1.7.1). 마지막 서버의 응답에서 온 쿠키만 저장됩니다.

$upstream_header_time

업스트림 서버에서 응답 헤더를 수신하는 데 보낸 시간을 유지합니다(1.7.10). 시간은 밀리초 해상도로 초 단위로 유지됩니다. 여러 응답의 시간은 $upstream_addr 변수의 주소와 같이 쉼표 및 콜론으로 구분됩니다.

$upstream_http_name

서버 응답 헤더 필드를 유지합니다. 예를 들어, “Server” 응답 헤더 필드는 $upstream_http_server 변수를 통해 사용 가능합니다. 헤더 필드 이름을 변수 이름으로 변환하는 규칙은 “$http_” 접두사로 시작하는 변수에 대해 동일합니다. 마지막 서버의 응답에서 온 헤더 필드만 저장됩니다.

$upstream_queue_time

업스트림 대기열에서 요청이 보낸 시간을 유지합니다(1.13.9). 시간은 밀리초 해상도로 초 단위로 유지됩니다. 여러 응답의 시간은 $upstream_addr 변수의 주소와 같이 쉼표 및 콜론으로 구분됩니다.

$upstream_response_length

업스트림 서버에서 얻은 응답의 길이를 유지합니다.(0.7.27). 길이는 바이트 단위로 유지됩니다. 여러 응답의 길이는 $upstream_addr 변수의 주소와 같이 쉼표 및 콜론으로 구분됩니다.

$upstream_response_time

업스트림 서버에서 응답을 수신하는 데 보낸 시간을 유지합니다. 시간은 밀리초 해상도로 초 단위로 유지됩니다. 여러 응답의 시간은 $upstream_addr 변수의 주소와 같이 쉼표 및 콜론으로 구분됩니다.

$upstream_status

업스트림 서버에서 얻은 응답의 상태 코드를 유지합니다. 여러 응답의 상태 코드는 $upstream_addr 변수의 주소와 같이 쉼표 및 콜론으로 구분됩니다. 서버를 선택할 수 없으면 변수가 502(잘못된 게이트웨이) 상태 코드를 유지합니다.

$upstream_trailer_name

업스트림 서버에서 얻은 응답이 끝나는 부분부터 필드를 유지합니다(1.13.10).