Proposal: Add Health Check Support in nerdctl

[subashkotha]

Hello,

We’d like to propose adding support for container health checks in nerdctl, similar to Docker’s health check functionality via Dockerfile, Compose, and CLI flags.

This feature would allow users and downstream clients like Finch to define and monitor application-level health of containers, enabling use cases such as container restarts on failure, basic orchestration, and service monitoring.

The attached PDF includes the detailed proposal plan. Looking forward to feedback and discussion!

Thanks!
Health Check Support in Nerdctl – Proposal.pdf

Previous discussion - #3149

cc @AkihiroSuda @djdongjin

[AkihiroSuda]

nerdctl healthcheck run

This doesn't seem consistent with Docker.
The podman-style command can be added too, but I don't see why we have to avoid the docker-style behavior.

systemd timer

Depending on systemd is the last resort, as not every distro uses systemd.

As discussed before, the feature is similar to https://github.com/containerd/containerd/blob/v2.0.4/plugins/restart/monitor.go and could be implemented as another monitor plugin.

However, embedding application-level health checks directly within ContainerD might not be ideal.
ContainerD’s primary
responsibility is managing container lifecycles and providing low-level telemetry . Implementing detailed, application-specific health checks within ContainerD could complicate its core responsibilities and might duplicate capabilities better handled by higher-level systems.

Healthchecking doesn't seem so high-level. Same as the restart monitor,

Requires buy-in from containerd maintainers to upstream these changes, which may add delays to adoption.

FYI: containerd v2.1 will be released relative soon: May 7
Feature-freeze will happen 2-4 weeks before that date.

containerd v2.2 is planned to be released 6 months after v2.1.

containerd will need to be aware of docker specific image schema to support image health configs.

Why? The restart monitor isn't aware of the image schema, so the story should be same for healthchecking too?

[subashkotha]

Thanks for getting back.

Supporting health checks defined in Docker-built images would require containerd to recognize and parse Docker-specific extensions to the image schema, specifically the Healthcheck field embedded in the image config. The restart monitor, by contrast, operates independently of the image schema and relies solely on runtime task events like exit codes. Since the OCI image specification does not standardize health check configuration, containerd currently does not unmarshal this data. Enabling support would require either diverging from OCI compliance or introducing special-case handling for Docker-specific fields.

[AkihiroSuda]

introducing special-case handling for Docker-specific fields.

It should be fine, as containerd natively supports Docker Schema2
https://github.com/search?q=repo%3Acontainerd%2Fcontainerd%20schema2&type=code

[AkihiroSuda]

We should also consider proposing HEALTHCHECK to OCI

• "Healthcheck" for image config opencontainers/image-spec#749

[AkihiroSuda]

HEALTHCHECK isn't likely going to be accepted in OCI, so feel free to submit a PR to implement the feature on nerdctl side with a dependency on systemd timer.

[AkihiroSuda]

nerdctl healthcheck run

This doesn't seem consistent with Docker.
The podman-style command can be added too, but I don't see why we have to avoid the docker-style behavior.

ping @subashkotha @estesp