is-healthy

`is-healthy` is a heuristic library for checking the health of Kubernetes and Cloud resources, it supports basic, enhanced and heuristic mode.

• Basic Mode: Wraps Argo health check functionality. Does not distinguish between health and status, lastUpdated and ready are not supported

  • health: One of healthy, unhealthy, warning, unknown
  • message: A reason for the status e.g. Back-off pulling image "nginx:invalid"

• Enhanced Mode: returns the following fields:

  • ready: Whether the resource is currently being reconciled / provisioned.

  ready is independent of health, e.g. A pod in a failure state can be ready if its state is terminal and will not change.

  • health: One of healthy, unhealthy, warning, unknown,

  health can transition based on the age or last event time of a resource.

  • status: A text description of the state of of resource e.g. Running or ImagePullBackoff
  • message: A reason for the status e.g. Back-off pulling image "nginx:invalid"
  • lastUpdated: The last time the resource was updated

• Heuristic Mode: Attempts to determine health using and fields named state, status etc..

Object Type	Support Mode
Core Kubernetes Resources	Enhanced
Pod	Enhanced	Ignores pod restarts for the first 15m warning if restarted in in last 24h unhealthy if restarted in last 1h
Certificate	Enhanced	unhealthy if not issued with 1h warning if not issued with 15m warning if certificate expiry < 2d
CronJob	Enhanced
Flux CRD's	Enhanced
Argo CRD's	Enhanced
Cert-Manager CRD's	Enhanced	Marks
Kubernetes Resources using Conditions	Heuristic

Example

kubectl po  -o json <pod-name> | is-healthy -j

Output:

{
  "ready": false,
  "health": "unhealthy",
  "status": "ImagePullBackOff",
  "message": "Back-off pulling image \"nginx:invalid\"",
  "lastUpdated": "2025-03-26T10:17:18Z"
}

Attribution

This project builds upon the health check implementations from:

• Argo CD
• gitops-engine