ngx_http_grpc_module

ngx_http_grpc_module 모듈을 사용하여 gRPC 서버로 요청을 전달할 수 있습니다(1.13.10). 이 모듈은 ngx_http_v2_module 모듈이 필요합니다.

예제 구성

server {
    listen 9000 http2;
    
    location / {
        grpc_pass 127.0.0.1:9000;
    }
}

Directives

Syntax:  grpc_bind address [transparent ] | off;
Default: —
Context: http, server, location

선택적 포트를 통해 지정된 로컬 IP 주소에서 gRPC 서버로 나가는 연결을 설정합니다. 매개변수 값은 변수를 포함할 수 있습니다. 특수 값 off는 이전 구성 수준에서 상속한 grpc_bind 명령의 효과를 상쇄하여, 시스템에서 로컬 IP 주소와 포트를 자동으로 할당하도록 합니다.

transparent 매개변수를 사용하면 외부 IP 주소에서 gRPC 서버로 나가는 연결을 허용할 수 있습니다. 예를 들어, 클라이언트의 실제 IP 주소를 사용할 수 있습니다.

grpc_bind $remote_addr transparent;

이 매개변수가 작동하려면 일반적으로 superuser 권한이 있는 nginx 작업자 프로세스를 실행해야 합니다. Linux에서는 필수가 아닙니다. transparent 매개변수를 지정한 경우, 작업자 프로세스가 마스터 프로세스에서 CAP_NET_RAW 기능을 상속하기 때문입니다. 또한, 커널 라우팅 테이블을 구성하여 gRPC 서버의 네트워크 트래픽을 가로채야 합니다.

Syntax:  grpc_buffer_size size;
Default: grpc_buffer_size 4k|8k;
Context: http, server, location

gRPC 서버에서 수신된 응답을 읽는 데 사용할 버퍼의 size를 설정합니다. 응답은 수신되는 즉시, 동기식으로 클라이언트에 전달됩니다.

Syntax:  grpc_connect_timeout time;
Default: grpc_connect_timeout 60s;
Context: http, server, location

gRPC 서버와의 연결을 설정하는 데 적용할 제한 시간을 정의합니다. 참고로 이 제한 시간은 일반적으로 75초를 넘지 않습니다.

Syntax:  grpc_hide_header field;
Default: —
Context: http, server, location

기본적으로 nginx는 gRPC 서버 응답에서 클라이언트로 “Date”, “Server” 및 “X-Accel-…” 헤더 필드를 전달하지 않습니다. grpc_hide_header 명령은 전달되지 않는 추가 필드를 설정합니다. 반면, 필드 전달을 허용해야 하는 경우 grpc_pass_header 명령을 사용할 수 있습니다.

Syntax:  grpc_ignore_headers field ...;
Default: —
Context: http, server, location

gRPC 서버에서 특정 응답 헤더 필드를 처리하는 작업을 비활성화합니다. 다음의 필드가 무시됩니다. “X-Accel-Redirect” 및 “X-Accel-Charset”.

이 헤더 필드의 처리를 비활성화하지 않으면, 다음과 같은 효과가 발생합니다.

• “X-Accel-Redirect”가 지정된 URI에 내부 리디렉션을 실행합니다.
• “X-Accel-Charset”가 응답의 적절한 문자 세트를 설정합니다.

Syntax:  grpc_intercept_errors on | off;
Default: grpc_intercept_errors off;
Context: http, server, location

300 이상의 코드가 포함된 gRPC 서버 응답은 클라이언트로 전달하거나, 이를 해석하여 nginx로 리디렉션하고 error_page 명령을 통해 처리해야 합니다.

Syntax:  grpc_next_upstream error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | 
         http_403 | http_404 | http_429 | non_idempotent | off ...;
Default: grpc_next_upstream error timeout;
Context: http, server, location

요청을 다음 서버로 전달해야 하는 경우를 지정합니다.

error

서버와의 연결을 설정하는 동안 오류가 발생하거나, 요청을 다음 서버로 전달하거나, 응답 헤더를 읽는 경우

timeout

서버와 연결을 설정하거나 요청을 전달하거나 응답 헤더를 읽는 동안 시간 초과가 발생했습니다.

invalid_header

서버가 비어 있거나 잘못된 응답을 반환

http_500

서버가 코드 500으로 응답을 반환

http_502

서버가 코드 502로 응답을 반환

http_503

서버가 코드 503으로 응답을 반환

http_504

서버가 코드 504로 응답을 반환

http_403

서버가 코드 403으로 응답을 반환

http_404

서버가 코드 404로 응답을 반환

http_429

서버가 코드 429로 응답을 반환

non_idempotent

