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>

The quarkus:generate-code goal is executed by default during the Quarkus Maven plugin default lifecycle when using the quarkus packaging, and will handle the code generation.

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

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

Performance tuning for large messages

When working with large gRPC messages, you may need to tune the HTTP/2 flow control window size to achieve optimal throughput.

Unified server mode (Vert.x-based)

When using the unified server mode (quarkus.grpc.server.use-separate-server=false), you can configure the HTTP/2 connection window size:

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

The quarkus.http.http2-connection-window-size property sets the HTTP/2 connection window size in bytes. The default value is -1, which reuses the initial window size setting (typically 64KB). For large messages, increasing this value can significantly improve throughput.

Separate server mode (gRPC Java/Netty-based)

When using the separate server mode (quarkus.grpc.server.use-separate-server=true), you can configure the flow control window using a 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.

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

If you don’t want to specify a port you can set quarkus.http.port=0 and quarkus.http.test-port=0 when using Vert.x (quarkus.grpc.server.use-separate-server=false) or quarkus.grpc.server.port=0 and quarkus.grpc.server.test-port=0 when using the gRPC server. A random open port will be picked by the OS, and a log message printed in the console.

To retrieve the real port, use the io.quarkus.grpc.runtime.GrpcServer API, which can be injected into the application code as a CDI Bean:

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

@Singleton
public class MyService  {
    @Inject
    GrpcServer grpcServer;

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

Or into any kind of test, either as a field or test parameter:

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 は変更されません。 ただし、クライアントがサーバーと通信する方法は変わります。

Client-side flow control window

When working with large messages, you can configure the flow control window for gRPC clients:

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

The default flow control window is 1MB. Increasing this value can improve throughput when receiving large messages from the server.

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 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 Jekyll, 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.