Skip to content

Check docker-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. For Podman, use the podman-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
  • 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
  • On a host with a very large number of images the check can take a while, since every image is inspected, and may exceed the short check timeout monitoring systems use by default (often 10 seconds); give the check more time if it times out

Data Collection:

  • Executes docker images --quiet --no-trunc to list all image IDs
  • Executes docker 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/docker-image
Nagios/Icinga Check Name check_docker_image
Check Interval Recommendation Every day
Can be called without parameters Yes
Runs on Cross-platform
Compiled for Windows No
Requirements docker CLI

Help

usage: docker-image [-h] [-V] [--always-ok] [--brief] [-c CRIT]
                    [--ignore IGNORE] [--match MATCH]
                    [--no-match-severity {ok,warn,crit,unknown}]
                    [--no-perfdata] [-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 Podman, use the podman-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.
  -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/docker-image/

Usage Examples

Report all images and their age:

./docker-image

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

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

Output:

postgres:16: age 1Y 6M [CRITICAL] (thresholds 90D/180D)

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

States

  • WARN/CRIT if an image's age crosses --warning (default 90D) or --critical (default 365D).
  • 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 docker images fails, or if docker image inspect returns nothing that can be read. An image that is removed while the check runs makes docker image inspect fail as well; the images it did report are checked as usual.
  • 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.
  • --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.

Credits, License