gRPC Integration

Relevant source files

• build-plugin/spring-boot-gradle-plugin/build.gradle
• build-plugin/spring-boot-gradle-plugin/src/docs/antora/modules/gradle-plugin/pages/reacting.adoc
• build-plugin/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/plugin/ProtobufPluginAction.java
• build-plugin/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/plugin/SpringBootPlugin.java
• build-plugin/spring-boot-gradle-plugin/src/test/java/org/springframework/boot/gradle/plugin/ProtobufPluginActionIntegrationTests.java
• build-plugin/spring-boot-gradle-plugin/src/test/java/org/springframework/boot/gradle/testkit/PluginClasspathGradleBuild.java
• build-plugin/spring-boot-gradle-plugin/src/test/resources/org/springframework/boot/gradle/plugin/ProtobufPluginActionIntegrationTests-usesVersionOfGrpcPluginDependencyWhenSpecified.gradle
• build-plugin/spring-boot-gradle-plugin/src/test/resources/org/springframework/boot/gradle/plugin/ProtobufPluginActionIntegrationTests-usesVersionOfProtocDependencyWhenSpecified.gradle
• build-plugin/spring-boot-gradle-plugin/src/test/resources/org/springframework/boot/gradle/plugin/ProtobufPluginActionIntegrationTests.gradle
• core/spring-boot-test/build.gradle
• core/spring-boot-test/src/main/java/org/springframework/boot/test/context/ImportsContextCustomizer.java
• core/spring-boot-test/src/test/java/org/springframework/boot/test/context/ImportsContextCustomizerTests.java
• documentation/spring-boot-docs/src/docs/antora/modules/ROOT/pages/redirect.adoc
• module/spring-boot-grpc-client/build.gradle
• module/spring-boot-grpc-client/src/main/java/org/springframework/boot/grpc/client/autoconfigure/GrpcClientCodecConfiguration.java
• module/spring-boot-grpc-client/src/main/java/org/springframework/boot/grpc/client/autoconfigure/GrpcClientDefaultServiceConfigCustomizer.java
• module/spring-boot-grpc-client/src/main/java/org/springframework/boot/grpc/client/autoconfigure/GrpcClientObservationAutoConfiguration.java
• module/spring-boot-grpc-client/src/main/java/org/springframework/boot/grpc/client/autoconfigure/GrpcClientProperties.java
• module/spring-boot-grpc-client/src/main/java/org/springframework/boot/grpc/client/autoconfigure/PropertiesGrpcClientDefaultServiceConfigCustomizer.java
• module/spring-boot-grpc-client/src/main/resources/META-INF/additional-spring-configuration-metadata.json
• module/spring-boot-grpc-client/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
• module/spring-boot-grpc-client/src/test/java/org/springframework/boot/grpc/client/autoconfigure/GrpcChannelBuilderCustomizersTests.java
• module/spring-boot-grpc-client/src/test/java/org/springframework/boot/grpc/client/autoconfigure/GrpcClientAutoConfigurationTests.java
• module/spring-boot-grpc-client/src/test/java/org/springframework/boot/grpc/client/autoconfigure/GrpcClientObservationAutoConfigurationTests.java
• module/spring-boot-grpc-client/src/test/java/org/springframework/boot/grpc/client/autoconfigure/PropertiesChannelCredentialsProviderTests.java
• module/spring-boot-grpc-client/src/test/java/org/springframework/boot/grpc/client/autoconfigure/ServiceConfigTests.java
• module/spring-boot-grpc-server/build.gradle
• module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/ConditionalOnGrpcServerFactoryEnabled.java
• module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/ConditionalOnMissingNetworkGrpcServer.java
• module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/GrpcServerAutoConfiguration.java
• module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/GrpcServerBuilderCustomizers.java
• module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/GrpcServerCodecConfiguration.java
• module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/GrpcServerExecutorProvider.java
• module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/GrpcServerFactoryCustomizer.java
• module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/GrpcServerObservationAutoConfiguration.java
• module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/GrpcServerProperties.java
• module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/PropertiesServerBuilderCustomizer.java
• module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/ServletGrpcServerConfiguration.java
• module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/health/GrpcServerHealthProperties.java
• module/spring-boot-grpc-server/src/main/resources/META-INF/additional-spring-configuration-metadata.json
• module/spring-boot-grpc-server/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
• module/spring-boot-grpc-server/src/test/java/org/springframework/boot/grpc/server/autoconfigure/GrpcServerAutoConfigurationTests.java
• module/spring-boot-grpc-server/src/test/java/org/springframework/boot/grpc/server/autoconfigure/GrpcServerObservationAutoConfigurationTests.java
• module/spring-boot-grpc-server/src/test/java/org/springframework/boot/grpc/server/autoconfigure/PropertiesServerBuilderCustomizerTests.java
• module/spring-boot-health/src/test/java/org/springframework/boot/health/contributor/StatusTests.java
• platform/spring-boot-internal-dependencies/build.gradle