일반적으로 non-idempotent 메서드가 포함된 요청(POST, LOCK, PATCH)은 업스트림 서버에 전송되었다면 다음 서버로 전달되지 않습니다. 이 옵션을 활성화하면 이 요청을 재시도하는 것을 명시적으로 허용합니다.

off

다음 서버로의 요청 전달을 비활성화하는 경우

단, 아직 클라이언트에 아무것도 전송하지 않은 상태여야 요청을 다음 서버로 전달할 수 있습니다. 즉, 응답을 전송하는 동안 오류가 발생하거나 시간이 초과되면 이를 수정할 수 없습니다.

또한, 이 명령은 서버 연결 시도 실패를 정의합니다. error, timeout 및 invalid_header는 언제나 통신 연결 실패로 간주됩니다. 이는 명령에서 지정되지 않은 경우에도 해당합니다. http_500, http_502, http_503, http_504 및 http_429는 명령에서 지정되지 않은 경우에만 통신 연결 실패로 간주됩니다. http_403 및 http_404는 통신 실패로 간주하지 않습니다.

다음 서버로 요청을 전달하는 것은 시도 횟수와 시간으로 제한할 수 있습니다.

Syntax:  grpc_next_upstream_timeout time;
Default: grpc_next_upstream_timeout 0;
Context: http, server, location

다음 서버로 요청을 전달할 수 있는 시간을 제한합니다 0 값은 이 제한을 비활성화합니다.

Syntax:  grpc_next_upstream_tries number;
Default: grpc_next_upstream_tries 0;
Context: http, server, location

다음 서버로 요청 전달을 시도할 수 있는 횟수를 제한합니다. 0 값은 이 제한을 비활성화합니다.

Syntax:  grpc_pass address;
Default: —
Context: location, if in location

gRPC 서버 주소를 설정합니다. 이 주소는 도메인 이름이나 IP 주소와 포트로 지정할 수 있습니다.

grpc_pass localhost:9000;

또는, UNIX 도메인 소켓 경로도 가능합니다.

grpc_pass unix:/tmp/grpc.socket;

또는, “grpc://” 체계를 사용할 수 있습니다.

grpc_pass grpc://127.0.0.1:9000;

SSL 대신 gRPC를 사용하려면 “grpcs://” 체계를 사용해야 합니다.

grpc_pass grpcs://127.0.0.1:443;

도메인 이름이 여러 주소로 변환되는 경우, 모두 순환 방식으로 사용됩니다. 또한, 주소는 서버 그룹으로 지정할 수 있습니다.

매개변수 값은 변수를 포함할 수 있습니다(1.17.8). 이 경우, 주소를 도메인 이름으로 지정하면 설명된 서버 그룹에서 검색합니다. 이를 찾지 못할 경우 리졸버를 사용해서 확인합니다.

Syntax:  grpc_pass_header field;
Default: —
Context: http, server, location

다른 경우에는 비활성화된 헤더 필드를 gRPC 서버에서 클라이언트로 전달하도록 허용합니다.

Syntax:  grpc_read_timeout time;
Default: grpc_read_timeout 60s;
Context: http, server, location

gRPC 서버에서 응답을 읽는 시간제한을 정의합니다. 시간제한은 전체 응답 전송이 아니라 두 개의 연속적인 읽기 작업 사이에만 설정됩니다. gRPC 서버가 이 시간 내에 아무것도 전송하지 않으면 연결이 종료됩니다.

Syntax:  grpc_send_timeout time;
Default: grpc_send_timeout 60s;
Context: http, server, location

gRPC 서버로 요청을 전송하는 시간제한을 설정합니다. 시간제한은 전체 요청 전송이 아니라 두 개의 연속적인 쓰기 작업 사이에만 설정됩니다. gRPC 서버가 이 시간 내에 아무것도 전송하지 않으면 연결이 종료됩니다.

Syntax:  grpc_set_header field value;
Default: grpc_set_header Content-Length $content_length;
Context: http, server, location

gRPC 서버에 전달되는 요청 헤더의 필드를 다시 정의하거나 필드를 첨부하도록 허용합니다. value는 텍스트, 변수 및 그 두 가지의 조합을 포함할 수 있습니다. 이 명령은 현재 수준에서 정의된 grpc_set_header 명령이 없을 경우에만 이전 구성 수준에서 상속합니다.

헤더 필드의 값이 빈 문자열이라면 이 필드는 gRPC 서버로 전달되지 않습니다.

grpc_set_header Accept-Encoding "";

Syntax:  grpc_socket_keepalive on | off;
Default: grpc_socket_keepalive off;
Context: http, server, location
This directive appeared in version 1.15.6.

