gRPC reference guide
Using gRPC with Quarkus
如需实现 gRPC 服务或使用它,您需要 quarkus-grpc
扩展。它负责处理这两方面。
If you need to implement a gRPC service or consume it, you need the quarkus-grpc
extension.
It handles both sides.
Using Maven
要启用 gRPC,请向项目添加以下依赖项:
To enable gRPC, add the following dependency to your project:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-grpc</artifactId>
</dependency>
接下来,确保在 Quarkus Maven 插件中启用了 `generate-code`阶段:
Next, ensure that the generate-code
phase is enabled in the Quarkus Maven plugin:
<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>
Selecting a gRPC server
Quarkus 提供了两种实现 gRPC 服务器的方式:基于 Netty 的 gRPC Java 和 Vert.x。它们都支持 TLS。
Quarkus provides two implementation of the gRPC server: gRPC Java (based on Netty) and Vert.x. Both of them support TLS.
基于 Vert.x 的服务器的一个优势在于能够使用一个服务器处理 HTTP 请求和 gRPC 请求。如果您想在同一个端口上公开 REST 和 gRPC 端点,这种情况很有用。而 gRPC Java(使用独立的服务器)服务器无法做到这一点。
One of the advantage 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
属性:
To select the gRPC server implementation, set the quarkus.grpc.server.use-separate-server
property in your application.properties
file:
quarkus.grpc.server.use-separate-server=false # Use the Vert.x based server
我们建议使用基于 Vert.x 的 gRPC 服务器,因为它更加灵活,与 Quarkus 生态系统集成的也更好。
We recommend the usage of the Vert.x based gRPC server, as it is more flexible and better integrated in the Quarkus ecosystem.
您无法同时使用这两个服务器。
You cannot use both servers at the same time.
Selecting gRPC clients
对于服务器,Quarkus 为 gRPC 客户端提出了两个备选方案:gRPC Java 和 Vert.x。不同于服务器,您可以选择每个客户端的传输:
As for the server, Quarkus proposes two alternatives for the gRPC clients: gRPC Java and Vert.x. Unlike for the server, you can select the transport for each client:
quarkus.grpc.clients.hello.use-quarkus-grpc-client=true # Use client using the Vert.x based transport
虽然这不是默认设置,但我们建议使用基于 Vert.x 的客户端,因为它更加灵活,与 Quarkus 生态系统集成的也更好。它不会更改您能使用的存根,因为它们是由 gRPC 框架生成的。但是,它会改变客户端与服务器的通信方式。
While it’s not the default, we recommend using the Vert.x based client, as it is more flexible and better integrated in the Quarkus ecosystem. It does not change the stubs you can use, as they are generated by the gRPC framework. However, it changes the way the client communicates with the server.
Configuring TLS for gRPC services
With the Vert.x based server
如果您使用基于 Vert.x 的服务器,则可以通过在 application.properties
文件中设置以下属性来配置 TLS:
If you use the Vert.x based server, you can configure TLS by setting the following properties in your application.properties
file:
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
之前的配置使用了 centralized TLS configuration。这是建议采用的方法。
The previous configuration uses the centralized TLS configuration. This is the recommended approach.
您也可以使用以下属性直接配置服务器:
You can also configure the server directly using the following properties:
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
属性:
You can use key-store-file
and key-store-password
to configure the keystore file and its password when using JKS or P12. For PEM, use the certificate
and key
properties:
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 |
启用 TLS 时,它会同时覆盖 HTTP 和 gRPC 流量。 |
When TLS is enabled, it covers both HTTP and gRPC traffic. |
With the gRPC Java server
如果您使用 gRPC Java 服务器,则可以通过在 application.properties
文件中设置以下属性来配置 TLS:
If you use the gRPC Java server, you can configure TLS by setting the following properties in your application.properties
file:
quarkus.grpc.server.ssl.certificate=tls/server.pem
quarkus.grpc.server.ssl.key=tls/server.key
quarkus.grpc.server.plain-text=false
该服务器只支持证书和密钥的 PEM
格式。
This server only supports PEM
format for the certificate and the key.
Configuring TLS for gRPC clients
对于服务器,您可以使用集中式 TLS 配置或直接配置客户端。
As for the server, you can configure the clients using the centralized TLS configuration or directly.
With the centralized TLS configuration
当使用 Quarkus(基于 Vert.x)客户端时,您可以通过在 application.properties
文件中设置以下属性来配置 TLS:
When using the Quarkus (Vert.x-based) client, you can configure TLS by setting the following properties in your application.properties
file:
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
Direct configuration
当使用 Quarkus(基于 Vert.x)客户端时,您可以通过在 application.properties
文件中设置以下属性来配置 TLS:
When using the Quarkus (Vert.x-based) client, you can configure TLS by setting the following properties in your application.properties
file:
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 信任库,请使用以下配置:
If you use JKS trust-store, use the following configuration:
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 证书作为信任库,请使用以下配置:
If you use PEM certificates as trust-store, use the following configuration:
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:
When using the gRPC Java client, you can configure TLS by setting the following properties in your application.properties
file:
quarkus.grpc.clients.hello.ssl.trust-store=target/certs/grpc-client-tls-ca.crt
gRPC Java 客户端仅支持 PEM
格式用于信任库。
gRPC Java client only support the PEM
format for the trust-store.
Configuring mTLS
您可以为 gRPC 服务和客户端配置双向 TLS (mTLS)。
You can configure mutual TLS (mTLS) for gRPC services and clients.
Using the centralized TLS configuration
使用 Quarkus HTTP 服务器 (quarkus.grpc.server.use-separate-server=false
) 和 Quarkus gRPC 客户端 (quarkus.grpc.clients.hello.use-quarkus-grpc-client=true
) 时,可以通过在 application.properties
文件中设置以下属性来配置 mTLS:
When using the Quarkus HTTP server (quarkus.grpc.server.use-separate-server=false
) and Quarkus gRPC client (quarkus.grpc.clients.hello.use-quarkus-grpc-client=true
), you can configure mTLS by setting the following properties in your application.properties
file:
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
Direct configuration
使用 gRPC Java 服务器时,可以通过在 application.properties
文件中设置以下属性来配置 mTLS:使用基于 Vert.x 的服务器和基于 Vert.x 的客户端时,可以通过在 application.properties
文件中设置以下属性来配置 mTLS:
When using the gRPC Java server, you can configure mTLS by setting the following properties in your application.properties
file:
When using the Vert.x based server and Vert.x-based client, you can configure mTLS by setting the following properties in your application.properties
file:
# 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 格式,请使用以下配置:
If you use P12 format for the trust-store and the key-certificate, use the following configuration:
# 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