The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
Back to Guides
このページを編集

gRPC リファレンスガイド

Quarkus で gRPC を使用する

gRPC サービスを実装または使用する必要がある場合は、 quarkus-grpc エクステンションが必要です。 このエクステンションは、両側を処理します。

Maven の使用

gRPC を有効にするには、プロジェクトに次の依存関係を追加します。

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-grpc</artifactId>
</dependency>

quarkus:generate-code ゴールは、quarkus パッケージングを使用する場合、Quarkus Maven プラグインのデフォルトライフサイクル中にデフォルトで実行され、コード生成を処理します。

Gradle の使用

Gradle の場合、プロジェクトに次の依存関係を追加します。

implementation 'io.quarkus:quarkus-grpc'

gRPC サーバーの選択

Quarkus は、gRPC サーバーの 2 つの実装である gRPC Java (Netty ベース) と Vert.x を提供します。 どちらも TLS をサポートしています。

Vert.x ベースのサーバーの利点の 1 つは、単一のサーバーを使用して HTTP リクエストと gRPC リクエストを処理できることです。これは、REST エンドポイントと gRPC エンドポイントの両方を同じポートで公開する場合に便利です。ただし、gRPC Java サーバーでは不可能です (別のサーバーを使用)。

gRPC サーバーの実装を選択するには、 application.properties ファイルで quarkus.grpc.server.use-separate-server プロパティーを設定します。

# Use the Vert.x based server
quarkus.grpc.server.use-separate-server=false

より柔軟性が高く、Quarkus エコシステムとの統合性も優れているため、Vert.x ベースの gRPC サーバーの使用が推奨されます。

両方のサーバーを同時に使用することはできません。

大容量メッセージのパフォーマンスチューニング

大容量の gRPC メッセージを扱う場合、最適なスループットを実現するために HTTP/2 フロー制御ウィンドウサイズを調整する必要がある場合があります。

統合サーバーモード (Vert.x ベース)

統合サーバーモード (quarkus.grpc.server.use-separate-server=false) を使用する場合、HTTP/2 接続ウィンドウサイズを設定できます。

quarkus.grpc.server.use-separate-server=false
quarkus.http.http2-connection-window-size=104857600 # 100MB

quarkus.http.http2-connection-window-size プロパティーは、HTTP/2 接続ウィンドウサイズをバイト単位で設定します。デフォルト値は -1 であり、これは初期ウィンドウサイズ設定 (通常 64KB) を再利用します。大容量メッセージの場合、この値を増やすとスループットが大幅に向上する可能性があります。

独立サーバーモード (gRPC Java/Netty ベース)

独立サーバーモード (quarkus.grpc.server.use-separate-server=true) を使用する場合、ServerBuilderCustomizer を使用してフロー制御ウィンドウを設定できます。

import io.grpc.netty.NettyServerBuilder;
import io.quarkus.grpc.api.ServerBuilderCustomizer;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class GrpcServerCustomizer implements ServerBuilderCustomizer<NettyServerBuilder> {
    @Override
    public void customize(NettyServerBuilder builder) {
        builder.initialFlowControlWindow(100 * 1024 * 1024); // 100MB
    }
}
独立サーバーモードは、Netty 固有の設定をより直接的に制御できますが、gRPC トラフィック用に専用ポートが必要です。

ランダムポートでの待ち受け

ポートを指定したくない場合、Vert.x を使用している場合 (quarkus.grpc.server.use-separate-server=false) は quarkus.http.port=0 と quarkus.http.test-port=0 を、gRPC サーバーを使用している場合は quarkus.grpc.server.port=0 と quarkus.grpc.server.test-port=0 を設定できます。OS によってランダムな空きポートが選択され、コンソールにログメッセージが出力されます。

実際のポートを取得するには、アプリケーションコードに CDI Bean として注入できる io.quarkus.grpc.runtime.GrpcServer API を使用します。

import jakarta.inject.Singleton;
import io.quarkus.grpc.runtime.GrpcServer;

@Singleton
public class MyService  {
    @Inject
    GrpcServer grpcServer;

    public void connectToServer() {
        int port = grpcServer.getPort();
    }
}

または、フィールドまたはテストパラメーターとして、あらゆる種類のテストに注入できます。

import org.junit.jupiter.api.Test;
import io.quarkus.test.junit.QuarkusTest;
import io.quarkus.grpc.runtime.GrpcServer;

@QuarkusTest
class GrpcServerTest {
    GrpcServer grpcServer;

    @Test
    void connectToServer(GrpcServer grpcServer) {
        int port = grpcServer.getPort();
    }
}

gRPC クライアントの選択

サーバーに関しては、Quarkus には gRPC クライアント向けに gRPC Java と Vert.x という 2 つの選択肢があります。 サーバーとは異なり、クライアントごとにトランスポートを選択できます。

quarkus.grpc.clients.hello.use-quarkus-grpc-client=true # Use client using the Vert.x based transport

デフォルトではありませんが、より柔軟性が高く、Quarkus エコシステムとの統合性が高い、Vert.x ベースのクライアントを使用することが推奨されます。 stub は gRPC フレームワークによって生成されるため、使用できる stub は変更されません。 ただし、クライアントがサーバーと通信する方法は変わります。

