选择指南版本

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.

Using 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>

Using Gradle

For Gradle, add the following dependency to your project:

implementation 'io.quarkus:quarkus-grpc'

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 server

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

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

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

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.http.ssl.certificate.key-store-file=target/certs/grpc-tls-keystore.p12
quarkus.http.ssl.certificate.key-store-password=*****
quarkus.http.insecure-requests=disabled

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 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=false

This server only supports PEM format for the certificate and the key.

Configuring TLS for gRPC clients

When using the 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.crt

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 client only support the PEM format for the trust-store.

Configuring mTLS

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

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

Using gRPC with Quarkus
- Using Maven
- Using Gradle
Selecting a gRPC server
Selecting gRPC clients
Configuring TLS for gRPC services
- With the Vert.x based server
- With the gRPC Java server
Configuring TLS for gRPC clients
Configuring mTLS