Configuration

A gRPC client is configured with a GrpcClientSettingsGrpcClientSettings instance. There are a number of ways of creating one and the API docs are the best reference. An ActorSystem is always required as it is used for default configuration and service discovery.

By Code

The simplest way to create a client is to provide a static host and port.

Scala
sourceGrpcClientSettings.connectToServiceAt("localhost", 443)
Java
sourceGrpcClientSettings.connectToServiceAt("localhost", 443, actorSystem);

Further settings can be added via the with methods

Scala
sourceGrpcClientSettings.connectToServiceAt("localhost", 443).withDeadline(1.second).withTls(false)
Java
sourceGrpcClientSettings.connectToServiceAt("localhost", 443, actorSystem)
    .withDeadline(Duration.ofSeconds(1))
    .withTls(false);

By Configuration

Instead a client can be defined in configuration. All client configurations need to be under pekko.grpc.client

Scala
sourcepekko.grpc.client {
  "project.WithSpecificConfiguration" {
    service-discovery {
      service-name = "my-service"
    }
    host = "my-host"
    port = 42
    override-authority = "google.fr"
    deadline = 10m
    user-agent = "Pekko-gRPC"
  }
}
Java
sourcepekko.grpc.client {
  "project.WithSpecificConfiguration" {
    service-discovery {
      service-name = "my-service"
    }
    host = "my-host"
    port = 42
    override-authority = "google.fr"
    deadline = 10m
    user-agent = "Pekko-gRPC"
  }
}

Clients defined in configuration pick up defaults from reference.conf:

reference.conf
sourcepekko.grpc.client."*" {
  # netty or pekko-http (experimental)
  backend = "netty"

  # Host to use if service-discovery-mechanism is set to static or grpc-dns
  host = ""

  service-discovery {
    mechanism = "static"
    # Service name to use if a service-discovery.mechanism other than static or grpc-dns
    service-name = ""
    # See https://pekko.apache.org/docs/pekko-management/current/discovery/index.html for meanings for each mechanism
    # if blank then not passed to the lookup
    port-name = ""
    protocol = ""

    # timeout for service discovery resolving
    resolve-timeout = 1s
  }

  # port to use if service-discovery-mechanism is static or service discovery does not return a port
  port = 0

  # Experimental in grpc-java https://github.com/grpc/grpc-java/issues/1771
  # pick_first or round_robin
  load-balancing-policy = ""

  deadline = infinite
  override-authority = ""
  user-agent = ""
  # Location on the classpath of CA PEM to trust
  trusted = ""
  use-tls = true
  # SSL provider to use:
  # leave empty to auto-detect, or configure 'jdk' or 'openssl'.
  ssl-provider = ""

  # Whether to verify the server's hostname against its TLS certificate (RFC 2818).
  # When false, the client accepts any valid certificate regardless of hostname.
  # This is insecure and should only be used for testing.
  # Only effective for the pekko-http backend; the netty backend always verifies.
  verify-hostname = true

  # Minimum TLS protocol version to negotiate. Leave empty (the default) to use whatever
  # the JDK enables; on a supported JDK that is already TLSv1.2 and above. Set this to
  # require a floor of your own, for example to refuse anything below TLSv1.3.
  # This only narrows the versions the JDK enables; it never re-enables a disabled one.
  # Accepted values: "", "TLSv1.2", "TLSv1.3"
  minimum-tls-version = ""

  # TODO: Enforce HTTP/2 TLS restrictions: https://tools.ietf.org/html/draft-ietf-httpbis-http2-17#section-9.2

  # Maximum allowed size for inbound gRPC messages (in bytes).
  # Applies to the decompressed message size. Messages exceeding this limit
  # will be rejected with RESOURCE_EXHAUSTED status.
  # Applies to both the netty and the pekko-http backend.
  # Default is 4 MiB, matching grpc-java's default.
  max-inbound-message-size = 4194304

  # The message encoding to compress requests with: "gzip", "deflate", or "identity" (or empty) for no
  # compression. A client can't know which encodings a server supports, so compression is off by default:
  # only enable it for servers known to support the encoding.
  # Applies to both the netty and the pekko-http backend.
  compression = ""

  # The number of times to try connecting before giving up.
  # '-1': means retry indefinitely, '0' is invalid, '1' means fail
  # after the first failed attempt.
  # When load balancing we don't count individual connection
  # failures, so in that case any value larger than '1' is also
  # interpreted as retrying 'indefinitely'.
  connection-attempts = 20

  # Service discovery mechanism to use. The default is to use a static host
  # and port that will be resolved via DNS.
  # Any of the mechanisms described in https://pekko.apache.org/docs/pekko-management/current/discovery/index.html can be used
  # including Kubernetes, Consul, AWS API
}

TLS hostname verification

When TLS is enabled the client verifies that the server’s certificate matches the hostname it connected to (RFC 2818), so a certificate that is otherwise valid and trusted is still rejected if it was issued for a different host. This is controlled by verify-hostname, which defaults to true:

pekko.grpc.client."*" {
  verify-hostname = true
}

or programmatically:

Scala
val settings = GrpcClientSettings.connectToServiceAt("localhost", 8080)
  .withVerifyHostname(true)
Java
GrpcClientSettings settings = GrpcClientSettings.connectToServiceAt("localhost", 8080, system)
    .withVerifyHostname(true);

The hostname that is checked is the authority the client connects to — that is override-authority when it is set, otherwise the service name — not the address that service discovery resolved to. This matches how gRPC treats an overridden authority, and it is what lets a client reach a server by IP while still verifying the certificate it expects.

Warning

