Client Library: Python
Relevant source files
The following files were used as context for generating this wiki page:
The Kuberhealthy Python client library is designed for authoring synthetic monitoring checks within a Kubernetes cluster. It provides a standardized interface for external checker pods to report their health status back to the Kuberhealthy operator.
The library serves as a Python-based implementation of the status reporting protocol used by Kuberhealthy, enabling developers to write custom checks using Python >= 3.7. It handles the communication details with the Kuberhealthy API, allowing authors to focus on the logic of the check itself.
Sources: clients/python/README.md:1-5, README.md:3-8
Architecture and Core Logic
The Python client operates by sending HTTP POST requests to a locally reachable Kuberhealthy reporting endpoint. It abstracts the JSON data structures required by the operator into simple function calls.
Reporting Mechanism
The client uses the requests library to communicate with the Kuberhealthy server. The server URL is dynamically determined based on environment variables, with a default fallback to the standard internal service address.
The diagram above illustrates the flow of status reporting from a custom Python check to the Kuberhealthy operator.
Sources: clients/python/kh_client.py:27-58, clients/python/README.md:12-25
Data Structures
The library utilizes Python dataclasses to define the report payload.
| Field | Type | Description |
|---|---|---|
OK | bool | Indicates if the check passed. |
Errors | List[str] | A list of error messages describing why a check failed. |
Sources: clients/python/kh_client.py:10-15
Key Functions and Configuration
Configuration Constants
The library relies on environment variables to locate the Kuberhealthy reporting endpoint.
| Constant | Source | Default Value |
|---|---|---|
KH_REPORTING_URL | os.environ.get("KH_REPORTING_URL") | http://kuberhealthy.kuberhealthy.svc.cluster.local/externalCheckStatus |
Sources: clients/python/kh_client.py:18-19
Core Functions
The API consists of two primary reporting functions:
report_success(): Sends a report indicating the check is healthy.report_failure(errors): Sends a report containing a list of error strings.
This sequence diagram shows the interaction when a Python check reports a failure.
Sources: clients/python/kh_client.py:44-58, clients/python/README.md:27-35
Usage and Implementation
To implement a check, developers download kh_client.py and import it into their check script. The check logic typically concludes with a call to either report_success() or report_failure().
Example Check Pattern
from kh_client import report_success, report_failure
def run_my_check():
# ... logic here ...
return True
if __name__ == "__main__":
try:
if run_my_check():
report_success()
else:
report_failure(["Check failed logic"])
except Exception as e:
report_failure([str(e)])
Sources: clients/python/example_check.py:1-24, clients/python/README.md:37-43
Summary
The Client Library: Python provides a lightweight, easy-to-use interface for integrating Python-based synthetic tests into the Kuberhealthy ecosystem. By abstracting the reporting API, it ensures consistency across different check implementations and simplifies the maintenance of custom monitoring logic within Kubernetes clusters.