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.

[subashkotha]

Docker's health checks are daemon-driven, allowing it to internally manage scheduling and execution using docker exec. Since nerdctl doesn't have a persistent daemon, we rely on an external scheduler - systemd in our proposed approach to trigger the health checks.

In this setup, the nerdctl healthcheck run command acts as the entry point - when invoked it runs the health check cmd configured and updates the health check result. So while the scheduling mechanism differs from Docker, the functionality is preserved.

[AkihiroSuda]

Thanks, SGTM assuming that the command is not expected to be invoked manually

[AkihiroSuda]

@subashkotha Do you plan to submit a PR soon?

nerdctl v2.1 is planned to be released right after containerd v2.1 (May 7)
https://github.com/containerd/containerd/blob/main/RELEASES.md#current-state-of-containerd-releases

[subashkotha]

Thanks for the heads-up! We won’t be able to submit the PR before May 7. The implementation is in progress, but it needs a bit more time.

Also, could you please assign Issue #4157 to me? I’ll be driving this feature forward.

[yuntianfeijing]

I hope to see the status of the health check in the output of the nerdctl inspect and nerdctl ps commands.