Skip to content

Check podman-image

Overview

Lists the container images on a host and checks how old they are. Reports each image's repository tag, age and size, and alerts when an image is older than the configured thresholds, which is a sign that a rebuild or pull was missed. Images can be selected or excluded by name using regular expressions. On a host with many images, --brief hides the rows within the thresholds so the table shows only the images that are too old. For Docker, use the docker-image check instead. Requires root or sudo.

Important Notes:

  • Alerts when an image is older than the --warning (default 90D) or --critical (default 365D) age threshold; raise or widen these for images you intentionally pin
  • The age is measured from the image's build date, not from when it was pulled. Reproducible builds (for example Jib) stamp a fixed placeholder such as 1970-01-01 instead of the real build date. For such an image, the check uses the newest real layer date from the image history, or else the org.opencontainers.image.created label; without either, the age is shown as - and does not alert
  • A dangling image (one that has lost its repository tag) is shown by its short image ID instead of a tag, and counted in the images_dangling perfdata
  • Podman runs rootless by default, and every user keeps their images in their own storage. Running the check as root (via sudo) sees root's own images, not the rootless images of other users. To check a rootless user's images, pass --user=<name>: the check then runs podman as that user. Every line of output names the inspected user, so an empty result against root's storage is obvious The Podman Service Set in the Icinga Director creates its services without --user. Set it on the service of every host whose containers belong to a rootless user, otherwise a tagged host reports "No containers to check" while the containers are running.
  • On a host with a very large number of images, or with rootless Podman under --user, the check can take a while, since every image is inspected.
  • --timeout covers all Podman commands of a run together, so the check ends in time however long each of them takes. The shipped Director template allows 15 seconds.

Data Collection:

  • Executes podman images --quiet --no-trunc to list all image IDs
  • Executes podman image inspect on those IDs to read each image's repository tag, creation date and size

Fact Sheet

Fact Value
Check Plugin Download https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/podman-image
Nagios/Icinga Check Name check_podman_image
Check Interval Recommendation Every day
Can be called without parameters Yes
Runs on Cross-platform
Compiled for Windows No (runs with Python interpreter)
Requirements podman CLI

Help

usage: podman-image [-h] [-V] [--always-ok] [--brief] [-c CRIT]
                    [--ignore IGNORE] [--match MATCH]
                    [--no-match-severity {ok,warn,crit,unknown}]
                    [--no-perfdata] [--timeout TIMEOUT] [--user USER]
                    [-w WARN]

Lists the container images on a host and checks how old they are. Reports each
image's repository tag, age and size, and alerts when an image is older than
the configured thresholds, which is a sign that a rebuild or pull was missed.
Images can be selected or excluded by name using regular expressions. On a
host with many images, --brief hides the rows within the thresholds so the
table shows only the images that are too old. For Docker, use the docker-image
check instead. Requires root or sudo.

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  --always-ok           Always returns OK.
  --brief               Hide the rows that are within the thresholds and show
                        only those in a WARN or CRIT state. Perfdata and
                        alerting are unaffected: every item still emits
                        performance data and still drives the overall check
                        state, so this is safe to leave on.
  -c, --critical CRIT   CRIT threshold for the image age in a human-readable
                        format (s = seconds, m = minutes, h = hours, D = days,
                        W = weeks, M = months, Y = years). Supports Nagios
                        ranges. Example: `180D` alerts on images older than
                        180 days. Default: 365D
  --ignore IGNORE       Ignore images whose repository tag matches this Python
                        regular expression. Case-sensitive by default; use
                        `(?i)` for case-insensitive matching. Can be specified
                        multiple times. Example: `--ignore="^localhost/"` to
                        skip locally built images. Example:
                        `--ignore="(?i)test"` (case-insensitive) to skip any
                        image with "test" in its tag. Default: None
  --match MATCH         Only check images whose repository tag matches this
                        Python regular expression. Case-sensitive by default;
                        use `(?i)` for case-insensitive matching. Can be
                        specified multiple times. If both `--match` and
                        `--ignore` are given, an item must match `--match` AND
                        not match `--ignore` to be reported (include first,
                        exclude second). Example:
                        `--match="^docker.io/library/nginx"` to check only the
                        nginx images. Default: None
  --no-match-severity {ok,warn,crit,unknown}
                        State to report when no item matches the filters and
                        nothing is checked. Default: ok
  --no-perfdata         Suppress the performance data section from the output.
                        The status message and the exit code are unaffected,
                        so alerting keeps working while trending data is
                        dropped.
  --timeout TIMEOUT     Network timeout in seconds. Default: 8 (seconds)
  --user USER           Inspect the rootless images of this user instead of
                        those visible to the executing user. Podman keeps each
                        user's rootless images in that user's own storage, so
                        root (the monitoring user runs the check via sudo)
                        does not see them. With --user, the check runs podman
                        as that user. Requires the right to `sudo -u <user>`
                        (root has this by default), and the user needs a
                        subordinate UID range in /etc/subuid, as rootless
                        Podman does. Example: `--user=webapp`. Default: None
  -w, --warning WARN    WARN threshold for the image age in a human-readable
                        format (s = seconds, m = minutes, h = hours, D = days,
                        W = weeks, M = months, Y = years). Supports Nagios
                        ranges. Example: `90D` alerts on images older than 90
                        days. Default: 90D

Documentation:
https://linuxfabrik.github.io/monitoring-plugins/check-plugins/podman-image/

Usage Examples

Report all images and their age:

./podman-image

Alert on images older than 180 days, ignoring locally built ones:

./podman-image --ignore="^localhost/" --critical=180D

Check the rootless images of the webapp user (run the check as root, for example via the Icinga Director sudo wrapper):

./podman-image --user=webapp --warning=90D

Output:

docker.io/library/postgres:16: age 1Y 6M [CRITICAL] (thresholds 90D/365D; user: `webapp`)

Image                         ! Age   ! Size     ! State
------------------------------+-------+----------+-----------
docker.io/library/nginx:1.27  ! 4W 1D ! 178.3MiB ! [OK]
docker.io/library/postgres:16 ! 1Y 6M ! 405.3MiB ! [CRITICAL]

States

  • WARN/CRIT if an image's age crosses --warning (default 90D) or --critical (default 365D).
  • An image without a usable build date shows - as its age and never alerts.
  • The state reported when no image matches the --match / --ignore filters (or no images exist) is configurable via --no-match-severity (default: ok).
  • CRIT if podman images fails, or if podman image inspect returns nothing that can be read. An image that is removed while the check runs makes podman image inspect fail as well; the images it did report are checked as usual.
  • WARN if the Podman commands do not finish within --timeout (default: 8 seconds).
  • UNKNOWN if the check may not talk to the container engine. The engine is answering, this check is only not allowed to ask, so it says nothing about it and names the sudoers file instead.
  • UNKNOWN if the user given with --user has no subordinate UID range in /etc/subuid.
  • --always-ok suppresses all alerts and always returns OK.

Perfdata / Metrics

Name Type Description
images_checked Number Number of images that passed the filters and were checked.
images_dangling Number Number of checked images that have lost their repository tag.

Troubleshooting

Timeout while running a Podman command

Timeout after 8s while running `podman images --quiet --no-trunc`.

The container engine did not answer within --timeout, which covers all Podman commands of a run together. A host with many images, or an engine busy with other work, can take longer than usual. Run the command from the message by hand to see how long it takes, and raise --timeout accordingly. Keep it below the timeout of the monitoring system for the check command.

Credits, License