gRPC reference guide
Using gRPC with Quarkus
If you need to implement a gRPC service or consume it, you need the quarkus-grpc extension. It handles both sides.
Utilizando o Maven
To enable gRPC, add the following dependency to your project:
<dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-grpc</artifactId> </dependency>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 provides two implementation of the gRPC server: gRPC Java (based on Netty) and Vert.x. Both of them support TLS.
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).
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 serverWe 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
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 transportWhile 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
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=disabledThe 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=disabledYou 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 quarkus.http.insecure-requests property is used to disable insecure requests. |
| When TLS is enabled, it covers both HTTP and gRPC traffic. |
With the gRPC Java server
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=falseThis server only supports PEM format for the certificate and the key.
Configuring TLS for gRPC clients
As for the server, you can configure the clients using the centralized TLS configuration or directly.
With the centralized TLS configuration
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=trueDirect configuration
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=****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=****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.crtWhen 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.crtgRPC Java client only support the PEM format for the trust-store.
Configuring mTLS
You can configure mutual TLS (mTLS) for gRPC services and clients.
Using the centralized TLS configuration
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=falseDirect configuration
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=trueIf 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
