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>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=disabledJKS または 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 クライアント向けの 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.crtgRPC Java クライアントを使用する場合、 application.properties ファイルで次のプロパティーを設定することで TLS を設定できます。
quarkus.grpc.clients.hello.ssl.trust-store=target/certs/grpc-client-tls-ca.crtgRPC 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
