docker_image
docker_image makes sure that the node has one Docker image, pulled from a
registry. An image is a packaged filesystem. Docker uses the image as
the starting filesystem for an application's container, the environment
where Docker runs the application. A registry is the server that images
are pulled from. The module runs on the node and drives the docker command
that is installed there.
- docker_image:
image: registry.example.com/audio/converter:3.1
pull_image: when_missing
Use docker_image for a container that a systemd unit runs with
docker run, written with systemd_unit and systemd_service like any
other service, and for an image that a scheduled job starts later with
docker run. The containers of a Compose project get their images from
docker_compose_project itself, which pulls
them. Run containers
shows both ways.
image is an image reference with a tag or a digest, such as
registry.example.com/audio/converter:3.1. A reference without either is
rejected. A reference that names no registry, such as postgres:17.2, means
Docker Hub. pull_image says whether a rerun follows a tag that its
publisher moved:
newer images under the same tag
says what when_missing and always do, and what a dryrun asks the
registry, for both Docker modules.
docker_image never removes an image; see
Clean up unused images on a timer.
Set up
docker_image needs the docker command and a Docker daemon that answers.
docker_image does not need the Compose plugin, the extension that adds
docker compose to the docker command.
Set up
on the page of docker_compose_project has the node tasks that install
Docker, and says what docker_image and docker_compose_project tasks do
when Docker is missing.
Inputs
image(string; required): the image reference with a tag or a digest, such as registry.example.com/audio/converter:3.1; a reference without either is rejectedpull_image(when_missingoralways; required): no default; when_missing pulls only when the node does not have the image, so a rerun never follows a tag that moved; always asks the registry on every run which image the reference names now and pulls it when it differs from the node'sregistry_username(string; optional): with registry_password: the login for the registry named in image; a private valueregistry_password(string; optional): with registry_username; a private value, normally a secret; it reaches docker through a private directory under /run that the task removes, never through a command line or an account's home directory; a secret in the login does not hide the task's result: MMX shows [redacted] wherever a text of the result holds the secret
Outputs
The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.
statuschangereasonvalue.image_idvalue.previous_image_id
What a dryrun reports
Pulls nothing and writes no login; reports would_change for an image the node does not have; with pull_image: always it asks the registry which image the reference names now without downloading it, with the task's own login only, and reports would_change with both image IDs and, in reason, the digest under which the registry serves the image when that differs from the node's, or not_checked with the error when the registry does not answer, and then predicts no restart of a service that follows an image the node has; when the reference names a list of images for several platforms, the registry serves another list, and the node's Docker uses the classic image store, it reports not_checked and predicts no restart of a service that follows the image, because it cannot see whether the image for the node's platform changed; value.image_id is null where it is known only after the pull: on a node whose Docker uses the classic image store, and for a missing image with when_missing whose reference has a tag; not_checked while the docker command or the Docker daemon is missing.
Retries and time limits
Bounded automatic retries by default; retry: false turns them off.
The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.
Examples
One image for a container that systemd runs
- task_block:
id: audio_converter
changes:
- docker_image:
image: registry.example.com/audio/converter:3.1
pull_image: when_missing
registry_username: "{{ .vars.registry_username }}"
registry_password: "{{ .secrets.registry_password }}"
- systemd_unit:
name: audio-converter.service
content: |
[Unit]
Requires=docker.service
After=docker.service
[Service]
ExecStartPre=-/usr/bin/docker rm --force audio-converter
ExecStart=/usr/bin/docker run --rm --name audio-converter registry.example.com/audio/converter:3.1
ExecStop=/usr/bin/docker stop audio-converter
Restart=always
[Install]
WantedBy=multi-user.target
activate:
- systemd_service:
name: audio-converter
state: running
start_at_boot: true
On the node, MMX first pulls the image if the node lacks the image, using
the login for registry.example.com. The systemd_unit task installs
audio-converter.service, and the systemd_service task starts and enables
it. When a later run pulls an image with another ID, the systemd_service
task restarts the service; How it works says why. To wait
until the container's own health check reports healthy, add a wait_for task
with docker_container_is_healthy: audio-converter in verify; see
Wait until a container is healthy.
The login reaches Docker without a password on a command line, in an account's home directory, or on a disk; logins for private registries says how.
Clean up unused images on a timer
Old images fill the disk. MMX deletes none by itself. A
docker_unused_images node task deletes unused
images once, such as in a one-time playbook. A timer deletes unused images
on a schedule:
- task_block:
id: docker_image_cleanup
changes:
- systemd_unit:
name: docker-image-cleanup.service
content: |
[Service]
Type=oneshot
ExecStart=/usr/bin/docker image prune --all --force --filter until=168h
- systemd_unit:
name: docker-image-cleanup.timer
content: |
[Timer]
OnCalendar=Sun 04:00
Persistent=true
[Install]
WantedBy=timers.target
activate:
- systemd_service:
name: docker-image-cleanup.timer
state: running
start_at_boot: true
Every Sunday at 04:00 the node deletes the images that no container uses and that are older than seven days. Docker's image stores are the systems Docker uses to keep images on the node: classic and containerd. With Docker's classic image store, the seven days count from when the image was built. With the containerd image store, which a new installation of Docker 29 uses, an image that came onto the node within the last seven days stays, however long ago it was built.
How it works
The task is unchanged when the node has the image and, with always, the
registry still names the same image for the reference. Its result has
value.image_id and value.previous_image_id, which is null when the node
did not have the image. They are the IDs that docker image inspect reports
on the node.
In the changes of a node task block, the image ID is a
tracked input of the
block, like the version of an installed package: the systemd_service task
in activate restarts the service when the image ID differs from the one the
service last started with. That also holds when the run that pulled the
image stopped before the restart: the next run finds the image unchanged and
still restarts the service once. A dryrun predicts the restart.
Newer images under the same tag
An image is the packaged filesystem a container starts from. A
registry is the server that images are pulled from. An image reference
such as registry.example.com/shop/web:2.4 names the registry, the image,
and a tag. Whoever publishes an image can move a tag to a newer image; a
digest (@sha256:...) names exactly one image forever.
Most projects name an image by a tag that its publisher moves, such as
latest or 17. Whether a rerun deploys the newer image is a required
choice on the task, pull_image on docker_image and pull_images on
docker_compose_project:
when_missingpulls an image only when the node does not have it. A rerun never replaces a running container because a tag moved. Usewhen_missingwith tags that name one version, and with digests.alwaysasks the registry on every run which image each reference names now, pulls an image that differs from the node's, and recreates the containers of that image. The task reports changed and lists each pulled image with its previous and its new image ID.
With always, an unchanged project and an unchanged registry give an
unchanged rerun.
A dryrun with always asks the registry the same question without
downloading the image. When the registry names another image than the node
has, the dryrun reports would_change, the service it would recreate, and
the image with previous_image_id and image_id. When the registry does not
answer, the task reports not_checked with the error, and a docker_image
task predicts no restart of a service that follows an image the node has. A
dryrun with when_missing reports would_change only for an image the node
does not have.
An image for several platforms. Most public images, Docker's official
images among them, are a list of images under one tag: one image for each
platform, such as linux/amd64 and linux/arm64. The registry's answer
names the list. The list changes whenever the image for any platform is
rebuilt, and the answer does not say whether the image for this node's
platform is among them. So when the registry serves another list than the
node's image came from, a dryrun does not claim what it cannot see:
- A service of a Compose project that uses the image, and whose container
already exists, reports the action
not_checked, with a reason that says so. - With the classic image store, the pull may change nothing on the node. The
image's entry in
value.imagesthen has a nullimage_idand areason, and adocker_imagetask for an image the node has reportsnot_checkedand predicts no restart of a service that follows it. With the containerd image store, the image ID is the list's digest, so the dryrun reports the new ID. - The task reports
would_changewhen something else in it is certain to change, andnot_checkedotherwise.
A run pulls. With the classic image store, the image and the containers change only if the image for the node's platform changed. With the containerd image store, the image gets the new ID, and Compose decides about the containers: Compose 5 keeps a container when the image for the container's platform has not changed. Compose 2.40 recreates a container even when the image for the container's platform has not changed. A reference that names one image has no such doubt: another digest is another image. To deploy exactly what you tested, name the image by its digest.
The image ID. image_id and previous_image_id are the IDs that
docker image inspect reports on the node. The two image stores name an
image differently. The containerd image store, which a new installation of
Docker 29 uses, names it by the digest of its manifest, the digest under
which a registry serves it. The classic store, which older versions and
upgraded installations use, names it by the digest of the image's
configuration.
What a dryrun knows of an image it would pull. With the containerd image
store, the new image ID is the digest under which the registry serves the
image, so the dryrun reports it. With the classic store, Docker learns the ID
only with the pull: image_id is null in the dryrun, the task's reason
names the registry's digest, and a later node task that reads
value.image_id of a docker_image task is not checked. With
when_missing, a dryrun does not ask the registry, and image_id of an
image it would pull is null too. The exception is a reference with a digest
on a node with the containerd image store: the digest is the image ID, so
the dryrun reports it without asking the registry.
How MMX asks the registry. A dryrun asks the Docker daemon on its Unix
socket which image a reference names (GET /distribution/<reference>/json,
the request docker pull starts with). The daemon asks the registry with its
own settings: which registries it trusts without TLS, their certificates, and
its proxy. The daemon downloads no image layer. A run asks nobody
beforehand: docker pull, or docker compose up --pull always, pulls what
differs.
Logins in a dryrun. A dryrun asks with the task's own login only; a
login saved on the node with docker login does not count. For a private
image without a login on the task, the dryrun reports not_checked with the
registry's refusal, and the reason says that registry_username and
registry_password (registry_logins for a Compose project) on the task let
the dryrun check.
Modules that rely on this section: docker_image and
docker_compose_project.
Errors and what they mean
Every reason starts with docker_image.
| The reason holds | What the reason means, and what to do |
|---|---|
the program docker is not installed, the Docker daemon does not answer (...) |
Docker is missing or not started. The task is not tried again; a dryrun reports the docker_image task not_checked. See Set up. |
docker_image needs pull_image: when_missing or always |
pull_image has no default. Set pull_image to when_missing or always. |
set registry_username and registry_password together, or omit registry_username and registry_password |
The task has only registry_username or only registry_password. Write registry_username and registry_password together, or omit registry_username and registry_password. |
docker pull ... succeeded, but Docker still reports no image under the requested reference |
Docker reported success and has no image under the reference. Check the reference with docker image ls on the node. |
In a dryrun: the docker command reaches the Docker daemon at ...; MMX can ask a registry without downloading only through a Docker daemon on a Unix socket on the node |
The docker command uses a daemon on another address, such as a TCP address. A dryrun with pull_image: always cannot ask the registry. |
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10.
The suite tests/integration/docker_containers.py covers docker_image
together with docker_compose_project, on the distributions and Docker
versions that the page of docker_compose_project
lists.
Why it works this way
pull_imagehas no default. The choice decides whether a rerun deploys new software, so it must be on the page.docker_imagedeletes no image. Deleting is a separate, explicit node task,docker_unused_images, or a schedule, not a side effect of a run. An image that a rollback needs tomorrow must not vanish because today's run no longer names it.
This page is docs/reference/modules/docker_image.md in the MMX repository.