Spring Boot provides extensive integration for gRPC, supporting both client and server components. The integration is built upon the spring-grpc project and includes auto-configuration for observability, health monitoring, security, and externalized configuration.

Configuration Properties

The gRPC integration is primarily driven by two configuration property classes that map external properties to gRPC components.

Server Properties

GrpcServerProperties module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/GrpcServerProperties.java40 manages the lifecycle and behavior of the gRPC server. Key configuration areas include:

• Network: Port and address binding module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/GrpcServerProperties.java45-50
• Inbound Limits: Maximum message and metadata sizes module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/GrpcServerProperties.java137-195
• Keep-alive: Pings, timeouts, and permit policies module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/GrpcServerProperties.java219-267
• Transport: Specific settings for Netty or Servlet-based deployments module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/GrpcServerProperties.java62-64
• Shutdown: Graceful shutdown period, defaulting to 30 seconds module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/GrpcServerProperties.java113-132

Client Properties

GrpcClientProperties module/spring-boot-grpc-client/src/main/java/org/springframework/boot/grpc/client/autoconfigure/GrpcClientProperties.java41 allows for named channel configurations module/spring-boot-grpc-client/src/main/java/org/springframework/boot/grpc/client/autoconfigure/GrpcClientProperties.java46-50 Each channel can define its own:

