Update documentation for node_is_alive

If patroni is not running, we cannot know it's down or if the
provided api url is wrong. Therefore, we return UNKNOWN.

The doc and code was updated to make this more clear.

Author: blogh

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Change log
 
+## unreleased
+
+### Fixed
+
+* Update the documentation to clarify that if patroni cannot be reached, we consider
+  it's a configuration error that returns UNKNOWN (#77, reported by @MLyssens)
+
 ## check_patroni 2.1.0 - 2024-10-19
 
 ### Fixed

README.md

@@ -140,6 +140,11 @@ example only Bash versions older than 4.4 are supported.
 
 [click]: https://click.palletsprojects.com/en/8.1.x/shell-completion/
 
+## Connection errors and service status
+
+If patroni is not running, we have no way to know if the provided endpoint is
+valid, therefore the check returns UNKNOWN.
+
 ## Cluster services
 
 ### cluster_config_has_changed
@@ -356,11 +361,14 @@ Options:
 Usage: check_patroni node_is_alive [OPTIONS]
 
   Check if the node is alive ie patroni is running. This is a liveness check
-  as defined in Patroni's documentation.
+  as defined in Patroni's documentation. If patroni is not running, we have no
+  way to know if the provided endpoint is valid, therefore the check returns
+  UNKNOWN.
 
   Check:
-  * `OK`: If patroni is running.
-  * `CRITICAL`: otherwise.
+  * `OK`: If patroni the liveness check returns with HTTP status 200.
+  * `CRITICAL`: if partoni's liveness check returns with an HTTP status
+     other than 200.
 
   Perfdata:
   * `is_running` is 1 if patroni is running, 0 otherwise

check_patroni/cli.py

@@ -789,12 +789,15 @@ def node_patroni_version(ctx: click.Context, patroni_version: str) -> None:
 @nagiosplugin.guarded
 def node_is_alive(ctx: click.Context) -> None:
     """Check if the node is alive ie patroni is running. This is
-    a liveness check as defined in Patroni's documentation.
+    a liveness check as defined in Patroni's documentation. If
+    patroni is not running, we have no way to know if the provided
+    endpoint is valid, therefore the check returns UNKNOWN.
 
     \b
     Check:
-    * `OK`: If patroni is running.
-    * `CRITICAL`: otherwise.
+    * `OK`: If patroni the liveness check returns with HTTP status 200.
+    * `CRITICAL`: if partoni's liveness check returns with an HTTP status
+       other than 200.
 
     \b
     Perfdata:

check_patroni/types.py

@@ -11,8 +11,8 @@
 
 
 class APIError(requests.exceptions.RequestException):
-    """This exception is raised when the rest api couldn't
-    be reached and we got a http status code different from 200.
+    """This exception is raised when the rest api could
+    be reached but we got a http status code different from 200.
     """
 
 

docs/make_readme.sh

@@ -121,6 +121,11 @@ Please note that shell completion is not supported far all shell versions, for
 example only Bash versions older than 4.4 are supported.
 
 [click]: https://click.palletsprojects.com/en/8.1.x/shell-completion/
+
+## Connection errors and service status
+
+If patroni is not running, we have no way to know if the provided endpoint is
+valid, therefore the check returns UNKNOWN.
 _EOF_
 readme
 readme "## Cluster services"