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 rejected
  • pull_image (when_missing or always; 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's
  • registry_username (string; optional): with registry_password: the login for the registry named in image; a private value
  • registry_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.

  • status
  • change
  • reason
  • value.image_id
  • value.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_missing pulls an image only when the node does not have it. A rerun never replaces a running container because a tag moved. Use when_missing with tags that name one version, and with digests.
  • always asks 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.images then has a null image_id and a reason, and a docker_image task for an image the node has reports not_checked and 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_change when something else in it is certain to change, and not_checked otherwise.

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_image has no default. The choice decides whether a rerun deploys new software, so it must be on the page.
  • docker_image deletes 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.