クライアント側フロー制御ウィンドウ

大容量メッセージを扱う場合、gRPC クライアントのフロー制御ウィンドウを設定できます。

quarkus.grpc.clients.hello.flow-control-window=104857600 # 100MB

デフォルトのフロー制御ウィンドウは 1MB です。この値を増やすと、サーバーから大容量メッセージを受信する際のスループットが向上する可能性があります。

gRPC サービス向けの TLS の設定

Vert.x ベースのサーバーの場合

Vert.x ベースのサーバーを使用する場合は、 application.properties ファイルで次のプロパティーを設定することで TLS を設定できます。

quarkus.grpc.server.use-separate-server=false
quarkus.grpc.server.plain-text=false

quarkus.tls.key-store.p12.path=grpc-tls-keystore.p12
quarkus.tls.key-store.p12.password=*****

quarkus.http.insecure-requests=disabled

以前の設定では、一元化された TLS 設定 が使用されています。 これが推奨されるアプローチです。

次のプロパティーを使用してサーバーを直接設定することもできます。

quarkus.grpc.server.use-separate-server=false

quarkus.grpc.server.plain-text=false
quarkus.http.ssl.certificate.key-store-file=target/certs/grpc-tls-keystore.p12
quarkus.http.ssl.certificate.key-store-password=*****
quarkus.http.insecure-requests=disabled

JKS または P12 を使用する場合、 key-store-file と key-store-password を使用してキーストアファイルとそのパスワードを設定できます。PEM の場合は、 certificate プロパティーと key プロパティーを使用します。

quarkus.grpc.server.use-separate-server=false

quarkus.grpc.server.plain-text=false
quarkus.http.ssl.certificate.files=target/certs/grpc-tls.crt
quarkus.http.ssl.certificate.key-files=target/certs/grpc-tls.key
quarkus.http.insecure-requests=disabled
quarkus.http.insecure-requests プロパティーは、安全ではないリクエストを無効にするために使用されます。
TLS が有効な場合、HTTP トラフィックと gRPC トラフィックの両方がカバーされます。

gRPC Java サーバーの場合

gRPC Java サーバーを使用する場合は、 application.properties ファイルで次のプロパティーを設定することで TLS を設定できます。

quarkus.grpc.server.ssl.certificate=tls/server.pem
quarkus.grpc.server.ssl.key=tls/server.key

quarkus.grpc.server.plain-text=false

このサーバーは、証明書とキーに対して PEM 形式のみをサポートしています。

gRPC クライアント向けの TLS の設定

サーバーに関しては、一元化された TLS 設定を使用するか、直接クライアントを設定できます。

一元化された TLS 設定の場合

Quarkus (Vert.x ベース) クライアントを使用する場合は、 application.properties ファイルで次のプロパティーを設定することで TLS を設定できます。

quarkus.tls.trust-store.p12.path=grpc-client-truststore.p12
quarkus.tls.trust-store.p12.password=password

quarkus.grpc.clients.hello.plain-text=false
quarkus.grpc.clients.hello.use-quarkus-grpc-client=true

直接設定

Quarkus (Vert.x ベース) クライアントを使用する場合は、 application.properties ファイルで次のプロパティーを設定することで TLS を設定できます。

quarkus.grpc.clients.hello.plain-text=false # Use TLS
quarkus.grpc.clients.hello.use-quarkus-grpc-client=true # Use client using the Vert.x based transport
quarkus.grpc.clients.hello.tls.enabled=true
quarkus.grpc.clients.hello.tls.trust-certificate-p12.path=target/certs/grpc-tls-truststore.jks
quarkus.grpc.clients.hello.tls.trust-certificate-p12.password=****

JKS トラストストアを使用する場合は、次の設定を使用します。

quarkus.grpc.clients.hello.plain-text=false # Use TLS
quarkus.grpc.clients.hello.use-quarkus-grpc-client=true # Use client using the Vert.x based transport
quarkus.grpc.clients.hello.tls.enabled=true
quarkus.grpc.clients.hello.tls.trust-certificate-jks.path=target/certs/grpc-tls-truststore.jks
quarkus.grpc.clients.hello.tls.trust-certificate-jks.password=****

PEM 証明書をトラストストアとして使用する場合は、次の設定を使用します。

quarkus.grpc.clients.hello.plain-text=false # Use TLS
quarkus.grpc.clients.hello.use-quarkus-grpc-client=true # Use client using the Vert.x based transport
quarkus.grpc.clients.hello.tls.enabled=true
quarkus.grpc.clients.hello.tls.trust-certificate-pem.certs=target/certs/grpc-client-ca.crt

gRPC Java クライアントを使用する場合、 application.properties ファイルで次のプロパティーを設定することで TLS を設定できます。

quarkus.grpc.clients.hello.ssl.trust-store=target/certs/grpc-client-tls-ca.crt

gRPC Java クライアントは、トラストストアに対して PEM 形式のみをサポートします。

