Skip to content

Commit 68a0fa5

Browse files
PMEds28PMEds28
authored
Merge pull request #200062 from Caoxuyang/main
Check in doc for custom probe feature
2 parents e783e46 + 7bab35d commit 68a0fa5

File tree

2 files changed

+256
-0
lines changed

2 files changed

+256
-0
lines changed

‎articles/spring-cloud/how-to-configure-health-probes-graceful-termination.md

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
---
2+
title: How to configure health probes and graceful termination period for apps hosted in Azure Spring Apps
3+
description: Shows you how to customize apps running in Azure Spring Apps with health probes and graceful termination period.
4+
author: KarlErickson
5+
ms.service: spring-cloud
6+
ms.topic: conceptual
7+
ms.date: 07/02/2022
8+
ms.author: xuycao
9+
ms.custom: devx-track-java, devx-track-azurecli
10+
---
11+
12+
# How to configure health probes and graceful termination periods for apps hosted in Azure Spring Apps
13+
14+
**This article applies to:** ✔️ Java ✔️ C#
15+
16+
**This article applies to:** ✔️ Basic/Standard tier ✔️ Enterprise tier
17+
18+
This article shows you how to customize apps running in Azure Spring Apps with health probes and graceful termination periods.
19+
20+
A probe is a diagnostic performed periodically by Azure Spring Apps on an app instance. To perform a diagnostic, Azure Spring Apps either executes an arbitrary command of your choice within the app instance, establishes a TCP socket connection, or makes an HTTP request.
21+
22+
Azure Spring Apps uses liveness probes to determine when to restart an application. For example, liveness probes could catch a deadlock, where an application is running but unable to make progress. Restarting the application in such a state can help to make the application more available despite bugs.
23+
24+
Azure Spring Apps uses readiness probes to determine when an app instance is ready to start accepting traffic. One use of this signal is to control which app instances are used as backends for the application. When an app instance isn't ready, it's removed from Kubernetes Service Discovery. For more information, see [Discover and register your Spring Boot applications](how-to-service-registration.md).
25+
26+
Azure Spring Apps uses startup probes to determine when an application has started. If such a probe is configured, it disables liveness and readiness checks until it succeeds, making sure those probes don't interfere with the application startup. You can use this behavior to adopt liveness checks on slow starting applications, preventing them from getting killed before they're up and running.
27+
28+
Azure Spring Apps offers default health probe rules for every application. This article shows you how to customize your application with three kinds of health probes.
29+
30+
## Prerequisites
31+
32+
- The [Azure Spring Apps extension](/cli/azure/azure-cli-extensions-overview) for the Azure CLI.
33+
34+
## Configure health probes and graceful termination for applications
35+
36+
The following sections describe the properties available for configuration and how to set the properties using the Azure CLI.
37+
38+
### Graceful termination
39+
40+
The following table describes the property available for configuring graceful termination.
41+
42+
| Property name | Description |
43+
|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
44+
| terminationGracePeriodSeconds | The grace period is the duration in seconds after the processes running in the app instance are sent a termination signal and before the processes are forcibly halted with a kill signal. Set this value longer than the expected cleanup time for your process. The value must be a non-negative integer. The value zero indicates to stop immediately via the kill signal (with no opportunity to shut down). If this value is nil, the default grace period will be used instead. The default value is 90 seconds. |
45+
46+
### Health probe properties
47+
48+
The following table describes the properties available for configuring health probes.
49+
50+
| Property name | Description |
51+
|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
52+
| initialDelaySeconds | The number of seconds after the app instance has started before probes are initiated. The default value is 0 seconds. The minimum value is 0. |
53+
| periodSeconds | How often (in seconds) to perform the probe. The default value is 10 seconds. The minimum value is 1 second. |
54+
| timeoutSeconds | The number of seconds after which the probe times out. The default value is 1 second. The minimum value is 1 second. |
55+
| failureThreshold | The minimum number of consecutive failures for the probe to be considered failed after having succeeded. The default value is 3. The minimum value is 1. |
56+
| successThreshold | The minimum number of consecutive successes for the probe to be considered successful after having failed. The default value is 1. The value must be 1 for liveness and startup. The minimum value is 1. |
57+
58+
### Probe action properties
59+
60+
There are three different ways to check an app instance using a probe. Each probe must define exactly one of these three probe actions:
61+
62+
- `HTTPGetAction`
63+
64+
Performs an HTTP GET request against the app instance on a specified path. The diagnostic is considered successful if the response has a status code greater than or equal to 200 and less than 400.
65+
66+
| Property name | Description |
67+
|---------------|--------------------------------------------------------------------------------|
68+
| scheme | The scheme to use for connecting to the host. Defaults to HTTP. |
69+
| path | The path to access on the HTTP server of the app instance, such as `/healthz`. |
70+
71+
- `ExecAction`
72+
73+
Executes a specified command inside the app instance. The diagnostic is considered successful if the command exits with a status code of 0.
74+
75+
| Property name | Description |
76+
|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
77+
| command | The command line to execute inside the app instance. The working directory for the command is root ('/') in the app instance's filesystem. The command is run using `exec`, not inside a shell, so traditional shell instructions won't work. To use a shell, you need to explicitly call out to that shell. An exit status of 0 is treated as live/healthy and non-zero is unhealthy. |
78+
79+
- `TCPSocketAction`
80+
81+
Performs a TCP check against the app instance.
82+
83+
There are no available properties to be customized for now.
84+
85+
### Customize your application by using the Azure CLI
86+
87+
The following steps show you how to customize your application.
88+
89+
1. Use the following command to create an application with liveness probe and readiness probe:
90+
91+
```azurecli
92+
az spring app create \
93+
--resource-group <resource-group-name> \
94+
--service <Azure-Spring-Cloud-instance-name> \
95+
--name <application-name> \
96+
--enable-liveness-probe true \
97+
--liveness-probe-config <path-to-liveness-probe-json-file> \
98+
--enable-readiness-probe true \
99+
--readiness-probe-config <path-to-readiness-probe-json-file>
100+
```
101+
102+
The following example shows the contents of a sample JSON file passed to the `--liveness-probe-config` parameter in the create command:
103+
104+
```json
105+
{
106+
"probe": {
107+
"initialDelaySeconds": 30,
108+
"periodSeconds": 10,
109+
"timeoutSeconds": 1,
110+
"failureThreshold": 30,
111+
"successThreshold": 1,
112+
"probeAction": {
113+
"type": "TCPSocketAction",
114+
}
115+
}
116+
}
117+
```
118+
119+
> [!NOTE]
120+
> Azure Spring Apps also support two more kinds of probe actions, as shown in the following JSON file examples:
121+
>
122+
> ```json
123+
> "probeAction": {
124+
> "type": "HTTPGetAction",
125+
> "scheme": "HTTP",
126+
> "path": "/anyPath"
127+
> }
128+
> ```
129+
>
130+
> and
131+
>
132+
> ```json
133+
> "probeAction": {
134+
> "type": "ExecAction",
135+
> "command": ["cat", "/tmp/healthy"]
136+
> }
137+
> ```
138+
139+
1. Optionally, protect slow starting containers with a startup probe by using the following command:
140+
141+
```azurecli
142+
az spring app update \
143+
--resource-group <resource-group-name> \
144+
--service <Azure-Spring-Cloud-instance-name> \
145+
--name <application-name> \
146+
--enable-startup-probe true \
147+
--startup-probe-config <path-to-startup-probe-json-file>
148+
```
149+
150+
1. Optionally, disable any specific health probe using the following command:
151+
152+
```azurecli
153+
az spring app update \
154+
--resource-group <resource-group-name> \
155+
--service <Azure-Spring-Cloud-instance-name> \
156+
--name <application-name> \
157+
--enable-liveness-probe false
158+
```
159+
160+
1. Optionally, set the termination grace period seconds using the following command:
161+
162+
```azurecli
163+
az spring app update \
164+
--resource-group <resource-group-name> \
165+
--service <Azure-Spring-Cloud-instance-name> \
166+
--name <application-name> \
167+
--grace-period <termination-grace-period-seconds>
168+
```
169+
170+
## Use best practices
171+
172+
Use the following best practices when adding your own persistent storage to Azure Spring Apps.
173+
174+
- Use liveness and readiness probe together. The reason for this recommendation is that Azure Spring Apps provides two approaches for service discovery at the same time. When the readiness probe fails, the app instance will be removed only from Kubernetes Service Discovery. A properly configured liveness probe can remove the issued app instance from Eureka Service Discovery to avoid unexpected cases. For more information about Service Discovery, see [Discover and register your Spring Boot applications](how-to-service-registration.md).
175+
- When an app instance starts, the first check is done after the delay specified by `initialDelaySeconds`, and subsequent checks happen periodically, with the period length specified by `periodSeconds`. If the app has failed to respond to the requests for a number of times defined by `failureThreshold`, the app instance will be restarted. Be sure your application can start fast enough, or update these parameters, so the total timeout `initialDelaySeconds + periodSeconds * failureThreshold` is longer than the start time of your application.
176+
- For Spring Boot applications, Spring Boot shipped with the [Health Groups](https://docs.spring.io/spring-boot/docs/2.2.x/reference/html/production-ready-features.html#health-groups) support, allowing developers to select a subset of health indicators and group them under a single, correlated, health status. For more information, see [Liveness and Readiness Probes with Spring Boot](https://spring.io/blog/2020/03/25/liveness-and-readiness-probes-with-spring-boot) on the Spring Blog.
177+
178+
The following examples show Liveness and Readiness probes with Spring Boot:
179+
180+
- Liveness probe:
181+
182+
```json
183+
"probe": {
184+
"initialDelaySeconds": 30,
185+
"periodSeconds": 10,
186+
"timeoutSeconds": 1,
187+
"failureThreshold": 30,
188+
"successThreshold": 1,
189+
"probeAction": {
190+
"type": "HTTPGetAction",
191+
"scheme": "HTTP",
192+
"path": "/actuator/health/liveness"
193+
}
194+
}
195+
```
196+
197+
- Readiness probe:
198+
199+
```json
200+
"probe": {
201+
"initialDelaySeconds": 0,
202+
"periodSeconds": 10,
203+
"timeoutSeconds": 1,
204+
"failureThreshold": 3,
205+
"successThreshold": 1,
206+
"probeAction": {
207+
"type": "HTTPGetAction",
208+
"scheme": "HTTP",
209+
"path": "/actuator/health/readiness"
210+
}
211+
}
212+
```
213+
214+
## FAQs
215+
216+
The following list shows frequently asked questions (FAQ) about using health probes with Azure Spring Apps.
217+
218+
- I received 400 response when I created applications with customized health probes. What does this mean?
219+
220+
*The error message will point out which probe is responsible for the provision failure. Be sure the health probe rules are correct and the timeout is long enough for the application to be in the running state.*
221+
222+
- What's the default probe settings for existing application?
223+
224+
*The following example shows the default settings:*
225+
226+
```json
227+
"startupProbe": null,
228+
"livenessProbe": {
229+
"disableProbe": false,
230+
"failureThreshold": 24,
231+
"initialDelaySeconds": 60,
232+
"periodSeconds": 10,
233+
"probeAction": {
234+
"type": "TCPSocketAction"
235+
},
236+
"successThreshold": 1,
237+
"timeoutSeconds": 1
238+
},
239+
"readinessProbe": {
240+
"disableProbe": false,
241+
"failureThreshold": 3,
242+
"initialDelaySeconds": 0,
243+
"periodSeconds": 10,
244+
"probeAction": {
245+
"type": "TCPSocketAction"
246+
},
247+
"successThreshold": 1,
248+
"timeoutSeconds": 1
249+
}
250+
```
251+
252+
## Next steps
253+
254+
- [Scale an application in Azure Spring Apps](how-to-scale-manual.md).

‎articles/spring-cloud/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -198,6 +198,8 @@ items:
198198
href: how-to-elastic-apm-java-agent-monitor.md
199199
- name: Analyze logs with ELK
200200
href: how-to-elastic-diagnostic-settings.md
201+
- name: Health probes and graceful termination
202+
href: how-to-configure-health-probes-graceful-termination.md
201203
- name: Network
202204
items:
203205
- name: Deploy Azure Spring Apps in a virtual network

0 commit comments

Comments
 (0)