Add HealthStatus attribute on the docker ps command #50281

mdaffad · 2025-06-28T16:42:04Z

fixes: Add container health to list containers API response for ease of monitoring #50253

- What I did
Add HealthStatus attribute for dokcer ps command

- How I did it

Add new attribute with type HealthSummary on ContainerSummary

- How to verify it

Run container with health check

# healthy status
docker run -d   --name traefik-test   --health-cmd="wget -qO- http://localhost:8080/ping || exit 1"   --health-interval=5s   --health-retries=3   traefik:v2.11   --ping
# unhealthy status
docker run -d --name test-fail   --health-cmd="exit 1"   --health-interval=3s   busybox:latest   sleep 300

Run this command curl --unix-socket /var/run/docker.sock http://localhost/containers/json | jq

- Human readable description for the release notes

`GET /containers/json` now includes a `Health` field describing container healthcheck status.

api/types/container/container.go

vvoland · 2025-07-04T16:41:41Z

Thanks!
Please rebase the branch and squash commits, see: https://github.com/moby/moby/blob/master/CONTRIBUTING.md#review

mdaffad · 2025-07-04T17:00:45Z

Updated

vvoland · 2025-07-09T09:10:17Z

api/types/container/container.go

 		NetworkMode string            `json:",omitempty"`
 		Annotations map[string]string `json:",omitempty"`
 	}
+	Health          HealthSummary


Wondering if we want to make it *HealthSummary and make it nil/null instead of the Status=none.

Thoughts?

cc @moby/moby-committers

Yes, we probably want it to be omitted for older API versions

We historically haven't bothered omitting fields in responses for older API versions since clients that don't know about them just ignore them. I don't think it's worth fussing about here, either.

I like it the way it is. Clients can trivially detect whether the daemon is capable of providing health summaries by the presence of the Health property in the response, even when the container being inspected is not running.

Based on the discussion:

If i want to support the older API versions using *HealthSummary to allow nullable value, do i need declare something like versions.LessThan(version, "1.51") or set it as null with HealthSummary json:",omitempty"? But i assume from the @corhere response, it should be ignored by the client.

Let me know if i should update to support nullable or keep it like this.

Thanks

After discussing further with the other maintainers, we have reached the consensus that the HealthSummary should be omitted entirely from responses to requests with an older API version.

Suggested change

Health HealthSummary

Health *HealthSummary `json:",omitempty"`

Responses to requests with API version >= 1.51 should unconditionally include the HealthSummary. This includes containers with no health checks configured, or containers that are not running -- respond with Status=none.

Updated with new test case for version less than 1.51

integration/container/list_test.go

mdaffad · 2025-07-09T10:21:53Z

Just want to ask. For the failed windows job https://github.com/moby/moby/actions/runs/16078201519/job/45626075880, is it a flake?

vvoland · 2025-07-09T10:29:26Z

Yes, it's a flake and not related to this PR 👍🏻

thaJeztah · 2025-07-09T11:40:14Z

api/types/container/health.go

+type HealthSummary struct {
+	Status        HealthStatus
+	FailingStreak int
+}


The type and fields could use some GoDoc / documentation here. We've not always done a good job at that, but it's an exported type, so having some docs is useful to whoever uses it.

Updated. I added comment on HealthSummary

daemon/container/view.go

api/types/container/health.go

vvoland

LGTM overall, just a linter failure that needs fixing 😅

vvoland · 2025-07-14T16:18:47Z

integration/container/list_test.go

+		for _, container := range containers {
+			if (container.Health == nil && versions.LessThan(version, "1.51")) {
+				total++
+			} else if container.Health != nil && container.Health.Status == healthStatus && versions.GreaterThanOrEqualTo(version, "1.51"){
+				total++
+			}
+		}


