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 registry
  • pull_image (when_missing or always; 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 image
  • registry_username (string; optional): the login for the registry named in image; both registry_username and registry_password, or neither
  • registry_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 secret
  • in_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.

  • status
  • change
  • reason
  • value.image_id
  • value.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_missing pulls only when the store does not have the image. A rerun asks the registry nothing and never replaces an image because a tag moved. Use pull_image: when_missing with tags that name one version, and with digests.
  • always asks 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_change and 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_image has no default. The pull_image setting decides whether a rerun deploys new software, so every podman_image task must set pull_image explicitly.
  • 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 inspect leaves 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 /tmp from 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_image never 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.