Image from "scratch" has no shell, but passing the --health-cmd to docker run uses CMD-SHELL

Description

An image that is being based on "scratch", has no shell in it. When using the HEALTHCHECK instruction in a Dockerfile, one can instruct that the healthcheck should run with CMD, not CMD-SHELL. However, when passing the --health-cmd flag to a docker run command, it will always prefix the command with CMD-SHELL. There is no way (afaik) to tell Docker to use CMD, and neither the ENTRYPOINT nor the SHELL instruction seem to influence this.

Is this a bug? Is there a known workaround? Is the solution to this missing from the documentation?

Steps to reproduce the issue:

Build an image from SCRATCH, and try to pass it a --health-cmd on docker run.

Describe the results you received:

It fails with an error, describing that the CMD-SHELL prefixed command will not run.

Describe the results you expected:

It should be possible to tell the cli that it would have to use the CMD prefixed command, so it runs in the same way as a CMD prefixed HEALTHCHECK in the Dockerfile or a healthcheck in the compose.yaml file would run.

Additional information you deem important (e.g. issue happens only occasionally):

I reported this issue moby/moby#43843, but got redirected to this repository. The issue came up when trying to add an optional healthcheck in the Dozzle container, as mentioned in amir20/dozzle#1814

Output of docker version:

Client:
 Version:           20.10.7
 API version:       1.41
 Go version:        go1.16.8
 Git commit:        v20.10.7
 Built:             Thu Jan  1 00:00:00 1970
 OS/Arch:           linux/amd64
 Context:           default
 Experimental:      true

Server:
 Engine:
  Version:          20.10.7
  API version:      1.41 (minimum version 1.12)
  Go version:       go1.16.8
  Git commit:       v20.10.7
  Built:            Tue Jan  1 00:00:00 1980
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          v1.5.7
  GitCommit:        v1.5.7
 runc:
  Version:          1.0.0-rc95
  GitCommit:        
 docker-init:
  Version:          0.18.0
  GitCommit:

Output of docker info:

Client:
 Context:    default
 Debug Mode: false
 Plugins:
  buildx: Build with BuildKit (Docker Inc., 0.0.0+unknown)

Server:
 Containers: 22
  Running: 3
  Paused: 0
  Stopped: 19
 Images: 1619
 Server Version: 20.10.7
 Storage Driver: overlay2
  Backing Filesystem: extfs
  Supports d_type: true
  Native Overlay Diff: true
  userxattr: false
 Logging Driver: journald
 Cgroup Driver: systemd
 Cgroup Version: 2
 Plugins:
  Volume: local
  Network: bridge host ipvlan macvlan null overlay
  Log: awslogs fluentd gcplogs gelf journald json-file local logentries splunk syslog
 Swarm: inactive
 Runtimes: io.containerd.runtime.v1.linux runc io.containerd.runc.v2
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: v1.5.7
 runc version: 
 init version: 
 Security Options:
  seccomp
   Profile: default
  cgroupns
 Kernel Version: 5.10.88
 Operating System: NixOS 21.05 (Okapi)
 OSType: linux
 Architecture: x86_64
 CPUs: 8
 Total Memory: 15.31GiB
 Name: nixos
 ID: JMBO:UXHB:WA6C:HFWI:6W5O:I5PW:L3NR:TEZN:TNZQ:7VRJ:NFXS:4CYG
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 Registry: https://index.docker.io/v1/
 Labels:
 Experimental: false
 Insecure Registries:
  127.0.0.0/8
 Live Restore Enabled: true

Additional environment details (AWS, VirtualBox, physical, etc.):

NixOS

Any updates on this?

Bump for this...

Is there anything new about this?

Right, the CLI always uses the CMD-SHELL form:

cli/cli/command/container/opts.go

Line 560 in 2c35778

probe = []string{"CMD-SHELL", copts.healthCmd}

Not sure what's the best UX for this, but perhaps we could have a --health-test that would directly translate to the Test parameter of the health config in the API:

https://github.com/moby/moby/blob/47ee8a0485ef214cdb938661c1f5c154ebf1190c/api/swagger.yaml#L803-L817

I don't think we have a bandwidth to work on this now, but if anyone would contribute a PR with a proposal.. We would be happy to review and discuss!

Related;

fix: add busybox as base image

I guess if time could be rolled back, the ideal way of achieving this would be to treat --health-cmd as CMD and --health-cmd-shell as CMD-SHELL.

However, I suppose this would be a big breaking change nowadays. If that cannot be achieved, then I think the next best thing would be to keep --health-cmd the way it is and add something along the lines of --health-cmd-no-shell or --health-cmd-exec to handle it like CMD does.

As I understand this issue, this is purely a limitation of the CLI, right?

I stumbled upon this when trying to use https://github.com/paketo-buildpacks/health-checker.

Opened #7008 — adds --health-cmd-exec so --health-cmd can use the exec (CMD) healthcheck form instead of always wrapping in CMD-SHELL.

Example for scratch images:

docker run --rm --health-cmd=/healthcheck --health-cmd-exec my-scratch-image

--health-cmd behavior is unchanged (still CMD-SHELL by default). Happy to adjust the flag name or UX if maintainers prefer --health-test or another approach from the thread.

Opened https://github.com/docker/cli/pull/XXXX — adds --health-cmd-exec so --health-cmd can use the exec (CMD) healthcheck form instead of always wrapping in CMD-SHELL.

Example for scratch images:
docker run --rm --health-cmd=/healthcheck --health-cmd-exec my-scratch-image
--health-cmd behavior is unchanged (still CMD-SHELL by default). Happy to adjust the flag name or UX if maintainers prefer --health-test or another approach from the thread.

PR number is wrong / placeholder

container: add --health-cmd-exec for CMD healthcheck form

container: add --health-cmd-mode for CMD healthcheck form

Navigation Menu

Repository navigation

Image from "scratch" has no shell, but passing the --health-cmd to docker run uses CMD-SHELL #3719

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Image from "scratch" has no shell, but passing the --health-cmd to docker run uses CMD-SHELL #3719

Description

Activity

saltydk commented on Jan 7, 2024

saschabrockel commented on Mar 26, 2024

durcon commented on Feb 10, 2025

vvoland commented on Feb 13, 2025

thaJeztah commented on Feb 13, 2025

andrebrait commented on Apr 13, 2026

sdavids commented on Apr 20, 2026

lohitkolluri commented on May 26, 2026

andrebrait commented on May 26, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions