Skip to content

Commit 9aa5752

Browse files
TimHessbart-vmware
TimHess
and
bart-vmware
authored
Changes for health groups, showcomponents and showdetails (#343)
* changes for health groups, showcomponents and showdetails * Apply suggestions from code review Co-authored-by: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> * Changes for built-in groups, other feedback * Apply suggestions from code review Co-authored-by: Bart Koelman <104792814+bart-vmware@users.noreply.github.com> * treat docfx-layer-changed as string * don't build docfx image on workflow updates * skip docfx steps instead of whole job so later jobs aren't also skipped * add missing header, k8s probes must be enabled, custom contributor output --------- Co-authored-by: Bart Koelman <104792814+bart-vmware@users.noreply.github.com>
1 parent 28d8e4a commit 9aa5752

File tree

2 files changed

+100
-61
lines changed

2 files changed

+100
-61
lines changed

‎.github/workflows/build-and-stage.yml‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,6 @@ jobs:
4444
with:
4545
filters: |
4646
docfx-layer-changed:
47-
- .github/workflows/build-and-stage.yml
4847
- 'docfx/**'
4948
metadata-layer-changed:
5049
- .github/workflows/build-and-stage.yml
@@ -76,33 +75,37 @@ jobs:
7675
build-push-docfx:
7776
name: Build and push docfx layer
7877
needs: change-detection
79-
if: ${{ needs.change-detection.outputs.docfx-layer-changed }}
8078
runs-on: ubuntu-latest
8179
steps:
8280
- name: Checkout
81+
if: ${{ needs.change-detection.outputs.docfx-layer-changed == 'true' }}
8382
uses: actions/checkout@v4
8483

8584
- name: Set DocFX version to use
85+
if: ${{ needs.change-detection.outputs.docfx-layer-changed == 'true' }}
8686
run: echo v${{ env.DOCFX_VERSION }} > docfx/version
8787
shell: bash
8888

8989
- name: Login to container registry
90+
if: ${{ needs.change-detection.outputs.docfx-layer-changed == 'true' }}
9091
uses: docker/login-action@v3
9192
with:
9293
registry: "${{ vars.DOCKER_REGISTRY }}"
9394
username: "${{ secrets.DOCKER_USERNAME }}"
9495
password: "${{ secrets.DOCKER_PASSWORD }}"
9596

9697
- name: Build image
98+
if: ${{ needs.change-detection.outputs.docfx-layer-changed == 'true' }}
9799
run: docker build docfx --file "docfx/Dockerfile" -t ${{ vars.DOCKER_REGISTRY }}/docfx:${{ needs.change-detection.outputs.docfx-image-version }}
98100

99101
- name: Push image
102+
if: ${{ needs.change-detection.outputs.docfx-layer-changed == 'true' }}
100103
run: docker push ${{ vars.DOCKER_REGISTRY }}/docfx --all-tags
101104

102105
build-push-metadata:
103106
name: Build and push API docs layer
104107
needs: [ change-detection, build-push-docfx ]
105-
if: ${{ needs.change-detection.outputs.metadata-layer-changed }}
108+
if: ${{ needs.change-detection.outputs.metadata-layer-changed == 'true' }}
106109
runs-on: ubuntu-latest
107110
steps:
108111
- name: Checkout

‎api/v4/management/health.md‎

Lines changed: 94 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ By default, the final application health state is computed by the registered `IH
1313
It is responsible for sorting out all of the returned statuses from each `IHealthContributor` and [`IHealthCheck`](https://learn.microsoft.com/dotnet/api/microsoft.extensions.diagnostics.healthchecks.ihealthcheck) and deriving an overall application health state.
1414
The built-in aggregator returns the "worst" status returned from the contributors and checks.
1515

16+
## Configure Settings
17+
1618
The following table describes the configuration settings that you can apply to the endpoint.
1719
Each key must be prefixed with `Management:Endpoints:Health:`.
1820

@@ -23,18 +25,20 @@ Each key must be prefixed with `Management:Endpoints:Health:`.
2325
| `Path` | The relative path at which the endpoint is exposed. | same as `ID` |
2426
| `RequiredPermissions` | Permissions required to access the endpoint, when running on Cloud Foundry. | `Restricted` |
2527
| `AllowedVerbs` | An array of HTTP verbs the endpoint is exposed at. | `GET` |
26-
| `ShowDetails` | The level of detail included in the response. | `Never` |
27-
| `Claim` | The claim required in `HttpContext.User` when `ShowDetails` is set to `WhenAuthorized`. | |
28-
| `Role` | The role required in `HttpContext.User` when `ShowDetails` is set to `WhenAuthorized`. | |
29-
| `Groups` | Specify logical groupings of health contributors. | |
28+
| `ShowComponents` | Whether health check components should be included in the response. | `Never` |
29+
| `ShowDetails` | Whether details of health check components should be included in the response. | `Never` |
30+
| `Claim` | The claim required in `HttpContext.User` when `ShowComponents` and/or `ShowDetails` is set to `WhenAuthorized`. | |
31+
| `Role` | The role required in `HttpContext.User` when `ShowComponents` and/or `ShowDetails` is set to `WhenAuthorized`. | |
3032

31-
The information exposed by the health endpoint depends on the `ShowDetails` property, which can be configured with one of the following values:
33+
The depth of information exposed by the health endpoint depends on the `ShowComponents` and `ShowDetails` properties, which can both be configured with one of the following values:
3234

3335
| Name | Description |
3436
| --- | --- |
35-
| `Never` | Details are never shown. |
36-
| `WhenAuthorized` | Details are shown only to authorized users. |
37-
| `Always` | Details are always shown. |
37+
| `Never` | Never shown. |
38+
| `WhenAuthorized` | Shown only to authorized users. |
39+
| `Always` | Always shown. |
40+
41+
`ShowDetails` only has an effect when `ShowComponents` is set to `Always`, or `WhenAuthorized` and the request is authorized.
3842

3943
Authorized users can be configured by setting `Claim` or `Role`.
4044
A user is considered to be authorized when they are in the given role or have the specified claim.
@@ -45,10 +49,11 @@ The following example uses `Management:Endpoints:Health:Claim`:
4549
"Management": {
4650
"Endpoints": {
4751
"Health": {
52+
"ShowComponents": "WhenAuthorized",
4853
"ShowDetails": "WhenAuthorized",
4954
"Claim": {
5055
"Type": "health_actuator",
51-
"Value": "see_details"
56+
"Value": "see_all"
5257
}
5358
}
5459
}
@@ -84,7 +89,7 @@ The configuration key `Management:Endpoints:UseStatusCodeFromResponse` can be se
8489
Clients can overrule this per request by sending an `X-Use-Status-Code-From-Response` HTTP header with the value `true` or `false`.
8590

8691
> [!TIP]
87-
> By default, health contributors for disk space, ping, liveness, and readiness are activated. They can be turned off through configuration:
92+
> By default, health contributors for disk space and ping are activated. They can be turned off through configuration:
8893
>
8994
> ```json
9095
> {
@@ -96,12 +101,6 @@ Clients can overrule this per request by sending an `X-Use-Status-Code-From-Resp
96101
> },
97102
> "Ping": {
98103
> "Enabled": "false"
99-
> },
100-
> "Liveness": {
101-
> "Enabled": "false"
102-
> },
103-
> "Readiness": {
104-
> "Enabled": "false"
105104
> }
106105
> }
107106
> }
@@ -113,28 +112,32 @@ Clients can overrule this per request by sending an `X-Use-Status-Code-From-Resp
113112
114113
This endpoint returns the top-level status, along with the details of the contributors and checks.
115114
116-
The response will always be returned as JSON, like this:
115+
The response will always be returned as JSON, and this is the default value:
116+
117+
```json
118+
{
119+
"status": "UP"
120+
}
121+
```
122+
123+
When `ShowComponents` and `ShowDetails` are set to `Always`, or when set to `WhenAuthorized` and the request is authorized, the response is more detailed:
117124

118125
```json
119126
{
120127
"status": "UP",
121-
"details": {
128+
"components": {
122129
"ping": {
123130
"status": "UP"
124131
},
125132
"diskSpace": {
126133
"status": "UP",
127-
"total": 1999599824896,
128-
"free": 1349396418560,
129-
"threshold": 10485760
130-
},
131-
"readiness": {
132-
"status": "UP",
133-
"ReadinessState": "ACCEPTING_TRAFFIC"
134-
},
135-
"liveness": {
136-
"status": "UP",
137-
"LivenessState": "CORRECT"
134+
"details": {
135+
"total": 1999599824896,
136+
"free": 1330717282304,
137+
"threshold": 10485760,
138+
"path": "C:\\source\\Repository\\src\\Project",
139+
"exists": true
140+
}
138141
}
139142
}
140143
}
@@ -164,52 +167,64 @@ Should you need to check application health based on a subset of health contribu
164167
}
165168
```
166169

167-
While group names are case-sensitive, the entries in `Include` are case-insensitive and will only activate health contributors with a matching `Id`.
168-
169-
> [!NOTE]
170-
> Adding your own health groups implicitly turns off the built-in groups for liveness and readiness. If you want to keep them, you need to include them explictly.
171-
>
172-
> To turn off the default liveness/readiness health groups without adding any of your own, configure a single-element empty group like this:
173-
> ```json
174-
> {
175-
> "Management": {
176-
> "Endpoints": {
177-
> "Health": {
178-
> "Groups": {
179-
> "": {
180-
> "Include": ""
181-
> }
182-
> }
183-
> }
184-
> }
185-
> }
186-
> }
187-
> ```
188-
> This clumsy format is used because there's no syntax in .NET Configuration to express an empty collection.
189-
> See https://github.com/dotnet/extensions/issues/1341#issuecomment-598310364 for details.
170+
While group names are case-sensitive, the entries in `Include` are case-insensitive and will only activate health contributors with a matching `Id`, and/or ASP.NET health check registrations with a matching name.
190171

191172
For any group that has been defined, you may access health information from the group by appending the group name to the HTTP request URL. For example: `/actuator/health/example-group`.
192173

174+
`ShowComponents` and `ShowDetails` can also be set at the group level, overriding the settings found at the endpoint level.
175+
176+
```json
177+
{
178+
"Management": {
179+
"Endpoints": {
180+
"Health": {
181+
"Claim": {
182+
"Type": "health_actuator",
183+
"Value": "see_all"
184+
},
185+
"Groups": {
186+
"example-group": {
187+
"Include": "Redis,RabbitMQ",
188+
"ShowComponents": "Always",
189+
"ShowDetails": "WhenAuthorized"
190+
}
191+
}
192+
}
193+
}
194+
}
195+
}
196+
```
193197

194198
### Kubernetes Health Groups
195199

196-
Applications deployed on Kubernetes can provide information about their internal state with [Container Probes](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#container-probes). Depending on your [Kubernetes configuration](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/), the kubelet will call those probes and react to the result.
200+
Applications deployed on Kubernetes can provide information about their internal state with [Container Probes](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#container-probes).
201+
Depending on your [Kubernetes configuration](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/), the kubelet will call those probes and react to the result.
197202

198-
Steeltoe provides an [`ApplicationAvailability`](https://github.com/SteeltoeOSS/Steeltoe/blob/main/src/Management/src/Endpoint/Actuators/Health/Availability/ApplicationAvailability.cs) class for managing various types of application state. Out of the box, support is provided for Liveness and Readiness, where each is exposed in a corresponding `IHealthContributor` and health group.
203+
Steeltoe provides an [`ApplicationAvailability`](https://github.com/SteeltoeOSS/Steeltoe/blob/main/src/Management/src/Endpoint/Actuators/Health/Availability/ApplicationAvailability.cs) class for managing various types of application state.
204+
Out of the box, support is provided for Liveness and Readiness, where each is exposed in a corresponding `IHealthContributor` and health group.
205+
While these health contributors are included, they are disabled by default and must be enabled in configuration (as demonstrated in the example below).
199206

200-
To change the health contributors that are included in either of the two default groups, use the same style of configuration described above. Please note that this will _replace_ the default groupings, so if you would like to _add_ an `IHealthContributor` you will need to include the original entry. These entries demonstrate including disk space in both groups:
207+
To change the health contributors that are included in either of the two built-in groups, use the same style of configuration described above.
208+
Please note that this will _replace_ these groupings, so if you would like to _add_ an `IHealthContributor` you will need to include the original entry.
209+
These entries demonstrate enabling the probes, their groups and including disk space in both groups:
201210

202211
```json
203212
{
204213
"Management": {
205214
"Endpoints": {
206215
"Health": {
216+
"Liveness": {
217+
"Enabled": "true"
218+
},
219+
"Readiness": {
220+
"Enabled": "true"
221+
},
207222
"Groups": {
208223
"liveness": {
209-
"Include": "diskSPACE,liveness"
224+
"Include": "diskSpace,livenessState"
210225
},
211226
"readiness": {
212-
"Include": "diskspace,readiness"
227+
"Include": "diskSpace,readinessState"
213228
}
214229
}
215230
}
@@ -305,13 +320,34 @@ public class ExampleHealthContributor : IHealthContributor
305320

306321
Sending a GET request to `/actuator/health` returns the following response:
307322

323+
```json
324+
{
325+
"status":"WARNING"
326+
}
327+
```
328+
329+
When `ShowComponents` and `ShowDetails` are set to `Always`, or when set to `WhenAuthorized` and the request is authorized, the response is more detailed:
330+
308331
```json
309332
{
310333
"status": "WARNING",
311-
"details": {
334+
"components": {
312335
"ExampleHealthContributor": {
313336
"status": "WARNING",
314337
"description": "This health check does not check anything"
338+
},
339+
"ping": {
340+
"status": "UP"
341+
},
342+
"diskSpace": {
343+
"status": "UP",
344+
"details": {
345+
"total": 1999599824896,
346+
"free": 1330717282304,
347+
"threshold": 10485760,
348+
"path": "C:\\source\\Repository\\src\\Project",
349+
"exists": true
350+
}
315351
}
316352
}
317353
}

0 commit comments

Comments
 (0)