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

gRPC リファレンスガイド

Quarkus で gRPC を使用する

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

Maven の使用

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

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

次に、Quarkus Maven プラグインで generate-code フェーズが有効になっているようにします。

<plugin>
    <groupId>${quarkus.platform.group-id}</groupId>
    <artifactId>quarkus-maven-plugin</artifactId>
    <version>${quarkus.platform.version}</version>
    <extensions>true</extensions>
    <executions>
        <execution>
            <goals>
                <goal>build</goal>
                <goal>generate-code</goal>
                <goal>generate-code-tests</goal>
            </goals>
        </execution>
    </executions>
</plugin>

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 プロパティーを設定します。

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

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

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

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 サービス向けの 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-filekey-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

関連コンテンツ