モジュール ngx_http_grpc_module

ngx_http_grpc_module モジュールは、gRPC サーバー (1.13.10) へのリクエストの転送を可能にします。このモジュールは、ngx_http_v2_module モジュールを必要とします。

server {
    listen 9000;

    http2 on;

    location / {
        grpc_pass 127.0.0.1:9000;
    }
}

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

transparent パラメータは、gRPC サーバーへの発信接続を、ローカル以外の IP アドレス、たとえばクライアントの実際の IP アドレスから発信することを可能にします。

grpc_bind $remote_addr transparent;

このパラメータを動作させるには、通常、nginx ワーカープロセスをスーパーユーザー権限で実行する必要があります。Linux では、transparent パラメータが指定されている場合、ワーカープロセスはマスタープロセスから CAP_NET_RAW ケーパビリティを継承するため、これは必要ありません。また、gRPC サーバーからのネットワークトラフィックをインターセプトするようにカーネルルーティングテーブルを設定する必要があります。

grpc_buffer_size 4k|8k;

gRPC サーバーから受信したレスポンスの読み取りに使用するバッファのサイズを設定します。レスポンスは、受信されるとすぐにクライアントに同期的に渡されます。

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 への内部リダイレクトを実行します。
• "X-Accel-Charset" は、レスポンスの目的の文字セットを設定します。

grpc_intercept_errors off;

300 以上のコードを持つ gRPC サーバーのレスポンスをクライアントに渡すか、インターセプトして error_page ディレクティブで処理するために nginx にリダイレクトするかを決定します。

grpc_next_upstream error timeout;

リクエストを次のサーバーに渡す必要がある場合を指定します。

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

通常、冪等でないメソッド (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;

ドメイン名が複数のアドレスに解決される場合、それらはすべてラウンドロビン方式で使用されます。さらに、アドレスはサーバーグループとして指定できます。

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

そうでなければ無効になっているヘッダーフィールドを gRPC サーバーからクライアントに渡すことを許可します。

grpc_read_timeout 60s;

gRPC サーバーからのレスポンスを読み取るためのタイムアウトを定義します。タイムアウトは、レスポンス全体の送信ではなく、2 つの連続した読み取り操作の間にのみ設定されます。 gRPC サーバーがこの時間内に何も送信しない場合、接続は閉じられます。

grpc_send_timeout 60s;

gRPC サーバーにリクエストを送信するためのタイムアウトを設定します。タイムアウトは、リクエスト全体の送信ではなく、2 つの連続した書き込み操作の間にのみ設定されます。 gRPC サーバーがこの時間内に何も受信しない場合、接続は閉じられます。

grpc_set_header Content-Length $content_length;

gRPC サーバーに渡されるリクエストヘッダーのフィールドを再定義または追加することを可能にします。 値には、テキスト、変数、およびそれらの組み合わせを含めることができます。これらのディレクティブは、現在のレベルで grpc_set_header ディレクティブが定義されていない場合にのみ、前の設定レベルから継承されます。

ヘッダーフィールドの値が空の文字列の場合、このフィールドは gRPC サーバーに渡されません。

grpc_set_header Accept-Encoding "";

grpc_socket_keepalive off;

gRPC サーバーへの発信接続の「TCP キープアライブ」動作を構成します。デフォルトでは、ソケットにはオペレーティングシステムの設定が有効です。ディレクティブが "on" に設定されている場合、ソケットの SO_KEEPALIVE ソケットオプションがオンになります。

gRPC SSL サーバーへの認証に使用される PEM 形式の証明書を含むファイルを指定します。

バージョン 1.21.0 以降、ファイル名に変数を使用できます。

gRPC SSL サーバーへの認証に使用される PEM 形式の秘密鍵を含むファイルを指定します。

ファイルの代わりに値 engine:名前:ID を指定できます。これは、指定された ID の秘密鍵を OpenSSL エンジン 名前 からロードします。

バージョン 1.21.0 以降、ファイル名に変数を使用できます。

grpc_ssl_ciphers DEFAULT;

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

完全なリストは、"openssl ciphers" コマンドを使用して表示できます。

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

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

同じレベルで複数の grpc_ssl_conf_command ディレクティブを指定できます。これらのディレクティブは、現在のレベルで grpc_ssl_conf_command ディレクティブが定義されていない場合にのみ、前の設定レベルから継承されます。

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

gRPC SSL サーバーの証明書を検証するために使用される、PEM 形式の失効した証明書 (CRL) を含むファイルを指定します。

gRPC SSL サーバー接続 SSL 鍵のログ記録を有効にし、鍵ログファイルへのパスを指定します。鍵は、Wireshark と互換性のある SSLKEYLOGFILE 形式でログに記録されます。

このディレクティブは、商用サブスクリプションの一部として利用できます。

grpc_ssl_name host from grpc_pass;

gRPC SSL サーバーの証明書を検証するために使用されるサーバー名と、gRPC SSL サーバーとの接続を確立するときにSNI 経由で渡されるサーバー名を上書きすることを可能にします。

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

秘密鍵(secret keys)のパスフレーズを指定したfileを指定します。各パスフレーズは別々の行に指定します。キーの読み込み時にパスフレーズは順番に試行されます。

grpc_ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;

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

TLSv1.3 パラメータは、1.23.4 以降デフォルトで使用されます。

grpc_ssl_server_name off;

gRPC SSL サーバーとの接続確立時に、TLS Server Name Indication 拡張 (SNI, RFC 6066) を介したサーバー名の受け渡しを有効または無効にします。

grpc_ssl_session_reuse on;

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

gRPC SSL サーバーの証明書の検証に使用する、信頼できる CA 証明書が PEM 形式で記述されたfileを指定します。

grpc_ssl_verify off;

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

grpc_ssl_verify_depth 1;

gRPC SSL サーバー証明書チェーンの検証深度を設定します。