Setting verify-hostname = false accepts any trusted certificate regardless of which host it was issued for, which removes the protection against a man-in-the-middle that holds any certificate your trust store accepts. It exists for testing against certificates that do not carry a matching name, and should not be used in production. The client logs a warning on every channel it creates while it is disabled.

The setting only applies to the pekko-http backend. The netty backend always verifies the hostname and offers no switch to turn it off, so setting verify-hostname = false there has no effect and is logged as a warning.

Minimum TLS version

By default the client negotiates whichever TLS versions the JDK enables, which on a supported JDK is TLSv1.2 and above. To require a higher floor, set minimum-tls-version. The accepted values are TLSv1.2 and TLSv1.3; any other value is rejected when the settings are created. The setting only narrows the versions the JDK enables: it never re-enables a version the JDK has disabled, for example through jdk.tls.client.protocols or jdk.tls.disabledAlgorithms.

pekko.grpc.client."*" {
  minimum-tls-version = "TLSv1.3"
}

or programmatically:

Scala
val settings = GrpcClientSettings.connectToServiceAt("localhost", 8080)
  .withMinimumTlsVersion("TLSv1.3")
Java
GrpcClientSettings settings = GrpcClientSettings.connectToServiceAt("localhost", 8080, system)
    .withMinimumTlsVersion("TLSv1.3");

The setting applies to both the netty and the pekko-http backend, including when you supply your own SSLContext with withSslContext.

To set a floor for every TLS client in the JVM rather than per gRPC client, the JDK’s jdk.tls.client.protocols system property (for example -Djdk.tls.client.protocols=TLSv1.3) does that. It only applies to the JDK’s own TLS implementation, so it is ignored when the netty backend uses the OpenSSL provider (ssl-provider = "openssl").

Maximum inbound message size

Inbound gRPC messages are limited to 4 MiB by default, matching the grpc-java default; larger messages are rejected with RESOURCE_EXHAUSTED. The limit applies to both the netty and the pekko-http backend, and covers the decompressed size, so a compressed response that inflates past the limit is rejected while it is being decompressed.

Set it in configuration:

pekko.grpc.client."*" {
  max-inbound-message-size = 8388608  # 8 MiB
}

or programmatically:

Scala
val settings = GrpcClientSettings.connectToServiceAt("localhost", 8080)
  .withMaxInboundMessageSize(8 * 1024 * 1024)
Java
GrpcClientSettings settings = GrpcClientSettings.connectToServiceAt("localhost", 8080, system)
    .withMaxInboundMessageSize(8 * 1024 * 1024);

Request compression

By default the client does not compress requests: a client can’t know which message encodings a server supports, so it should only compress requests to servers known to support the encoding. The gzip and deflate encodings are supported, with both the netty and the pekko-http backend.

Set it in configuration:

pekko.grpc.client."*" {
  compression = "gzip"
}

or programmatically:

Scala
val settings = GrpcClientSettings.connectToServiceAt("localhost", 8080)
  .withCompression("gzip")
Java
GrpcClientSettings settings = GrpcClientSettings.connectToServiceAt("localhost", 8080, system)
    .withCompression("gzip");

Responses are decompressed whichever encoding the server chooses from the ones the client accepts.

Using Pekko Discovery for Endpoint Discovery

The examples above all use a hard coded host and port for the location of the gRPC service which is the default if you do not configure a service-discovery-mechanism. Alternatively Pekko Discovery can be used. This allows a gRPC client to switch between discovering services via DNS, config, Kubernetes and Consul and others by just changing the configuration (see Discovery methods in Pekko Management).

To see how to config a particular service discovery mechanism see the Pekko Discovery docs. Once it is configured a service discovery mechanism name can either be passed into settings or put in the client’s configuration.

Scala
sourcepekko.grpc.client {
  "project.WithConfigServiceDiscovery" {
    service-discovery {
      mechanism = "config"
      service-name = "from-config"
      # optional for discovery
      protocol = "tcp"
      port-name = "http"
    }
    port = 43
  }
}
Java
sourcepekko.grpc.client {
  "project.WithConfigServiceDiscovery" {
    service-discovery {
      mechanism = "config"
      service-name = "from-config"
      # optional for discovery
      protocol = "tcp"
      port-name = "http"
    }
    port = 43
  }
}

The above example configures the client project.WithConfigServiceDiscovery to use config based service discovery.

Then to create the GrpcClientSettings:

Scala
source// an implicit ActorSystem is required to be in scope for service discovery
val settings = GrpcClientSettings.fromConfig(clientName = "project.WithConfigServiceDiscovery")
Java
source// an ActorSystem is required for service discovery
GrpcClientSettings.fromConfig("project.WithConfigServiceDiscovery", actorSystem);

Alternatively if a default instance is available (configured by pekko.discovery.method) in your system it can be use like this:

Scala
source// An ActorSystem's default service discovery mechanism
GrpcClientSettings
  .usingServiceDiscovery(serviceName = "my-service")
  .withServicePortName("https") // (optional) refine the lookup operation to only https ports
Java
source// An ActorSystem's default service discovery mechanism
GrpcClientSettings.usingServiceDiscovery("my-service", actorSystem)
    .withServicePortName("https"); // (optional) refine the lookup operation to only https ports

Currently service discovery is only queried on creation of the client. A client can be automatically re-created, and go via service discovery again, if a connection can’t be established, see the lifecycle section.

Debug logging

To enable fine grained debug running the following logging configuration can be used.

Put this in a file grpc-debug-logging.properties:

handlers=java.util.logging.ConsoleHandler
io.grpc.netty.level=FINE
java.util.logging.ConsoleHandler.level=FINE
java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter

Run with -Djava.util.logging.config.file=/path/to/grpc-debug-logging.properties.