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;
    }
}

gRPCサーバへ向かって出て行く接続が、指定したローカルのIPアドレスとオプションのポートから始まるようにします。パラメータの値には変数を含めることができます。特別な値off は上の設定レベルのgrpc_bindディレクティブの継承の影響をキャンセルします。これによりシステムはローカルIPアドレスとポートに自動割り当てすることができます。

transparent パラメータはgRPCサーバへ向かって出ていく接続がローカルIPアドレスでは無いようにします。例えば、クライアントの実際のIPアドレス:

grpc_bind $remote_addr transparent;

このパラメータが動作するためには、通常nginxのワーカープロセスを superuser 権限を使って実行する必要があります。Linux上では、transparentパラメータが指定された場合はワーカープロセスはマスタープロセスからCAP_NET_RAW機能を継承するため、必要ではありません。gRPCサーバからのネットワーク通信を捕らえるためにカーネルのルーティングテーブルを設定する必要もあります。

grpc_buffer_size 4k|8k;

gRPCサーバから応答の最初の部分を読み込むために使われるバッファのsizeを設定します。応答は受け取り次第クライアントに同期して渡されます。

grpc_connect_timeout 60s;

gRPCサーバとの接続の確立のタイムアウトを定義します。このタイムアウトは通常75秒以上にならないことに注意が必要です。

デフォルトでは、nginxはgRPCサーバの応答からクライアントへの"Date", "Server"と"X-Accel-..."ヘッダフィールドを通しません。grpc_hide_headerディレクティブは、更に通過されないフィールドを設定します。逆に、フィールドの通過が必要な場合は、grpc_pass_headerディレクティブを使うことができます。

gRPCサーバからの特定の応答ヘッダフィールドの処理を無効にします。以下のフィールドは無視することができます: “X-Accel-Redirect” と “X-Accel-Charset”。

無効にされない場合、これらのヘッダフィールドの処理には次の影響があります:

• "X-Accel-Redirect" は特定のURIに対してinternal redirect を実行します。
• "X-Accel-Charset"は望ましい応答のcharsetを設定します。

grpc_intercept_errors off;

gRPCサーバの300以上の応答コードが、クライアントへ渡されるべきかまたは遮断されるべきか、そしてerror_page ディレクティブで処理するためにnginxにリダイレクトすべきかを決定します。

grpc_next_upstream error timeout;

どの場合にリクエストが次のサーバに渡されるべきかを指定します:

エラー

サーバへの接続の確立時、あるいはサーバにリクエストを渡す時、あるいは応答ヘッダーを読み込む時にエラーが起きた場合;

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

もしリクエストがupstream サーバに送信された場合は、通常 non-idempotent メソッド (POST, LOCK, PATCH) のリクエストは次のサーバに渡されません; このオプションを有効にすると明示的にそのようなリクエストの再試行を行うことができます。

off

リクエストを次のサーバに渡すのを無効化する。

まだクライアントに何も送っていない時にのみ、リクエストを次のサーバに渡す事ができるということを、心に留めておいてください。応答の転送中にエラーまたはタイムアウトが起きると、この修復は不可能です。

このディレクティブは何をサーバとの通信の失敗と見なすかについても定義します。error, timeout と invalid_header は、ディレクティブの中で指定されていなくても常に失敗と見なされます。http_500, http_502, http_503, http_504 と http_429 がディレクティブの中で指定されている時のみ、失敗と見なされます。http_403 と http_404 の場合は、失敗と見なされません。

次のサーバへリクエストを渡すことを 試行回数 および 時間で制限することができます。

grpc_next_upstream_timeout 0;

次のサーバに渡すことができるリクエストの間隔を制限します。0 の値はこの制限を無効にします。

grpc_next_upstream_tries 0;

次のサーバにリクエストが渡すときに、可能な試行回数を制限します。0 の値はこの制限を無効にします。

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;

ドメイン名が幾つかのアドレスに解決される場合は、ラウンドロビンの形式でそれら全てが使われるでしょう。更に、server groupとしてアドレスを指定することができます。

パラメータの値には変数を含めることができます (1.17.8)。この場合、アドレスがドメイン名として指定されない場合、名前はサーバ グループと記述された中で検索され、もし見つからない場合はレゾルバを使って決定されます。

gRPCサーバからクライアントへotherwise disabledヘッダフィールドを渡すことを許可します。

grpc_read_timeout 60s;

gRPCサーバから応答を読み込む時のタイムアウトを定義します。タイムアウトは二つの連続する読み込み操作の間に設定され、応答全体の転送のためのものではありません。この時間内にgRPCサーバが何も転送しなかった場合、接続が閉じられます。

grpc_send_timeout 60s;

gRPCサーバへのリクエストの転送のタイムアウトを設定します。タイムアウトは二つの連続する書き込み操作の間に設定され、リクエスト全体の転送のためのものではありません。この時間内にgRPCサーバが何も受け取らなかった場合、接続が閉じられます。

grpc_set_header Content-Length $content_length;

gRPCサーバへ渡されるリクエストヘッダのフィールドの再定義あるいは追加が可能です。valueにはテキスト、変数、それらの組み合わせを含めることができます。現在のレベルにgrpc_set_headerディレクティブが無い場合に限り、これらのディレクティブは上の設定レベルから引き継がれます。

ヘッダーフィールドの値が空文字であれば、このフィールドはgRPCサーバに渡されないでしょう:

grpc_set_header Accept-Encoding "";

grpc_socket_keepalive off;

gRPCサーバへの送信接続の“TCP keepalive”の動作を設定します。デフォルトでは、オペレーティングシステムの設定はソケットに対して有効です。ディレクティブが値“on”に設定されている場合、ソケットのSO_KEEPALIVEソケットオプションがオンになります。

gRPC SSLサーバに対して認証に使われるPEM形式の証明書の ファイルを指定します。

バージョン 1.21.0以降、file名に変数を使うことができます。

gRPC SSLサーバに対して認証に使われるPEM形式の秘密鍵の ファイルを指定します。

engine:name:id の値は file の代わりに指定することができ、 特定のOpenSSLのnameの特定の id と一緒に秘密鍵を取り付けます。

バージョン 1.21.0以降、file名に変数を使うことができます。

grpc_ssl_ciphers DEFAULT;

gRPC SSLサーバへのリクエストで有効なcipherを指定します。cipherはOpenSSLライブラリで理解される形式で指定されます。

全てのリストは"openssl ciphers"コマンドを使ってみることができます。

gRPC SSL サーバとの接続を確立する時に、任意のOpenSSL設定コマンドを設定します。

このディレクティブはOpenSSL 1.0.2以降を使う場合にサポートされます。

いくつかのgrpc_ssl_conf_commandディレクティブは同じレベルに設定できます。現在のレベルにgrpc_ssl_conf_commandディレクティブが無い場合に限り、これらのディレクティブは上の設定レベルから引き継がれます。

OpenSSLを直接設定すると、予期しない動作が発生する可能性があることに注意してください。

gRPC SSLサーバの証明書をverifyするために使われるPEM形式の無効な証明書(CRL)のfileを指定します。

grpc_ssl_name host from grpc_pass;

gRPC SSLサーバの証明書をverifyするために使われるサーバ名を上書きし、gRPC SSLサーバと接続を確立する時にpassed through SNIできます。

デフォルトでは、grpc_passのホスト部分が使われます。

secret keysのためのそれぞれのパスフレーズが一行に指定されているfileを指定します。パスフレーズはキーがロードされる時に順番に試されます。

grpc_ssl_protocols TLSv1 TLSv1.1 TLSv1.2;

gRPC SSLサーバへ指定されたプロトコルのリクエストを有効にします。

grpc_ssl_server_name off;

gRPC SSLサーバと接続を確立する時に、TLS Server Name Indication extension (SNI, RFC 6066) を使ってサーバ名を渡すことを有効または無効にします。

grpc_ssl_session_reuse on;

gRPCサーバと動作する時に、SSLセッションを再利用するかどうかを決定します。ログに"SSL3_GET_FINISHED:digest check failed"が現れる場合は、セッションの再利用を無効にしてみてください。

gRPC SSLサーバの証明書をverifyするために使われるPEM形式の信頼されたCA証明書のfileを指定します。

grpc_ssl_verify off;

gRPC SSLサーバの証明書の検証を有効または無効にします。

grpc_ssl_verify_depth 1;

gRPC SSLサーバの連鎖証明書の検証の深さを設定します。