Back to Guides
このページを編集

gRPC reference guide

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 provides two implementations of the gRPC server: gRPC Java (based on Netty) and Vert.x. Both of them support TLS.

One of the advantages of the Vert.x based server is the ability to use a single server to handle HTTP requests and gRPC requests. This is useful if you want to expose both REST and gRPC endpoints on the same port. This is not possible with the gRPC Java server (using a separate server).

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 サーバーの使用が推奨されます。

You cannot use both servers at the same time.

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

大容量の 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
    }
}
The separate server mode provides more direct control over Netty-specific settings but requires a dedicated port for gRPC traffic.

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

ポートを指定したくない場合、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
The quarkus.http.insecure-requests property is used to disable insecure requests.
When TLS is enabled, it covers both HTTP and gRPC traffic.

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 client only supports the PEM format for the trust-store.

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 is open. All dependencies of this project are available under the Apache Software License 2.0 or compatible license. CC by 3.0

This website was built with Roq on Quarkus, is hosted on GitHub Pages and is completely open source. If you want to make it better, fork the website and show us what you’ve got.

ナビゲーション
フォローする
ヘルプ
言語
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.