skip to content

Health Status, Aggregation & show-details

4 roadmaps5 questions

Statuses are ordered and aggregated into one overall status, mapped to an HTTP code, with details shown never, always or only to authorized callers. Interviewers ask why details are hidden by default, and information disclosure is the reason.

part ofSpring Frameworkoverview, primer and where to startread it →
on this pageshow

explore

questions

5

In Spring Boot Actuator, what does management.endpoint.health.show-details control, and what are its three possible values?

level: juniorimportance: must knowfreq 70%

answer

  1. never / when-authorized / always
  2. default = never (secure by default)
  3. when-authorized + roles property
  4. show-components inherits show-details
  5. details can leak DB/disk info

basics

~10 s

It controls how much detail /actuator/health shows. Values: never (default, only overall status), when-authorized (details shown to logged-in/authorized users), and always (details shown to everyone).

solid answer

~30 s

management.endpoint.health.show-details decides whether the /actuator/health endpoint returns just the aggregated overall status, or also the per-contributor breakdown (component names, statuses, and detail maps like disk space or DB info). The three values are: never (the default) shows only {"status":"UP"}; always shows the full details to any caller; when-authorized shows details only to authenticated users, optionally restricted to roles listed in management.endpoint.health.roles. The default is never precisely because health details (DB URLs, disk paths, error messages) can leak sensitive infrastructure information to anonymous callers, so you must opt in.

code

yaml · 10 lines
yaml
management:
  endpoint:
    health:
      show-details: when-authorized   # never | when-authorized | always
      roles: ADMIN                     # only ADMINs see the breakdown
      show-components: when-authorized  # optional; defaults to show-details
  endpoints:
    web:
      exposure:
        include: health

go deeper

for a junior

Know the three values and that never is the default.

for a middle

Explain the security rationale and the roles property.

for a senior

Contrast with show-components and describe the anonymous-vs-authenticated behavior of when-authorized.

for a principal

Tie show-details to threat modeling of health-endpoint information disclosure and probe design.

**What the health endpoint returns.** Spring Boot Actuator exposes `/actuator/health`. Internally, many `HealthContributor` beans (each a `HealthIndicator`) report their own `Health` — a `Status` (UP/DOWN/etc.) plus an optional map of details (e.g. the `DiskSpaceHealthIndicator` reports free/total bytes, `DataSourceHealthIndicator` reports the validation query result). Actuator aggregates all contributor statuses into one overall status. **What show-details does.** The property `management.endpoint.health.show-details` decides how much of that is serialized in the HTTP response body: - `never` (the **default**): the response is just the overall status, e.g. `{"status":"UP"}`. No component names, no detail maps. - `always`: the full nested breakdown is returned to **every** caller, including anonymous ones — component names, each component's status, and each component's details. - `when-authorized`: details are returned **only** when the request comes from an authenticated principal. You can further require specific roles via `management.endpoint.health.roles` (a comma-separated list); if that list is set, the user must hold at least one of those roles, otherwise only the overall status is shown. **Why the default is `never`.** Health details frequently contain sensitive infrastructure data: database connection info, disk paths, broker addresses, exception messages. Exposing these to anonymous callers is an information-disclosure risk, so Spring is secure-by-default and forces you to opt in. **Related property: show-components.** `management.endpoint.health.show-components` controls whether the **names** of components are listed (without necessarily their full detail maps). If not set explicitly, it inherits the value of `show-details`. It takes the same three values (never/when-authorized/always). This lets you, for example, reveal that a `db` and `diskSpace` component exist and their statuses, while still hiding deeper detail maps — though the common case is to leave show-components unset and let it follow show-details. **Interaction with security.** `when-authorized` requires Spring Security to be present so Actuator can inspect the current `Principal`/authorities. Without a SecurityContext, `when-authorized` behaves like `never` for anonymous requests. **When to use which.** Use `never` for a health check consumed only by a load balancer / Kubernetes probe (they only need the status code / overall status). Use `when-authorized` when operators need the breakdown but you don't want anonymous exposure. Use `always` only in trusted/internal networks or non-sensitive setups.

  • With show-details=when-authorized and no roles configured, who sees the details?
    Any authenticated user. The roles property only narrows it further — if roles is empty/unset, being authenticated is sufficient; anonymous callers still get only the overall status.
  • Why is never the default rather than always?
    Security-by-default: component detail maps can contain sensitive infrastructure data (DB URLs, disk paths, exception text), so Spring forces an explicit opt-in before exposing them.

saying these in an interview costs you the question

  • Saying the default is always (it is never)
  • Thinking show-details changes the HTTP status code (it only changes the body detail)
  • Believing when-authorized needs no Spring Security to evaluate the principal

context

resolving links…

open as a page

What is the HttpCodeStatusMapper, and what HTTP status codes does /actuator/health return by default for each health status?

level: middleimportance: should knowfreq 50%

basics

~10 s

The HttpCodeStatusMapper maps a health Status to an HTTP status code. By default DOWN and OUT_OF_SERVICE return 503 (Service Unavailable); UP and UNKNOWN return 200 OK. You customize it via management.endpoint.health.status.http-mapping.

open as a page

How does Spring Boot compute the single overall health status from many contributors, and how is the severity ordering configured?

level: middleimportance: should knowfreq 55%

basics

~10 s

A StatusAggregator (default SimpleStatusAggregator) picks the most severe status among all contributors. The default order (most to least severe) is DOWN, OUT_OF_SERVICE, UP, UNKNOWN. You can override it with management.endpoint.health.status.order.

open as a page

How do you register a custom health Status (e.g. FATAL) and wire it correctly into severity ordering and HTTP mapping?

level: seniorimportance: should knowfreq 35%

basics

~10 s

Create a new Status("FATAL") and return it from a HealthIndicator via Health.status(...). Then add FATAL to management.endpoint.health.status.order so it's ranked correctly, and to status.http-mapping so it returns the right HTTP code.

open as a page

Design a production health endpoint strategy covering aggregation severity, HTTP mapping for probes, and safe detail exposure. What are the trade-offs and pitfalls?

level: principalimportance: nice to knowfreq 20%

basics

~20 s

Keep show-details at never or when-authorized to avoid leaking infra data; let DOWN/OUT_OF_SERVICE map to 503 so load balancers and probes react; configure status.order and http-mapping consistently for any custom status; and separate liveness from readiness so transient dependency failures don't kill pods.

open as a page