Linter failure (https://github.com/moby/moby/actions/runs/16223267852/job/45939842246?pr=50281#step:6:71)

integration/container/list_test.go:166:1: File is not properly formatted (gofmt) if (container.Health == nil && versions.LessThan(version, "1.51")) { ^ integration/container/list_test.go:162:10: nilness: impossible condition: nil != nil (govet) if err != nil { ^

Sorry, looks like i missed to run gofmt -s -w. Updated

Edited, re-run hack/validate/golangci-lint on dev container

thaJeztah

quick "request changes" so that we don't forget to bump the API version (we can do the actual bump in a separate PR first)

thaJeztah · 2025-07-15T15:13:45Z

integration/container/list_test.go

+		apiVersion string
+	}{
+		{apiVersion: "1.50"},
+		{apiVersion: "1.51"},


Before we merge; I think API v1.51 already shipped, so we need a version bump for v29 and move these to 1.52; https://github.com/moby/moby/blob/v28.3.2/api/common.go#L5-L6

Can i bump it to 1.52 on the different PR for this file https://github.com/moby/moby/blob/v28.3.2/api/common.go#L5-L6? Or we also need to bump on the other files at this commit
27f2e0e

Oh good catch!

I opened a PR to bump the API, you can rebase your PR once we get it in: #50418

Merged, you can rebase and adjust the API version check 👍🏻

Got it, thanks for the help! 🫡

corhere · 2025-07-16T16:32:48Z

api/types/container/health.go


+// HealthSummary stores a summary of the container's healthcheck results.
+type HealthSummary struct {
+	Status        HealthStatus // Status is one of [NoHealthcheck], [Starting], [Healthy] or [Unhealthy].


Nit: no need to enumerate the possible values in the doc comment; users are capable of following the link to HealthStatus in the go doc. And besides, the bracketed identifiers don't get rendered as links anyway, e.g.

vvoland

LGTM, thanks!

thompson-shaun · 2025-07-21T14:39:41Z

@thaJeztah - LGTY?

thaJeztah

LGTM, thanks!

Signed-off-by: Muhammad Daffa Dinaya <[email protected]> Signed-off-by: Sebastiaan van Stijn <[email protected]>

thaJeztah · 2025-07-21T20:59:01Z

DId a quick rebased after the API module PR was merged.

vvoland · 2025-07-21T21:34:19Z

vendor/github.com/moby/moby/api/swagger.yaml

+      Health:
+        type: "object"
+        description: |-
+          Summary of health status
+
+          Added in v1.52, before that version all container summary not include Health.
+          After this attribute introduced, it includes containers with no health checks configured,
+          or containers that are not running with none
+        properties:
+          Status:
+            type: "string"
+            description: |-
+              the health status of the container
+            enum:
+              - "none"
+              - "starting"
+              - "healthy"
+              - "unhealthy"
+            example: "healthy"
+          FailingStreak:
+            description: "FailingStreak is the number of consecutive failures"
+            type: "integer"
+            example: 0


Looks like the changes were included again in the vendor. Is this expected? 🤔

Yup, because we don't use the code from master, we use the module (which gets vendored) 😅

AkihiroSuda reviewed Jun 30, 2025

View reviewed changes

api/types/container/container.go Outdated Show resolved Hide resolved

vvoland added area/api API kind/feature Functionality or other elements that the project doesn't currently have. Features are new and shiny labels Jun 30, 2025

vvoland added this to the 29.0.0 milestone Jun 30, 2025

mdaffad force-pushed the 50253-add-container-health-on-containers-list-api branch from e975835 to 7b24f12 Compare July 4, 2025 16:15

mdaffad force-pushed the 50253-add-container-health-on-containers-list-api branch from 89a0f83 to e4fb1d1 Compare July 4, 2025 17:00

vvoland added the impact/changelog label Jul 9, 2025

vvoland reviewed Jul 9, 2025

View reviewed changes

integration/container/list_test.go Outdated Show resolved Hide resolved

mdaffad force-pushed the 50253-add-container-health-on-containers-list-api branch from e4fb1d1 to 012edf2 Compare July 9, 2025 10:18

thaJeztah reviewed Jul 9, 2025

View reviewed changes

mdaffad force-pushed the 50253-add-container-health-on-containers-list-api branch from 012edf2 to bc22a3f Compare July 10, 2025 09:15

corhere added this to 🔦 Maintainer spotlight Jul 10, 2025

github-project-automation bot moved this to New in 🔦 Maintainer spotlight Jul 10, 2025

thompson-shaun assigned corhere and thaJeztah Jul 10, 2025

thompson-shaun moved this from New to Complete in 🔦 Maintainer spotlight Jul 10, 2025

thompson-shaun assigned vvoland Jul 10, 2025

mdaffad force-pushed the 50253-add-container-health-on-containers-list-api branch 2 times, most recently from 0c7216d to 1017c1f Compare July 11, 2025 10:36

vvoland requested changes Jul 11, 2025

View reviewed changes

daemon/container/view.go Outdated Show resolved Hide resolved

api/types/container/health.go Outdated Show resolved Hide resolved

mdaffad force-pushed the 50253-add-container-health-on-containers-list-api branch from 1017c1f to 3b9b04a Compare July 11, 2025 15:05

mdaffad requested a review from vvoland July 11, 2025 15:05

vvoland reviewed Jul 14, 2025

View reviewed changes

mdaffad force-pushed the 50253-add-container-health-on-containers-list-api branch 2 times, most recently from a2c39b5 to 72bb671 Compare July 15, 2025 13:26

mdaffad requested a review from vvoland July 15, 2025 13:26

thaJeztah requested changes Jul 15, 2025

View reviewed changes

mdaffad force-pushed the 50253-add-container-health-on-containers-list-api branch from 72bb671 to 6507aa8 Compare July 16, 2025 13:20

mdaffad requested a review from thaJeztah July 16, 2025 13:22

corhere approved these changes Jul 16, 2025

View reviewed changes

vvoland approved these changes Jul 17, 2025

View reviewed changes

thaJeztah approved these changes Jul 21, 2025

View reviewed changes

thaJeztah added the status/4-merge label Jul 21, 2025

Add Health attribute on the docker ps command

6e7a2c8

Signed-off-by: Muhammad Daffa Dinaya <[email protected]> Signed-off-by: Sebastiaan van Stijn <[email protected]>

thaJeztah force-pushed the 50253-add-container-health-on-containers-list-api branch from 6507aa8 to 6e7a2c8 Compare July 21, 2025 20:57

vvoland reviewed Jul 21, 2025

View reviewed changes

thaJeztah merged commit b20888a into moby:master Jul 21, 2025
208 of 209 checks passed

mdaffad deleted the 50253-add-container-health-on-containers-list-api branch July 22, 2025 13:38

This was referenced Jul 23, 2025

vendor: docker/docker, moby/api, moby/client to latest docker/cli#6201

Merged

update docs, tests, local changes for "HealthCheck" in "ps" response docker/cli#6203

Open

This was referenced Aug 4, 2025

Prepare release notes for v1.52.0-alpha.0 #50625

Merged

Prepare release notes for v2.0.0-alpha.0 #50651

Closed

This was referenced Sep 5, 2025

Prepare release notes for api/v1.52.0-beta.0 #50904

Merged

Prepare release notes for v2.0.0-beta.0 #50918

Merged

dmcgowan mentioned this pull request Sep 24, 2025

Prepare release notes for api/v1.52.0-rc.0 #51030

Closed

	Health HealthSummary
	Health *HealthSummary `json:",omitempty"`

Add HealthStatus attribute on the docker ps command #50281

Add HealthStatus attribute on the docker ps command #50281

Uh oh!

Conversation

mdaffad commented Jun 28, 2025 • edited by vvoland Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

vvoland commented Jul 4, 2025

Uh oh!

mdaffad commented Jul 4, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mdaffad Jul 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

corhere Jul 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mdaffad commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vvoland commented Jul 9, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

vvoland left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thaJeztah left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mdaffad Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vvoland left a comment

Choose a reason for hiding this comment

Uh oh!

thompson-shaun commented Jul 21, 2025

Uh oh!

thaJeztah left a comment

Choose a reason for hiding this comment

Uh oh!

thaJeztah commented Jul 21, 2025

Uh oh!

vvoland Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

mdaffad commented Jun 28, 2025 •

edited by vvoland

Loading

mdaffad Jul 10, 2025 •

edited

Loading

corhere Jul 10, 2025 •

edited

Loading

mdaffad commented Jul 9, 2025 •

edited

Loading

mdaffad Jul 15, 2025 •

edited

Loading

vvoland Jul 21, 2025 •

edited

Loading