gRPC 내보내는 연결에 대해 “TCP keepalive” 동작을 구성합니다. 기본적으로 소켓에는 운영 체제 설정이 적용됩니다. 명령에서 “on” 값을 설정하면 해당 소켓에 대해 SO_KEEPALIVE 옵션이 활성화됩니다.

Syntax:  grpc_ssl_certificate file;
Default: —
Context: http, server, location

gRPC SSL 서버 인증에 사용하기 위한 PEM 형식의 인증서가 포함된 file을 지정합니다.

1.21.0버전 이후로 file 이름에 변수를 사용할 수 있습니다.

Syntax:  grpc_ssl_certificate_key file;
Default: —
Context: http, server, location

gRPC SSL 서버 인증에 사용하기 위한 PEM 형식의 시크릿 키가 포함된 file을 지정합니다.

file 대신 engine:name:id 값을 지정할 수 있는데, 이는 OpenSSL 엔진 name에서 지정된 id가 포함된 시크릿 키를 로드합니다.

1.21.0버전 이후로 file 이름에 변수를 사용할 수 있습니다.

Syntax:  grpc_ssl_ciphers ciphers;
Default: grpc_ssl_ciphers DEFAULT;
Context: http, server, location

gRPC SSL 서버에 대한 요청에 활성화된 암호를 지정합니다. 이 암호는 OpenSSL 라이브러리에서 이해하는 형식으로 지정합니다.

전체 목록은 “openssl ciphers” 명령을 사용하여 확인할 수 있습니다.

Syntax:  grpc_ssl_conf_command command;
Default: —
Context: http, server, location
This directive appeared in version 1.19.4.

gRPC SSL 서버로 연결을 설정할 때 임의의 OpenSSL 구성 명령을 설정합니다.

이 명령은 OpenSSL 1.0.2 이상을 사용할 때 지원됩니다.

동일한 수준에서 여러 grpc_ssl_conf_command 명령을 지정할 수 있습니다. 이러한 명령은 현재 수준에서 grpc_ssl_conf_command 명령이 정의되지 않은 경우에만 이전 구성에서 상속합니다.

OpenSSL을 직접 구성하면 예상치 못한 동작이 발생할 수 있습니다.

Syntax:  grpc_ssl_crl file;
Default: —
Context: http, server, location

gRPC SSL 서버의 인증서를 인증하는 데 사용한 취소된 인증서(CRL)를 PEM 형식으로 포함한 file을 지정합니다.

Syntax:  grpc_ssl_name name;
Default: grpc_ssl_name host from grpc_pass;
Context: http, server, location

gRPC SSL 서버 인증서를 인증하는 데 사용하고 gRPC SSL 서버와의 연결을 설정할 때 SNI를 통해 전달되는 서버 이름을 재정의할 수 있습니다.

기본적으로 grpc_pass 주소의 호스트 부분을 사용합니다.

Syntax:  grpc_ssl_password_file file;
Default: —
Context: http, server, location

시크릿 키에 대한 패스프레이즈가 포함된 file을 지정합니다. 각 패스프레이즈는 별도의 행으로 지정합니다. 키를 로딩할 때 순서대로 패스프레이즈를 시도합니다.

Syntax:  grpc_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: grpc_ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
Context: http, server, location

gRPC SSL 서버에 대한 요청에 지정된 프로토콜을 활성화합니다.

Syntax:  grpc_ssl_server_name on | off;
Default: grpc_ssl_server_name off;
Context: http, server, location

gRPC SSL 서버와 연결을 설정할 때 TLS Server Name Indication 확장 프로그램(SNI, RFC 6066)을 통해 서버 이름을 전달하도록 활성화하거나 비활성화합니다.

Syntax:  grpc_ssl_session_reuse on | off;
Default: grpc_ssl_session_reuse on;
Context: http, server, location

gRPC 서버와 작업 시 SSL 세션을 다시 사용할 수 있는지 결정합니다. 로그에 “SSL3_GET_FINISHED:digest check failed” 오류가 나타날 경우 세션 재사용을 비활성화해보세요.

Syntax:  grpc_ssl_trusted_certificate file;
Default: —
Context: http, server, location

gRPC SSL 서버의 인증서를 인증하는 데 사용된 신뢰할 수 있는 CA 인증서를 PEM 형식으로 포함한 file을 지정합니다.

Syntax:  grpc_ssl_verify on | off;
Default: grpc_ssl_verify off;
Context: http, server, location

gRPC SSL 서버 인증서의 인증을 활성화하거나 비활성화합니다.

Syntax:  grpc_ssl_verify_depth number;
Default: grpc_ssl_verify_depth 1;
Context: http, server, location

gRPC SSL 서버 인증서 체인에서 인증 깊이를 설정합니다.