podman_image
podman_image makes sure that the node has one Podman image, pulled from a
registry, the server that images are pulled from. Podman is a program that
runs containers. An image is the packaged filesystem a container starts
from. The image goes into the system's (root's) image store, or with
in_image_store_of_user_account into an ordinary account's own image store.
The module runs on the node and drives the podman command installed on the
node.
- podman_image:
image: registry.example.com/shop/web:2.4
pull_image: when_missing
A container that podman_quadlet declares starts from
the image. Pull the image with podman_image in the same node task block as
the Quadlet file: the container's service then restarts when a run pulls
another image, and a private image needs no registry login in the generated
service.
image is a full image reference: registry, image name, and a tag or a
digest, such as registry.example.com/shop/web:2.4. A reference without a
registry, such as nginx:1.27, is rejected, because Podman would have to
guess the registry.
podman_image never removes an image. The example project
examples/podman-host installs a systemd timer
that deletes unused images once a week; Set up on
the page of podman_quadlet shows its node tasks.
Set up
podman_image needs Podman on the node. A dryrun of a podman_image task
with pull_image: always also needs skopeo on the node. The program
skopeo is a separate package on every distribution.
Set up on the page of podman_quadlet has the
node tasks that install Podman and skopeo, and says what a task does when
Podman is missing. A run needs only Podman.
Inputs
image(string; required): a full image reference: registry, image name, and a tag or a digest, such as registry.example.com/shop/web:2.4; a reference without a registry, such as nginx:1.27, is rejected, because Podman would have to guess the registrypull_image(when_missingoralways; required): no default: when_missing pulls only when the store does not have the image, so a rerun never follows a tag that moved; always asks the registry on every run and pulls when the reference points to another imageregistry_username(string; optional): the login for the registry named in image; both registry_username and registry_password, or neitherregistry_password(string; optional): a private value, normally a secret; it reaches Podman through a file under /run that only the account that runs Podman can read and that MMX removes after the task, never a command line or a home directory; with in_image_store_of_user_account that account runs Podman, so it can read the password while the task pulls; a secret in the login does not hide the task's result: MMX shows [redacted] wherever a text of the result holds the secretin_image_store_of_user_account(string; optional): an account other than root: the image goes into that account's own image store, which the account's containers use, and MMX turns on lingering for the account so that its services start at boot and keep running after logout; without it, the system's (root's) store
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; when_missing reports would_change for an image the store does not have; always asks the registry with skopeo, without downloading the image: unchanged when the store's image is the one the registry serves for the node's platform now, would_change with both image IDs when not, and not_checked when the registry cannot be reached, skopeo is not installed, or only a pull can say whether the image differs (an image with zstd:chunked layers that the registry serves under another digest than the store's image came under); a not_checked result names the store's image as value.previous_image_id and predicts no restart of a service that follows an image the store has.
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
Pull the image of a system container
- task_block:
id: shop_web
changes:
- podman_image:
image: registry.example.com/shop/web:2.4
pull_image: when_missing
- podman_quadlet:
name: shop-web.container
content: |
[Container]
ContainerName=shop-web
Image=registry.example.com/shop/web:2.4
[Install]
WantedBy=multi-user.target
activate:
- systemd_service:
name: shop-web.service
state: running
On the node, in order: MMX pulls the image into the system's store if the
store does not have it, installs the Quadlet file, and the systemd_service
task starts shop-web.service. The image ID is a tracked input of the node
task block: when a later run pulls another image, the systemd_service task
restarts the service, and the restart uses the new image.
Run a container from a Quadlet file
is the whole example.
Pull into an ordinary account's image store
- user:
name: shop
system: false
home: /home/shop
create_home_directory: true
- podman_image:
image: registry.example.com/shop/web:2.4
pull_image: when_missing
in_image_store_of_user_account: shop
Each account that runs containers has its own image store, separate from
root's. A container that runs under in_systemd_of_user_account: shop needs
its image pulled with in_image_store_of_user_account: shop.
Containers of an ordinary account
shows the container that uses the image in the account shop's store, and
what the account needs.
Follow a moved tag from a private registry
- podman_image:
image: registry.example.com/shop/web:stable
pull_image: always
registry_username: deploy
registry_password: "{{ .secrets.registry_password }}"
A tag such as stable can be moved to a newer image by the image's
publisher. With pull_image: always, each run asks the registry and pulls
when the reference names another image than the store has. MMX passes the
registry username and password to Podman through a private file that MMX
removes after the task. See
How it works.
How it works
when_missing and always
pull_image says whether a rerun follows a moved tag:
when_missingpulls only when the store does not have the image. A rerun asks the registry nothing and never replaces an image because a tag moved. Usepull_image: when_missingwith tags that name one version, and with digests.alwaysasks the registry on every run and pulls when the reference names another image than the store has.
The task is unchanged when the store has the image and, with always, the
registry still points the reference at it. A reference with a digest names
one image forever. For such a reference MMX asks the registry only when the
store does not have the image, also with pull_image: always.
The result and the tracked input
The result's value has image_id and previous_image_id, each as
sha256: and the 64 hexadecimal digits that Podman prints, or null when
there is none. In a node task block's changes, the image ID is a
tracked input: the
block's systemd_service task restarts its service when the ID differs from
the image ID the service started with. The block's systemd_service task
also follows image IDs from docker_image.
What a dryrun compares
A dryrun pulls nothing. With when_missing it reports would_change for a
missing image. With always it asks the registry which image the reference
names now for the node's platform, without downloading the image, and it
never reports a change that a run would not make. A registry serves each
image under a digest, and Podman records that digest with the image it
pulls (RepoDigests). The store's image is the registry's image in three
cases:
- Podman recorded it under the digest of what the registry serves under the reference now: the manifest, or the list for several platforms.
- Podman recorded it under the digest of the manifest for the node's platform. A registry changes its list when another platform's image is built again, and keeps this platform's image; a pull then leaves the image as it is.
- It has the image ID that this manifest names (the digest of the image's configuration). That covers an image without a recorded digest, such as one built on the node.
Then the dryrun reports unchanged; otherwise it reports would_change with
both IDs. For the question it runs skopeo inspect --raw, which reads the
registry settings, certificates, and logins that Podman reads.
The dryrun reports not_checked with the reason in three cases:
- skopeo is not installed. The reason names the package.
- The registry does not answer.
- Only a pull can say whether the image differs. That is an image whose
layers are in the zstd:chunked format and that the registry now serves
under another digest than the store's image came under. For a store
without the image it reports
would_changeand no image ID.
A dryrun claims only what a run would do. When the task is not_checked
and the store has the image, the result names that image as
previous_image_id, and the dryrun predicts no change of the tracked input,
so no restart of a service that follows the image: a run may find the same
image. When the store does not have the image, a pull is certain, and the
dryrun predicts the restart.
The login
The login reaches Podman through a file in the
node task's private directory
in /run/mmx/private_task_directories/, which only the account that runs
Podman can open. MMX removes the directory after the task, also when the task
fails. The password is on no command line and in no home directory. With
in_image_store_of_user_account, the account named by the setting runs
Podman, so the named account can read the registry password while the task
pulls. As the playbook author, give the task registry credentials you allow
the named account to read.
MMX hands registry_username and registry_password only to Podman and, in
a dryrun, to skopeo as a login. A secret in the registry login inputs
therefore does not hide the task's result. The result shows the image IDs,
and a failure shows the reason, such as the registry's refusal of the login.
If the result's text contains the secret, MMX replaces the secret with
[redacted].
A login does not hide a node task's result
has the rule, and the cases in which the result is still hidden.
An account's image store and lingering
With in_image_store_of_user_account, podman_image turns on lingering for
the account when it is off, and says so, as a podman_quadlet task with
in_systemd_of_user_account does: the account's services then start at boot
and keep running after logout. podman_image needs lingering before it can
read the account's image store. When the task then fails, its reason says
that lingering was turned on. With retry, the reason of the first try says
it, and the task's result reports changed. The account needs a home
directory and ranges of sub-user and sub-group IDs, as
the account's own systemd on
the page of podman_quadlet says.
Errors and what they mean
Every reason starts with podman_image.
| The reason holds | What the reason means, and what to do |
|---|---|
the program podman is not installed; install Podman in an earlier node task |
See Set up. A dryrun reports the task not_checked. |
the systemd of account shop does not run, so the account has no runtime directory ... for Podman; start it with systemctl start user@<uid>.service |
The account's systemd is not running although lingering is on. Start the account's systemd as the message says. |
podman pull ... succeeded, but ... does not have the image |
Podman reported success, and the store has no image under the reference. Check the reference with podman image ls on the node, as the account when the task names one. |
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10.
The suite tests/integration/podman_containers.py covers podman_image
together with podman_quadlet, on the distributions and Podman versions that
the page of podman_quadlet lists. On Debian
12, whose Podman has no Quadlet, podman_image works.
Not verified: an image for several platforms pulled with Podman from a registry; Go tests cover it against a stand-in. An image from a public registry with its own login service, such as Docker Hub or GitHub's registry; the suite pulls from a test image registry on the guest.
Why it works this way
pull_imagehas no default. Thepull_imagesetting decides whether a rerun deploys new software, so everypodman_imagetask must setpull_imageexplicitly.- A reference must name its registry. Podman would otherwise have to guess the registry.
- The dryrun asks with skopeo. Podman has no command that asks a
registry without pulling:
podman manifest inspectleaves out the image ID for a single-platform image from Podman 5 on. Podman's own API also omits the image ID for a single-platform image from Podman 5 on. - The image ID alone cannot decide. Podman can compute, for an image whose layers it pulled in the zstd:chunked format, another ID than the manifest names, and a dryrun that compared only IDs would then report a change on every dryrun. For such an image the digests decide. Podman 5.4.2 and 6.1.3 give a zstd:chunked image the ID that its manifest names (measured); MMX does not build on that, because other versions are not measured.
- Lingering comes first for an account's store. Podman run as an account
without the account's runtime directory keeps its state under
/tmpfrom then on and leaves its pause process in the caller's process group; the runtime directory is there while the account's systemd runs, which lingering starts and keeps. podman_imagenever deletes unused images. Deleting is explicit and scheduled, with a systemd timer that the playbook declares.
This page is docs/reference/modules/podman_image.md in the MMX repository.