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
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 |
Linux |
Requirements |
Command-line tool |
Uses SQLite DBs |
|
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
Authors: Linuxfabrik GmbH, Zurich
License: The Unlicense, see LICENSE file.