• Target: The remote address (e.g., static://localhost:9090) module/spring-boot-grpc-client/src/main/java/org/springframework/boot/grpc/client/autoconfigure/GrpcClientProperties.java57-62
• Service Config: JSON-based configuration for load balancing and retries module/spring-boot-grpc-client/src/main/java/org/springframework/boot/grpc/client/autoconfigure/GrpcClientProperties.java117-123
• Deadlines: Default RPC deadlines for the channel module/spring-boot-grpc-client/src/main/java/org/springframework/boot/grpc/client/autoconfigure/GrpcClientProperties.java223-225

gRPC Configuration Mapping

Feature	Server Property	Client Property
Message Size	spring.grpc.server.inbound.message.max-size	spring.grpc.client.channel.<name>.inbound.message.max-size
Keep-alive Time	spring.grpc.server.keepalive.time	spring.grpc.client.channel.<name>.keepalive.time
SSL/TLS	spring.grpc.server.ssl.*	spring.grpc.client.channel.<name>.ssl.*

Sources: module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/GrpcServerProperties.java40-267 module/spring-boot-grpc-client/src/main/java/org/springframework/boot/grpc/client/autoconfigure/GrpcClientProperties.java41-247

---

Observability and Interceptors

Spring Boot auto-configures Micrometer-based observations for both client and server using specialized interceptors.

• Server Observation: GrpcServerObservationAutoConfiguration module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/GrpcServerObservationAutoConfiguration.java47-54 registers an ObservationGrpcServerInterceptor module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/GrpcServerObservationAutoConfiguration.java60-65
• Client Observation: GrpcClientObservationAutoConfiguration module/spring-boot-grpc-client/src/main/java/org/springframework/boot/grpc/client/autoconfigure/GrpcClientObservationAutoConfiguration.java42-49 registers an ObservationGrpcClientInterceptor marked with @GlobalClientInterceptor module/spring-boot-grpc-client/src/main/java/org/springframework/boot/grpc/client/autoconfigure/GrpcClientObservationAutoConfiguration.java52-59

gRPC Observation Data Flow

Sources: module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/GrpcServerObservationAutoConfiguration.java47-65 module/spring-boot-grpc-client/src/main/java/org/springframework/boot/grpc/client/autoconfigure/GrpcClientObservationAutoConfiguration.java42-61

---

Health Integration

The gRPC server health integration bridges Spring Boot's Actuator health indicators with the standard gRPC Health Checking Protocol (io.grpc.health.v1).

Key features include:

1. Status Mapping: Maps Spring Boot Status (e.g., UP, DOWN) to gRPC ServingStatus (e.g., SERVING, NOT_SERVING) via GrpcServerHealthProperties module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/health/GrpcServerHealthProperties.java169-180
2. Service-Specific Health: Configuration can include or exclude specific health indicators for different gRPC services module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/health/GrpcServerHealthProperties.java129-140

Sources: module/spring-boot-grpc-server/src/main/java/org/springframework/boot/grpc/server/autoconfigure/health/GrpcServerHealthProperties.java129-180

---

Security

Spring Boot provides auto-configuration for securing gRPC endpoints using Spring Security.

CSRF Protection

When running gRPC over a Servlet-based transport, CSRF protection is typically unnecessary as gRPC clients do not use browser-based cookie authentication by default. The spring.grpc.server.security.csrf.enabled property module/spring-boot-grpc-server/src/main/resources/META-INF/additional-spring-configuration-metadata.json29-33 controls this behavior, defaulting to false.

OAuth2 Resource Server

Integration with OAuth2 allows the gRPC server to validate JWT or Opaque tokens, securing services using standard Authorization: Bearer <token> metadata.

Security Entity Mapping

Sources: module/spring-boot-grpc-server/src/main/resources/META-INF/additional-spring-configuration-metadata.json29-33

---

Protobuf and Gradle Integration

The ProtobufPluginAction build-plugin/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/plugin/ProtobufPluginAction.java46 reacts to the application of the Google Protobuf Gradle plugin.

• Version Alignment: It aligns the versions of protoc and the grpc plugin with the versions found on the project's runtime classpath build-plugin/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/plugin/ProtobufPluginAction.java52-54
• Artifact Configuration: Automatically sets the protoc artifact to com.google.protobuf:protoc build-plugin/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/plugin/ProtobufPluginAction.java71-73 and the grpc plugin to io.grpc:protoc-gen-grpc-java build-plugin/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/plugin/ProtobufPluginAction.java76-79
• Task Customization: Configures GenerateProtoTask to include the @generated=omit option for gRPC build-plugin/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/plugin/ProtobufPluginAction.java90-92

Build Logic Flow

Sources: build-plugin/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/plugin/ProtobufPluginAction.java46-158 build-plugin/spring-boot-gradle-plugin/src/docs/antora/modules/gradle-plugin/pages/reacting.adoc110-119

---

Smoke Tests and Verification

The repository uses smoke tests to validate gRPC functionality. These tests use the PluginClasspathGradleBuild build-plugin/spring-boot-gradle-plugin/src/test/java/org/springframework/boot/gradle/testkit/PluginClasspathGradleBuild.java57 to ensure the gRPC and Protobuf plugins are correctly available in the test environment build-plugin/spring-boot-gradle-plugin/src/test/java/org/springframework/boot/gradle/testkit/PluginClasspathGradleBuild.java129-132

Verification includes checking that the protoc artifact and grpc plugin options are correctly applied during the build process build-plugin/spring-boot-gradle-plugin/src/test/resources/org/springframework/boot/gradle/plugin/ProtobufPluginActionIntegrationTests.gradle42-68

Sources: build-plugin/spring-boot-gradle-plugin/src/test/java/org/springframework/boot/gradle/testkit/PluginClasspathGradleBuild.java129-132 build-plugin/spring-boot-gradle-plugin/src/test/resources/org/springframework/boot/gradle/plugin/ProtobufPluginActionIntegrationTests.gradle42-68