ngx_http_upstream_hc_module 

ngx_http_upstream_hc_module 모듈을 사용하면 주변 위치에서 참조된 그룹 내 서버의 상태를 정기적으로 검사할 수 있습니다. 서버 그룹은 공유 메모리에 있어야 합니다.

상태 검사가 실패하면 서버는 정상이 아닌 것으로 간주됩니다. 동일한 서버 그룹에 여러 상태 검사가 정의된 경우, 검사가 한 번이라도 실패하면 해당 서버가 정상이 아닌 것으로 간주됩니다. 클라이언트 요청은 비정상 서버와 “checking” 상태의 서버에는 전달되지 않습니다.

대부분 변수는 상태 검사와 사용 시 빈 값이 됩니다.

이 모듈은 상업용 구독에서 제공합니다.

예제 구성

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 backup1.example.com:8080  backup;
    server backup2.example.com:8080  backup;
}

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

이 구성에서는 nginx가 5초마다 backend 그룹의 각 서버에 “/” 요청을 보냅니다. 연결 오류나 시간 초과가 발생하거나, 프록시된 서버가 2xx, 3xx 외의 다른 상태 코드로 응답한 경우, 상태 검사는 실패하고 서버는 비정상으로 간주됩니다.

상태 검사는 응답 상태 코드, 특정 헤더 필드과 그 값의 유무, 본문 내용을 테스트하도록 구성할 수 있습니다. 테스트는 match 명령을 사용하여 별도로 구성하며, health_check 명령의 match 매개변수에서 참조됩니다.

http {
    server {
    ...
        location / {
            proxy_pass http://backend;
            health_check match=welcome;
        }
    }

    match welcome {
        status 200;
        header Content-Type = text/html;
        body ~ "Welcome to nginx!";
    }
}

이 구성은 상태 검사를 통과하려면 상태 검사에 대한 응답이 성공하고, 상태가 200이어야 하며, 본문에 “Welcome to nginx!”를 포함해야 한다는 것을 나타냅니다.

Directives

Syntax:  health_check [parameters];
Default: —
Context: location

주변 위치에서 참조된 그룹의 서버 상태를 정기적으로 검사하도록 합니다.

지원되는 선택적 매개변수는 다음과 같습니다.

interval=time

2개의 연속적 상태 검사 간격을 설정합니다. 기본값은 5초입니다.

jitter=time

각 상태 검사를 무작위로 지연하는 시간 제한을 설정합니다. 기본값은 지연이 없는 상태입니다.

fails=number

특정 서버의 상태 검사가 연속적으로 실패할 수 있는 횟수를 설정합니다. 이 값이 초과되면 해당 서버는 비정상으로 간주됩니다. 기본값은 1입니다.

passes=number

특정 서버의 상태 검사가 연속적으로 통과되는 횟수를 설정합니다. 이 값을 넘으면 해당 서버는 정상으로 간주됩니다. 기본값은 1입니다.

uri=uri

상태 검사 요청에서 사용한 URI를 정의합니다. 기본값은 “/”입니다.

mandatory [persistent]

첫 상태 검사가 완료되기 전까지 서버의 최초 “checking” 상태를 설정합니다(1.11.7). 클라이언트 요청은 “checking” 상태의 서버에는 전달되지 않습니다. 매개변수를 지정하지 않으면 서버는 처음에 정상으로 간주됩니다.

persistent 매개변수(1.19.7)는 서버가 다시 로드되기 전에 정상으로 간주된 경우 서버의 최초 “up” 상태를 설정합니다.

match=name

match 블록을 지정하여, 상태 검사를 통과하기 위해 응답이 통과해야 할 테스트를 구성합니다. 기본적으로 응답은 상태 코드가 2xx 또는 3xx여야 합니다.

port=number

상태 검사를 위해 서버에 연결할 때 사용할 포트를 정의합니다(1.9.7). 기본적으로 서버 포트와 동일합니다.

type=grpc [grpc_service=name] [grpc_status=code]

gRPC 서버 또는 선택적 grpc_service 매개변수로 지정된 특정 gRPC 서버의 정기적 상태 검사를 활성화합니다(1.19.5). 서버가 gRPC 상태 검사 프로토콜을 지원하지 않는 경우, 선택적 grpc_status 매개변수를 사용하여 0이 아닌 gRPC 상태(예: 상태 코드 “12” / “UNIMPLEMENTED”)를 지정합니다. 이는 정상으로 간주됩니다.

health_check mandatory type=grpc grpc_status=12;

type=grpc 매개변수를 반드시 지정해야 하고, 그 이후에 다른 명령 매개변수인 grpc_service와 grpc_status는 type=grpc를 따라야 합니다. 이 매개변수는 uri 또는 match 매개변수와 호환되지 않습니다.

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

상태 검사 요청의 응답을 확인하기 위해 사용하는 이름이 지정된 테스트 세트를 정의합니다.

응답에서 테스트할 수 있는 항목은 다음과 같습니다.

status 200;

상태는 200

status ! 500;

상태가 500이 아닙니다.

status 200 204;

상태는 200 또는 204입니다.

status ! 301 302;

상태가 301도 302도 아닙니다.

status 200-399;

상태는 200에서 399 사이입니다.

status ! 400-599;

상태가 400에서 599 사이가 아닙니다.

status 301-303 307;

상태는 301, 302, 303 또는 307입니다.

header Content-Type = text/html;

헤더에 “Content-Type”이 포함되었고 값이 text/html인지 여부

header Content-Type != text/html;

헤더에 “Content-Type”이 포함되었고 text/html 외의 다른 값인지 여부

header Connection ~ close;

헤더에 “Connection”이 포함되었고 값이 정규식 close와 일치하는지 여부

header Connection !~ close;

헤더에 “Connection”이 포함되었고 값이 정규식 close와 일치하지 않는지 여부

header Host;

헤더에 “Host”가 포함되었는지 여부

header ! X-Accel-Redirect;

헤더에 “X-Accel-Redirect”가 없는지 여부

body ~ “Welcome to nginx!”;

본문이 정규식 “Welcome to nginx!”와 일치하는지 여부

body !~ “Welcome to nginx!”;

본문이 정규식 “Welcome to nginx!”와 일치하지 않는지 여부

require$variable...;

모든 지정된 값이 비어 있지 않고 “0”이 아닌지 여부(1.15.9).

여러 테스트를 지정한 경우, 모든 테스트에서 일치하는 경우에만 응답이 일치하게 됩니다.

응답 본문의 처음 256k만 검사합니다.

예:

# status is 200, content type is "text/html",
# and body contains "Welcome to nginx!"
match welcome {
    status 200;
    header Content-Type = text/html;
    body ~ "Welcome to nginx!";
}
# status is not one of 301, 302, 303, or 307, and header does not have "Refresh:"
match not_redirect {
    status ! 301-303 307;
    header ! Refresh;
}
# status ok and not in maintenance mode
match server_ok {
    status 200-399;
    body !~ "maintenance mode";
}
# status is 200 or 204
map $upstream_status $good_status {
    200 1;
    204 1;
}

match server_ok {
    require $good_status;
}