Spring gRPC 1.1 Migration Guide

This document is meant to help you migrate your application to Spring gRPC 1.1.

Note	This is a preview draft of the migration guide. It will be completed when Spring gRPC 1.1 is released.

Starters moved coordinates

The Spring Boot starters have moved from Spring gRPC into Spring Boot as follows:

From	To
org.springframework.grpc:spring-grpc-server-spring-boot-starter	org.springframework.boot:spring-boot-starter-grpc-server
org.springframework.grpc:spring-grpc-client-spring-boot-starter	org.springframework.boot:spring-boot-starter-grpc-client
org.springframework.grpc:spring-grpc-spring-boot-starter	Removed - just include both client and server starters
org.springframework.grpc:spring-grpc-server-web-spring-boot-starter	Removed - see Servlet Server section below

In addition there are now test starters shipped as part of Spring Boot:

Name

org.springframework.boot:spring-boot-starter-grpc-client-test

org.springframework.boot:spring-boot-starter-grpc-client-test

Servlet Server

To use your servlet container as a gRPC server you must now explicitly set the server.http2.enabled property to true and include the required dependencies as the org.springframework.grpc:spring-grpc-server-web-spring-boot-starter no longer exists. Follow the steps in the Servlet Server section of the Spring Boot reference docs.

ServerInterceptorFilter and ServerServiceDefinitionFilter Beans

In Spring gRPC 1.0:

• Applied to in-process servers

• Not applied to regular servers

This is inconsistent with Spring Boot conventions so when migrating you should use a GrpcServerFactoryCustomizer to apply filters.

Host/Port/Address Properties

With Spring Boot there are only address (an InetAddress) and `port (an integer) properties available to configure gRPC. The host property has not been migrated.

If you previously configured your project as follows:

spring:
  grpc:
    server:
      address: 192.168.1.1:1234

You should adapt it to:

spring:
  grpc:
    server:
      address: 192.168.1.1
      port: 1234

Distinct GrpcServletRegistration Class

Spring Boot introduces a GrpcServletRegistration instead of using DynamicRegistrationBean. If you previously used a DynamicRegistrationBean to register your gRPC servlet, you should switch to GrpcServletRegistration so that auto-configuration can detect it.

Property Restructuring

Server properties have been restructured a little and you may need to adapt.

New server properties

spring:
  grpc:
    server:
      address: "*"
      port: 9090
      shutdown:
        grace-period: 30s
      inbound:
        message:
          max-size: 4m
        metadata:
          max-size: 8kb
      inprocess:
        name: "something"
      keepalive:
        time: 2h
        timeout: 20s
        permit:
          time: 5m
          without-calls: false
        connection:
          max-idle-time:
          max-age:
          grace-period: 30s
      ssl:
        enabled:
        client-auth: optional
        bundle: my-bundle
        secure: true
      servlet:
        enabled:
        validate-http2: true
      health:
        enabled:
        include-overall-health: true
        services:
          validate-membership: true
        service:
          <name>:
            include: *
            exclude:
        status:
          order:
          mapping:
            up: serving
            down: not-serving
        scheduler:
          enabled: true
          period: 5s
          delay: 5s

Previous server properties

spring:
  grpc:
    server:
      address: "*:9090"
      host:
      port:
      max-inbound-message-size:
      max-inbound-metadata-size:
      inprocess:
        name:
      keep-alive:
        time:
        timeout:
        max-idle:
        max-age:
        max-age-grace:
        permit-time:
        permit-without-calls:
      ssl:
        enabled:
        client-auth: optional
        bundle: my-bundle
        secure: true
      health:
        enabled:
        actuator:
          enabled:
          update-overall-health:
          update-rate:
          update-initial-delay:
          health-indicator-paths:

Client

Automatic Scanning

Spring gRPC 1.0 Automatically scaned for .proto generated classes. Spring Boot not longer does this and you should use explicit @ImportGrpcClients annotations.

GrpcClientDefaultServiceConfigCustomizer

Merging multiple defaultServiceConfig customizers is difficult when just using a GrpcChannelFactoryCustomizer because the last customizer wins. To solve this, Spring Boot introduces a GrpcClientDefaultServiceConfigCustomizer that allows many customizers to mutate the defaultServiceConfig before it is set.

Property Restructuring

Client properties have been restructured a little and you may need to adapt.

New client properties

spring:
  grpc:
    client:
      channel:
        <name>:
          target:
          user-agent:
          bypass-certificate-validation:
          inbound:
            message:
              max-size:
            metadata:
              max-size:
          default:
            deadline:
            load-balancing-policy:
          idle:
            timeout:
          keepalive:
            time:
            timeout:
            without-calls: true
          health:
            enabled:
            service-name:

Previous client properties

spring:
  grpc:
    client:
      channels:
        <name>:
          address:
          default-deadline:
          default-load-balancing-policy:
          enable-keep-alive:
          health:
            enabled:
            service-name:
          idle-timeout:
          inherit-defaults:
          keep-alive-time:
          keep-alive-timeout:
          keep-alive-without-calls:
          max-inbound-message-size:
          max-inbound-metadata-size:
          negotiation-type:
          secure:
          service:config:
            <key>: <value>
          ssl:
          user-agent:
      default-channel:
      channel-defaults:
      defaultStubFactory:

Service Config Properties

Service config properties were previously coerced from the underling application properties into a from supported by gRPC. In Spring Boot, they are now strongly typed.

See org.springframework.boot.grpc.client.autoconfigure.ServiceConfig for details.

Testing

Class Renames

The following classes have been renamed:

• @AutoConfigureInProcessTransport → @AutoConfigureTestGrpcTransport

• @LocalGrpcPort → @LocalGrpcServerPort

Test Specific Factory Classes

Tests now use a custom GrpcServerFactory to create in-process channels rather than using InProcessGrpcServerFactory. This helps keep InProcessGrpcServerFactory for user code and allow better detection of then a factory is for test purposes.

Removal of InProcessTransportContextCustomizerFactory

The above means that InProcessTransportContextCustomizerFactory is not longer needed. It has not been migrated to Spring Boot.

Health Check

Removing Actuator Dependency

The gRPC health check feature has been reworked to build directly on Spring Boot’s HealthIndicator classes rather than building on HTTP actuator endpoints. This means that you can have health checking without needing actuator.

You may need to update your health properties to directly reference the indicators you wish to use. For example:

spring:
  grpc:
    server:
      health:
        service:
          myservice:
            include:
            - db
            - redis

See the Spring Boot gRPC health documentation for more details.

Scheduler Use

The scheduler backing gRPC health is now the standard Spring Boot shared scheduler. This should have no impact on typical applications.

Observation

No significant changes.

Security

Security support has been simplified a little during the migration to Spring Boot. Please see the security section of the Spring Boot reference documentation for details.

SSL Support

Some SSL properties have been renamed or simplified. You may need to update your application.properties or application.yaml file.

For details of the new properties please see the client SSL and server SSL documentation.