Skip to content

Check kubectl-get-pods

Overview

Checks the health and status of Kubernetes Pods by running kubectl get pods and parsing the results. Prints a table listing namespace, pod name, readiness, status, restart count, pod age, and IP address. Adds performance data for each pod status (Running, Pending, Failed, Succeeded, Unknown). By default, only shows pods from the current namespace. Use --all-namespaces to check across all namespaces. The plugin also stores a temporary local SQLite database during runtime (no persistent history). Results can therefore be filtered with a custom SQL --query (e.g., by namespace, pod name, or status). See the README for more details. Pending and Failed pods can trigger a WARNING or CRITICAL state (configurable via --severity), while Unknown pods result in an UNKNOWN state. Intended for use with Nagios/Icinga to detect Kubernetes pod issues like stuck, failing, or unreachable pods.

For the --query parameter, the following columns can be used:

  • namespace (TEXT)
  • name (TEXT)
  • ready (TEXT)
  • status (TEXT)
  • restarts (INT)
  • age (INT)
  • ip (TEXT)

Hints:

  • OIDC-based login to Kubernetes is not yet supported by this plugin.

Fact Sheet

Fact Value
Check Plugin Download https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/kubectl-get-pods
Check Interval Recommendation Once a minute
Can be called without parameters Yes
Compiled for Windows No
Requirements Command-line tool kubectl (you must use a kubectl version that is within one minor version difference of your cluster. For example, a v1.32 client can communicate with v1.31, v1.32, and v1.33 control planes. Using the latest compatible version of kubectl helps avoid unforeseen issues. See installation).
Uses SQLite DBs $TEMP/linuxfabrik-monitoring-plugins-kubectl-get-pods.db

Help

usage: kubectl-get-pods [-h] [-V] [--always-ok] [--all-namespaces]
                        [--kubeconfig KUBECONFIG] [--query QUERY]
                        [--severity {warn,crit}] [--test TEST]

Checks the health and status of Kubernetes Pods by running `kubectl get pods`
and parsing the results. Prints a table listing namespace, pod name,
readiness, status, restart count, pod age, and IP address. Adds performance
data for each pod status (Running, Pending, Failed, Succeeded, Unknown). By
default, only shows pods from the current namespace. Use `--all-namespaces` to
check across all namespaces. The plugin also stores a temporary local SQLite
database during runtime (no persistent history). Results can therefore be
filtered with a custom SQL `--query` (e.g., by namespace, pod name, or
status). See the README for more details. Pending and Failed pods can trigger
a WARNING or CRITICAL state (configurable via `--severity`), while Unknown
pods result in an UNKNOWN state. Intended for use with Nagios/Icinga to detect
Kubernetes pod issues like stuck, failing, or unreachable pods.

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  --always-ok           Always returns OK.
  --all-namespaces      If present, list the requested object(s) across all
                        namespaces. Namespace in current context is ignored
                        even if specified with `--namespace`. Default: False
  --kubeconfig KUBECONFIG
                        Path to the kubeconfig file. Default:
                        /var/spool/icinga2/.kubeconfig
  --query QUERY         Provide the SQL `WHEN` statement part to narrow down
                        results. Example: `namespace = 'mynamespace' and name
                        like 'prod-%' and status != 'running'`. Have a look at
                        the README for a list of available columns. Default: 1
  --severity {warn,crit}
                        Severity for alerting. Default: crit
  --test TEST           For unit tests. Needs "path-to-stdout-file,path-to-
                        stderr-file,expected-retc".

Usage Examples

./kubectl-get-pods \
    --all-namespaces \
    --kubeconfig /var/spool/icinga2/.kubeconfig \
    --query='namespace = "mynamespace" and name like "mycontainer-%"'

Output:

NAMESPACE   ! NAME                                ! RDY ! RSTRT ! AGE    ! IP         ! STATUS    
------------+-------------------------------------+-----+-------+--------+------------+--------
mynamespace ! mycontainer-mariadb-555df66f6c-5z8h ! 1/1 ! 0     ! 1D 2h  ! 192.0.2.11 ! Running 
mynamespace ! mycontainer-postgres-775cb466bb-qkw ! 1/1 ! 0     ! 1M 11h ! 192.0.2.12 ! Running

States

  • Depending on the --severity given, returns CRIT (default) or WARN if a pod is in 'Pending' or 'Failed' state,
  • UNKNOWN if it is in 'Unknown' state,
  • and OK in all other cases.

Perfdata / Metrics

Name Type Description
failed Number Number of failed pods
pending Number Number of pending pods
running Number Number of running pods
succeeded Number Number of succeeded pods
unknown Number Number of unknown pods

Credits, License