Merge pull request #1103 from charlesmst/actuator-healthcheck

Actuator healthcheck

Author: yidongnan

docs/en/actuator.md

@@ -7,7 +7,7 @@ This page focuses on the integration with
 This is an optional feature. Supported features:
 
 - Client + server metrics
-- Server `InfoContributor`
+- Server `InfoContributor` and `GRPC Health API`
 
 ## Table of Contents <!-- omit in toc -->
 
@@ -18,6 +18,7 @@ This is an optional feature. Supported features:
   - [Viewing the metrics](#viewing-the-metrics)
   - [Metric configuration](#metric-configuration)
 - [InfoContributor](#infocontributor)
+- [GRPC Health](#grpc-health)
 - [Opt-Out](#opt-out)
 
 ## Dependencies
@@ -178,6 +179,29 @@ You can view the grpc info along with your other info at `/actuator/info` (requi
 
 You can turn of the service listing (for both actuator and grpc) using `grpc.server.reflectionServiceEnabled=false`.
 
+## GRPC Health
+
+By default, the health endpoint will use the standard gRPC implementation for health, which does not integrate with Spring Boot Actuator.
+
+The server provides an optional integration with Actuator health information using the [gRPC Health API](https://grpc.io/docs/guides/health-checking/).
+
+This integration enables the server to respond to gRPC health checks based on the `HealthEndpoint` from Actuator, which is the same used for the web version.
+
+To enable this integration, add the following properties to your application configuration:
+
+````properties
+grpc.server.health-service.type=ACTUATOR
+````
+
+The integration allows you to check the health status for the whole service or specific health indicators, where the `service` is the key of the [`HealthIndicator`](https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html#actuator.endpoints.health.auto-configured-health-indicators).
+`Watch` is not yet supported because actuator is pull-based and does not automatically tries to determine the status of the service to notify clients.
+
+To prevent any health service from being served by the GRPC server, you can set the type to `NONE`:
+
+````properties
+grpc.server.health-service.type=NONE
+````
+
 ## Opt-Out
 
 You can opt out from the actuator autoconfiguration using the following annotation:

grpc-server-spring-boot-starter/src/main/java/net/devh/boot/grpc/server/autoconfigure/GrpcHealthServiceAutoConfiguration.java

@@ -16,6 +16,9 @@
 
 package net.devh.boot.grpc.server.autoconfigure;
 
+import org.springframework.boot.actuate.autoconfigure.health.HealthEndpointAutoConfiguration;
+import org.springframework.boot.actuate.health.HealthEndpoint;
+import org.springframework.boot.autoconfigure.AutoConfigureAfter;
 import org.springframework.boot.autoconfigure.AutoConfigureBefore;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
@@ -25,6 +28,7 @@
 
 import io.grpc.BindableService;
 import io.grpc.protobuf.services.HealthStatusManager;
+import net.devh.boot.grpc.server.health.ActuatorGrpcHealth;
 import net.devh.boot.grpc.server.service.GrpcService;
 
 /**
@@ -36,6 +40,7 @@
 @ConditionalOnClass(HealthStatusManager.class)
 @ConditionalOnProperty(prefix = "grpc.server", name = "health-service-enabled", matchIfMissing = true)
 @AutoConfigureBefore(GrpcServerFactoryAutoConfiguration.class)
+@AutoConfigureAfter(HealthEndpointAutoConfiguration.class)
 public class GrpcHealthServiceAutoConfiguration {
 
     /**
@@ -45,14 +50,24 @@ public class GrpcHealthServiceAutoConfiguration {
      */
     @Bean
     @ConditionalOnMissingBean
+    @ConditionalOnProperty(prefix = "grpc.server", name = "health-service.type", havingValue = "GRPC",
+            matchIfMissing = true)
     HealthStatusManager healthStatusManager() {
         return new HealthStatusManager();
     }
 
     @Bean
     @GrpcService
+    @ConditionalOnProperty(prefix = "grpc.server", name = "health-service.type", havingValue = "GRPC",
+            matchIfMissing = true)
     BindableService grpcHealthService(final HealthStatusManager healthStatusManager) {
         return healthStatusManager.getHealthService();
     }
 
+    @Bean
+    @GrpcService
+    @ConditionalOnProperty(prefix = "grpc.server", name = "health-service.type", havingValue = "ACTUATOR")
+    BindableService grpcHealthServiceActuator(final HealthEndpoint healthStatusManager) {
+        return new ActuatorGrpcHealth(healthStatusManager);
+    }
 }

grpc-server-spring-boot-starter/src/main/java/net/devh/boot/grpc/server/config/GrpcServerProperties.java

@@ -223,11 +223,21 @@ public class GrpcServerProperties {
     /**
      * Whether gRPC health service is enabled or not. Defaults to {@code true}.
      *
+     * @deprecated Use {@link HealthOptions#type health type} @{@link HealthType#NONE NONE} instead.
      * @param healthServiceEnabled Whether gRPC health service is enabled.
      * @return True, if the health service is enabled. False otherwise.
      */
+    @Deprecated
     private boolean healthServiceEnabled = true;
 
+    /**
+     * Implementation of gRPC health service. Defaults the type to {@link HealthType#GRPC GRPC}.
+     *
+     * @param healthService The options for the health service.
+     * @return The type of health service to use.
+     */
+    private HealthOptions healthService = new HealthOptions();
+
     /**
      * Whether proto reflection service is enabled or not. Defaults to {@code true}.
      *

grpc-server-spring-boot-starter/src/main/java/net/devh/boot/grpc/server/config/HealthOptions.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2016-2024 The gRPC-Spring Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.devh.boot.grpc.server.config;
+
+import lombok.Data;
+
+/**
+ * GRPC Health service options.
+ */
+@Data
+public class HealthOptions {
+
+    /**
+     * Implementation of gRPC health service. Defaults to {@link HealthType#GRPC GRPC}. To disable health service set to
+     * {@link HealthType#NONE NONE}.
+     *
+     * @see net.devh.boot.grpc.server.autoconfigure.GrpcHealthServiceAutoConfiguration
+     * @param type The implementation of gRPC health service.
+     * @return GRPC, ACTUATOR or NONE.
+     */
+    private HealthType type = HealthType.GRPC;
+}

grpc-server-spring-boot-starter/src/main/java/net/devh/boot/grpc/server/config/HealthType.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2016-2024 The gRPC-Spring Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.devh.boot.grpc.server.config;
+
+
+/**
+ * Enum to specify the type of health service to use in GRPC.
+ */
+public enum HealthType {
+    /**
+     * Use the standard GRPC health service from io.grpc.
+     * 
+     * @see net.devh.boot.grpc.server.autoconfigure.GrpcHealthServiceAutoConfiguration#grpcHealthService
+     */
+    GRPC,
+    /**
+     * Uses a bridge to the Spring Boot Actuator health service.
+     * 
+     * @see net.devh.boot.grpc.server.autoconfigure.GrpcHealthServiceAutoConfiguration#grpcHealthServiceActuator
+     * @see net.devh.boot.grpc.server.health.ActuatorGrpcHealth
+     */
+    ACTUATOR,
+    /**
+     * No health service will be created.
+     */
+    NONE
+}

grpc-server-spring-boot-starter/src/main/java/net/devh/boot/grpc/server/health/ActuatorGrpcHealth.java

@@ -0,0 +1,72 @@
+/*
+ * Copyright (c) 2016-2024 The gRPC-Spring Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.devh.boot.grpc.server.health;
+
+
+import static io.grpc.Status.NOT_FOUND;
+
+import org.springframework.boot.actuate.health.HealthComponent;
+import org.springframework.boot.actuate.health.HealthEndpoint;
+import org.springframework.boot.actuate.health.Status;
+
+import io.grpc.StatusException;
+import io.grpc.health.v1.HealthCheckRequest;
+import io.grpc.health.v1.HealthCheckResponse;
+import io.grpc.health.v1.HealthGrpc;
+import io.grpc.stub.StreamObserver;
+
+public class ActuatorGrpcHealth extends HealthGrpc.HealthImplBase {
+    private final HealthEndpoint healthEndpoint;
+
+    public ActuatorGrpcHealth(HealthEndpoint healthEndpoint) {
+        this.healthEndpoint = healthEndpoint;
+    }
+
+    public void check(HealthCheckRequest request, StreamObserver<HealthCheckResponse> responseObserver) {
+
+        if (!request.getService().isEmpty()) {
+            HealthComponent health = healthEndpoint.healthForPath(request.getService());
+            if (health == null) {
+                responseObserver.onError(
+                        new StatusException(NOT_FOUND.withDescription("unknown service " + request.getService())));
+                return;
+            }
+            Status status = health.getStatus();
+            HealthCheckResponse.ServingStatus result = resolveStatus(status);
+            HealthCheckResponse response = HealthCheckResponse.newBuilder().setStatus(result).build();
+            responseObserver.onNext(response);
+            responseObserver.onCompleted();
+        } else {
+            Status status = healthEndpoint.health().getStatus();
+            HealthCheckResponse.ServingStatus result = resolveStatus(status);
+            HealthCheckResponse response = HealthCheckResponse.newBuilder().setStatus(result).build();
+            responseObserver.onNext(response);
+            responseObserver.onCompleted();
+        }
+
+    }
+
+    private HealthCheckResponse.ServingStatus resolveStatus(Status status) {
+        if (Status.UP.equals(status)) {
+            return HealthCheckResponse.ServingStatus.SERVING;
+        }
+        if (Status.DOWN.equals(status) || Status.OUT_OF_SERVICE.equals(status)) {
+            return HealthCheckResponse.ServingStatus.NOT_SERVING;
+        }
+        return HealthCheckResponse.ServingStatus.UNKNOWN;
+    }
+}

grpc-server-spring-boot-starter/src/test/java/net/devh/boot/grpc/server/autoconfigure/GrpcHealthServiceFalseAutoConfigurationTest.java

@@ -30,7 +30,7 @@
 import io.grpc.health.v1.HealthCheckResponse;
 
 @SpringBootTest(classes = GrpcHealthServiceDefaultAutoConfigurationTest.TestConfig.class,
-        properties = "grpc.server.health-service-enabled=false")
+        properties = "grpc.server.health-service.type=NONE")
 @ImportAutoConfiguration({
         GrpcServerAutoConfiguration.class,
         GrpcServerFactoryAutoConfiguration.class,