From 28da1da24120fdf133a211f32b8ad585e1f7ebfa Mon Sep 17 00:00:00 2001 From: Phillip Webb Date: Mon, 13 Apr 2020 23:26:09 -0700 Subject: [PATCH] Update availability/probe documentation Update the application availability and probes documentation following the recent set of updates. See gh-20962 --- .../src/docs/asciidoc/deployment.adoc | 4 +- .../asciidoc/production-ready-features.adoc | 48 ++++++++++--------- .../docs/asciidoc/spring-boot-features.adoc | 48 ++++++++++--------- 3 files changed, 54 insertions(+), 46 deletions(-) diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/deployment.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/deployment.adoc index f1842950e4..94c74e4f99 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/deployment.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/deployment.adoc @@ -163,9 +163,9 @@ TIP: The https://github.com/pivotal-cf/java-cfenv/[Java CFEnv] project is a bett [[cloud-deployment-kubernetes]] === Kubernetes Spring Boot auto-detects Kubernetes deployment environments by checking the environment for `"*_SERVICE_HOST"` and `"*_SERVICE_PORT"` variables. -You can override this detection with the configprop:management.health.probes.enabled[] configuration property. +You can override this detection with the configprop:spring.main.cloud-platform[] configuration property. -Spring Boot helps you to <> and export it with <>. +Spring Boot helps you to <> and export it with <>. diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/production-ready-features.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/production-ready-features.adoc index cb58b24ad0..ce111a56c3 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/production-ready-features.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/production-ready-features.adoc @@ -679,15 +679,12 @@ The following `HealthIndicators` are auto-configured by Spring Boot when appropr | {spring-boot-actuator-module-code}/jms/JmsHealthIndicator.java[`JmsHealthIndicator`] | Checks that a JMS broker is up. -| {spring-boot-actuator-module-code}/kubernetes/LivenessProbeHealthIndicator.java[`LivenessProbeHealthIndicator`] -| Exposes the "Liveness" application state. - -| {spring-boot-actuator-module-code}/kubernetes/ReadinessProbeHealthIndicator.java[`ReadinessProbeHealthIndicator`] -| Exposes the "Readiness" application state. - | {spring-boot-actuator-module-code}/ldap/LdapHealthIndicator.java[`LdapHealthIndicator`] | Checks that an LDAP server is up. +| {spring-boot-actuator-module-code}/availability/LivenessStateHealthIndicator.java[`LivenessStateHealthIndicator`] +| Exposes the "Liveness" application availability state. + | {spring-boot-actuator-module-code}/mail/MailHealthIndicator.java[`MailHealthIndicator`] | Checks that a mail server is up. @@ -703,6 +700,9 @@ The following `HealthIndicators` are auto-configured by Spring Boot when appropr | {spring-boot-actuator-module-code}/amqp/RabbitHealthIndicator.java[`RabbitHealthIndicator`] | Checks that a Rabbit server is up. +| {spring-boot-actuator-module-code}/availability/ReadinessStateHealthIndicator.java[`ReadinessStateHealthIndicator`] +| Exposes the "Readiness" application availability state. + | {spring-boot-actuator-module-code}/redis/RedisHealthIndicator.java[`RedisHealthIndicator`] | Checks that a Redis server is up. @@ -876,8 +876,8 @@ TIP: You can use `@Qualifier("groupname")` if you need to register custom `Statu Applications deployed on Kubernetes can provide information about their internal state with https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#container-probes[Container Probes]. Depending on https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/[your Kubernetes configuration], the kubelet will call those probes and react to the result. -Spring Boot manages your <> out-of-the-box. -If deployed in a Kubernetes environment, Actuator will gather the "Liveness" and "Readiness" information from the `ApplicationAvailabilityProvider` and use that information in dedicated <>: `LivenessProbeHealthIndicator` and `ReadinessProbeHealthIndicator`. +Spring Boot manages your <> out-of-the-box. +If deployed in a Kubernetes environment, actuator will gather the "Liveness" and "Readiness" information from the `ApplicationAvailability` interface and use that information in dedicated <>: `LivenessStateHealthIndicator` and `ReadinessStateHealthIndicator`. These indicators will be shown on the global health endpoint (`"/actuator/health"`). They will also be exposed as separate HTTP Probes using <>: `"/actuator/health/liveness"` and `"/actuator/health/readiness"`. @@ -904,33 +904,37 @@ NOTE: If an application takes longer to start than the configured liveness perio The `"startupProbe"` is not necessarily needed here as the `"readinessProbe"` fails until all startup tasks are done, see <>. WARNING: If your Actuator endpoints are deployed on a separate management context, be aware that endpoints are then not using the same web infrastructure (port, connection pools, framework components) as the main application. -In this case, a Probe check could be successful even if the main application does not work properly (for example, it cannot accept new connections). +In this case, a probe check could be successful even if the main application does not work properly (for example, it cannot accept new connections). [[production-ready-kubernetes-probes-external-state]] ==== Checking external state with Kubernetes Probes -Actuator configures the "liveness" and "readiness" Probes as Health Groups; this means that all the <> are available for them. +Actuator configures the "liveness" and "readiness" probes as Health Groups; this means that all the <> are available for them. You can, for example, configure additional Health Indicators: [source,properties,indent=0,configprops] ---- - management.endpoint.health.group.readiness.include=readinessProbe,customCheck + management.endpoint.health.group.readiness.include=readinessState,customCheck ---- By default, Spring Boot does not add other Health Indicators to these groups. -The "liveness" Probe should not depend on health checks for external systems. -If the <> is broken, Kubernetes will try to solve that problem by restarting the application instance. +The "`liveness`" Probe should not depend on health checks for external systems. +If the <> is broken, Kubernetes will try to solve that problem by restarting the application instance. This means that if an external system fails (e.g. a database, a Web API, an external cache), Kubernetes might restart all application instances and create cascading failures. -As for the "readiness" Probe, the choice of checking external systems must be made carefully by the application developers, i.e. Spring Boot does not include any additional health checks in the readiness probe. -If the <> is unready, Kubernetes will not route traffic to that instance. +As for the "`readiness`" Probe, the choice of checking external systems must be made carefully by the application developers, i.e. Spring Boot does not include any additional health checks in the readiness probe. +If the <> is unready, Kubernetes will not route traffic to that instance. Some external systems might not be shared by application instances, in which case they could quite naturally be included in a readiness probe. Other external systems might not be essential to the application (the application could have circuit breakers and fallbacks), in which case they definitely should not be included. Unfortunately, an external system that is shared by all application instances is common, and you have to make a judgement call: include it in the readiness probe and expect that the application is taken out of service when the external service is down, or leave it out and deal with failures higher up the stack, e.g. using a circuit breaker in the caller. -NOTE: If all instances of an application are unready, a Kubernetes Service with `type=ClusterIP` or `NodePort` will not accept any incoming connections. There is no HTTP error response (503 etc.) since there is no connection. A Service with `type=LoadBalancer` might or might not accept connections, depending on the provider. A Service that has an explicit https://kubernetes.io/docs/concepts/services-networking/ingress/[Ingress] will also respond in a way that depends on the implementation - the ingress service itself will have to decide how to handle the "connection refused" from downstream. HTTP 503 is quite likely in the case of both load balancer and ingress. +NOTE: If all instances of an application are unready, a Kubernetes Service with `type=ClusterIP` or `NodePort` will not accept any incoming connections. +There is no HTTP error response (503 etc.) since there is no connection. +A Service with `type=LoadBalancer` might or might not accept connections, depending on the provider. +A Service that has an explicit https://kubernetes.io/docs/concepts/services-networking/ingress/[Ingress] will also respond in a way that depends on the implementation - the ingress service itself will have to decide how to handle the "connection refused" from downstream. +HTTP 503 is quite likely in the case of both load balancer and ingress. Also, if an application is using Kubernetes https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/[autoscaling] it may react differently to applications being taken out of the load-balancer, depending on its autoscaler configuration. @@ -948,18 +952,18 @@ When a Spring Boot application starts: |Application startup phase |Liveness State |Readiness State |Notes |Starting -|broken -|unready +|`BROKEN` +|`REFUSING_TRAFFIC` |Kubernetes checks the "liveness" Probe and restarts the application if it takes too long. |Started -|live -|unready +|`CORRECT` +|`REFUSING_TRAFFIC` |The application context is refreshed. The application performs startup tasks and does not receive traffic yet. |Ready -|live -|ready +|`CORRECT` +|`ACCEPTING_TRAFFIC` |Startup tasks are finished. The application is receiving traffic. |=== diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc index 78386c0e84..ad1729b450 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc @@ -193,31 +193,34 @@ See the {spring-boot-module-api}/builder/SpringApplicationBuilder.html[`SpringAp -[[boot-features-application-availability-state]] -=== Application Availability State -When deployed on plaftorms, applications can provide information about their availability to the platform using infrastructure like https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/[Kubernetes Probes]. -Spring Boot manages this application state with the `ApplicationAvailabilityProvider` and makes it available to application components and the platform itself. +[[boot-features-application-availability]] +=== Application Availability +When deployed on platforms, applications can provide information about their availability to the platform using infrastructure such as https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/[Kubernetes Probes]. +Spring Boot includes out-of-the box support for the commonly used "`liveness`" and "`readiness`" availability states. +If you are using Spring Boot's "`actuator`" support then these states are exposed as health endpoint groups. +In addition, you can also obtain availability states by injecting the `ApplicationAvailability` interface into your own beans. -[[boot-features-application-availability-liveness]] + +[[boot-features-application-availability-liveness-state]] ==== Liveness State -The "Liveness" state of an application tells whether its internal state allows it to work correctly, or recover by itself if it's currently failing. -An invalid "Liveness" state means that the application is in a broken state and cannot recover from it; the infrastructure should then restart the application to mitigate that problem. +The "`Liveness`" state of an application tells whether its internal state allows it to work correctly, or recover by itself if it's currently failing. +A broken "`Liveness`" state means that the application is in a state that it cannot recover from, and the infrastructure should restart the application. NOTE: In general, the "Liveness" state should not be based on external checks, such as <>. If it did, a failing external system (a database, a Web API, an external cache) would trigger massive restarts and cascading failures across the platform. -The internal state of Spring Boot applications is mostly represented by the Spring application context. +The internal state of Spring Boot applications is mostly represented by the Spring `ApplicationContext`. If the application context has started successfully, Spring Boot assumes that the application is in a valid state. An application is considered live as soon as the context has been refreshed, see <>. -[[boot-features-application-availability-readiness]] +[[boot-features-application-availability-readiness-state]] ==== Readiness State -The "Readiness" state of an application tells whether the application is ready to handle traffic. -A failing "Readiness" state tells the platform that it should not route traffic to the application for now. +The "`Readiness`" state of an application tells whether the application is ready to handle traffic. +A failing "`Readiness`" state tells the platform that it should not route traffic to the application for now. This typically happens during startup, while `CommandLineRunner` and `ApplicationRunner` components are being processed, or at any time if the application decides that it's too busy for additional traffic. An application is considered ready as soon as application and command-line runners have been called, see <>. @@ -226,9 +229,9 @@ TIP: Tasks expected to run during startup should be executed by `CommandLineRunn -[[boot-features-managing-application-availability]] +[[boot-features-application-availability-managing]] ==== Managing the Application Availability State -Application components can retrieve the current availability state at any time, by injecting the `ApplicationAvailabilityProvider` and calling methods on it. +Application components can retrieve the current availability state at any time, by injecting the `ApplicationAvailability` interface and calling methods on it. More often, applications will want to listen to state updates or update the state of the application. For example, we can export the "Readiness" state of the application to a file so that a Kubernetes "exec Probe" can look at this file: @@ -236,15 +239,15 @@ For example, we can export the "Readiness" state of the application to a file so [source,java,indent=0] ---- @Component - public class ReadinessStateExporter implements ApplicationListener { + public class ReadinessStateExporter { - @Override - public void onApplicationEvent(ReadinessStateChangedEvent event) { - switch (event.getReadinessState().getStatus()) { - case READY: + @EventListener + public void onStateChange(AvailabilityChangeEvent event) { + switch (event.getState()) { + case ACCEPTING_TRAFFIC: // create file /tmp/healthy break; - case UNREADY: + case REFUSING_TRAFFIC: // remove file /tmp/healthy break; } @@ -271,7 +274,7 @@ We can also update the state of the application, when the application breaks and //... } catch (CacheCompletelyBrokenException ex) { - this.eventPublisher.publishEvent(LivenessStateChangedEvent.broken(ex)); + AvailabilityChangeEvent.publish(this.eventPublisher, ex, LivenessState.BROKEN); } } @@ -282,6 +285,7 @@ Spring Boot provides <>. + [[boot-features-application-events-and-listeners]] === Application Events and Listeners In addition to the usual Spring Framework events, such as {spring-framework-api}/context/event/ContextRefreshedEvent.html[`ContextRefreshedEvent`], a `SpringApplication` sends some additional application events. @@ -307,9 +311,9 @@ Application events are sent in the following order, as your application runs: . An `ApplicationContextInitializedEvent` is sent when the `ApplicationContext` is prepared and ApplicationContextInitializers have been called but before any bean definitions are loaded. . An `ApplicationPreparedEvent` is sent just before the refresh is started but after bean definitions have been loaded. . An `ApplicationStartedEvent` is sent after the context has been refreshed but before any application and command-line runners have been called. -. An `LivenessStateChangedEvent` is sent right after to indicate that the application is considered as live. +. An `AvailabilityChangeEvent` is sent right after with `LivenessState.CORRECT` to indicate that the application is considered as live. . An `ApplicationReadyEvent` is sent after any application and command-line runners have been called. -. An `ReadinessStateChangedEvent` is sent right after to indicate that the application is ready to service requests. +. An `LivenessState` is sent right after with `ReadinessState.ACCEPTING_TRAFFIC` to indicate that the application is ready to service requests. . An `ApplicationFailedEvent` is sent if there is an exception on startup. The above list only includes ``SpringApplicationEvent``s that are tied to a `SpringApplication`.