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

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

Proposed approach:

• Use GrpcServerFactoryCustomizer

• Allow users to conditionally apply filters

Host/Port/Address Properties

Maintaining separate host/port properties has caused issues (e.g., Redis support).

Solution:

• Use address to mean InetAddress (not the port)

Example:

spring:
  grpc:
    server:
      address: ${my-grpc-ip-address}
      port: ${my-grpc-port}

Distinct GrpcServletRegistration Class

Spring Boot will introduce GrpcServletRegistration instead of using DynamicRegistrationBean.

Benefits:

• Better auto-configuration control

• Ability to stop configuration when existing beans are detected

Internal Condition and Auto-Configuration Updates

Changes include:

• Consolidating auto-configuration classes

• Replacing custom conditions

No expected user impact unless excluding configurations.

Property Restructuring

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

Original behavior:

• Automatically scans .proto generated classes

Proposed approach:

• Use @ImportGrpcClients

Anemic Properties

Current GrpcClientProperties contains logic (e.g., getChannel mutates state).

Solution:

• Keep properties simple (anemic)

• Move logic to mapper classes

GrpcClientDefaultServiceConfigCustomizer

Problem:

• Cannot merge multiple defaultServiceConfig customizers

Solution:

• Introduce GrpcClientDefaultServiceConfigCustomizer

• Allows mutation before final application

Service Config Properties

Problems with generic service-config:

• Poor relaxed binding support

• No type safety

• Conversion issues (e.g., durations)

Solution:

• Remove generic map

• Use strongly typed configuration or customizers (GrpcClientDefaultServiceConfigCustomizer)

Property Restructuring

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:

Testing

Test Specific Factory Classes

Original approach: * Extend in-process factories

Problem:

• Confusion with production customizers

Solution:

• Introduce:

• TestGrpcChannelFactory

• TestGrpcServerFactory

Removal of ContextCustomizerFactory

• Remove InProcessTransportContextCustomizerFactory

• Simplify via property tweaks

Class Renames

• @AutoConfigureInProcessTransport → @AutoConfigureTestGrpcTransport

• @LocalGrpcPort → @LocalGrpcServerPort

Health Check

Removing Actuator Dependency

• Use core health indicator support

• Avoid actuator dependency

Scheduler Use

• Use shared task scheduler

• Align with Spring Integration

Observation

No significant changes.

Security

TBD

Other

TBD