mTLS の設定

gRPC サービスとクライアントに対して相互 TLS (mTLS) を設定できます。

一元化された TLS 設定の使用

Quarkus HTTP サーバー (quarkus.grpc.server.use-separate-server=false) と Quarkus gRPC クライアント (quarkus.grpc.clients.hello.use-quarkus-grpc-client=true) を使用する場合、 application.properties ファイルで次のプロパティーを設定することで mTLS を設定できます。

quarkus.tls.my-server.key-store.p12.path=target/certs/grpc-keystore.p12
quarkus.tls.my-server.key-store.p12.password=password
quarkus.tls.my-server.trust-store.p12.path=target/certs/grpc-server-truststore.p12
quarkus.tls.my-server.trust-store.p12.password=password

quarkus.tls.my-client.trust-store.p12.path=target/certs/grpc-client-truststore.p12
quarkus.tls.my-client.trust-store.p12.password=password
quarkus.tls.my-client.key-store.p12.path=target/certs/grpc-client-keystore.p12
quarkus.tls.my-client.key-store.p12.password=password

quarkus.grpc.clients.hello.plain-text=false
quarkus.grpc.clients.hello.tls-configuration-name=my-client
quarkus.grpc.clients.hello.use-quarkus-grpc-client=true

quarkus.http.ssl.client-auth=REQUIRED # Enable mTLS
quarkus.http.insecure-requests=disabled
quarkus.http.tls-configuration-name=my-server
quarkus.grpc.server.use-separate-server=false
quarkus.grpc.server.plain-text=false

直接設定

gRPC Java サーバーを使用する場合、 application.properties ファイルで次のプロパティーを設定することで mTLS を設定できます。 Vert.x ベースのサーバーと Vert.x ベースのクライアントを使用する場合、 application.properties ファイルで次のプロパティーを設定することで mTLS を設定できます。

# Server side:
quarkus.grpc.server.use-separate-server=false
quarkus.grpc.server.plain-text=false # Force the client to use TLS for the tests
quarkus.http.ssl.certificate.key-store-file=target/certs/grpc-keystore.jks
quarkus.http.ssl.certificate.key-store-password=****
quarkus.http.ssl.certificate.trust-store-file=target/certs/grpc-server-truststore.jks
quarkus.http.ssl.certificate.trust-store-password=****
quarkus.http.ssl.client-auth=REQUIRED # Force the client to authenticate, aka mTLS
quarkus.http.insecure-requests=disabled

# Client side:
quarkus.grpc.clients.hello.plain-text=false
quarkus.grpc.clients.hello.tls.trust-certificate-jks.path=target/certs/grpc-client-truststore.jks
quarkus.grpc.clients.hello.tls.trust-certificate-jks.password=****
quarkus.grpc.clients.hello.tls.key-certificate-jks.path=target/certs/grpc-client-keystore.jks
quarkus.grpc.clients.hello.tls.key-certificate-jks.password=****
quarkus.grpc.clients.hello.tls.enabled=true
quarkus.grpc.clients.hello.use-quarkus-grpc-client=true

トラストストアとキー証明書に P12 形式を使用する場合は、次の設定を使用します。

# Server side
quarkus.grpc.server.use-separate-server=false
quarkus.grpc.server.plain-text=false # Force the client to use TLS for the tests
quarkus.http.ssl.certificate.key-store-file=target/certs/grpc-keystore.p12
quarkus.http.ssl.certificate.key-store-password=****
quarkus.http.ssl.certificate.trust-store-file=target/certs/grpc-server-truststore.p12
quarkus.http.ssl.certificate.trust-store-password=****
quarkus.http.ssl.client-auth=REQUIRED # Force the client to authenticate, aka mTLS
quarkus.http.insecure-requests=disabled

# Client side
quarkus.grpc.clients.hello.plain-text=false
quarkus.grpc.clients.hello.tls.trust-certificate-p12.path=target/certs/grpc-client-truststore.p12
quarkus.grpc.clients.hello.tls.trust-certificate-p12.password=****
quarkus.grpc.clients.hello.tls.key-certificate-p12.path=target/certs/grpc-client-keystore.p12
quarkus.grpc.clients.hello.tls.key-certificate-p12.password=****
quarkus.grpc.clients.hello.tls.enabled=true
quarkus.grpc.clients.hello.use-quarkus-grpc-client=true

関連コンテンツ

同じエクステンションについて

同じトピックについて

Quarkus はオープンです。このプロジェクトのすべての依存関係は、Apache Software License 2.0 または互換性のあるライセンスの下で利用可能です。 CC by 3.0

このウェブサイトは Jekyll で構築され、GitHub Pages でホストされており、完全にオープンソースです。改善したい場合は、ウェブサイトをフォークして、あなたのアイデアを見せてください。

ナビゲーション
フォローする
ヘルプ
言語
Quarkusはコミュニティプロジェクトで構成されています
Copyright © Quarkus. All rights reserved. For details on our trademarks, please visit our Trademark Policy and Trademark List. Trademarks of third parties are owned by their respective holders and their mention here does not suggest any endorsement or association.