Client Library: JavaScript / Node.js
Relevant source files
The following files were used as context for generating this wiki page:
The JavaScript client for Kuberhealthy provides a simplified interface for reporting check results from external checker pods to the Kuberhealthy operator. This library is a direct implementation of the reporting logic found in the core Go client, allowing developers to write synthetic tests and continuous process verifications using Node.js.
Sources: clients/js/README.md:3-6, README.md:1-5
Overview and Purpose
The primary purpose of the JavaScript client is to export functions that send status report POST requests to the Kuberhealthy API. When a check is executed within a Kubernetes cluster, the client communicates the success or failure of that check back to the operator, which then aggregates these statuses for consumption by monitoring tools like Prometheus.
Sources: clients/js/README.md:3-5, README.md:141-143
Architecture and Data Flow
Kuberhealthy checker pods operate by performing specific verification logic and then using the client library to notify the Kuberhealthy operator of the result.
The diagram shows the lifecycle of a JavaScript-based check from execution to metric generation.
Sources: README.md:133-143, clients/js/README.md:23-32
Integration and Installation
The JavaScript client can be integrated into projects through two primary methods: the NPM registry or manual file inclusion.
Installation Options
| Method | Command / Action | Description |
|---|---|---|
| NPM | npm i --save kuberhealthy | Installs the official package; supports async/await and arbitrary host/port configuration. |
| Manual | curl -O -L https://raw.githubusercontent.com/kuberhealthy/kuberhealthy/master/clients/js/kh-client.js | Downloads the standalone client file directly into the project directory. |
Sources: clients/js/README.md:9-21
Configuration
Once downloaded or installed, the library is included using standard CommonJS require syntax:
const kh = require("./kh-client");
Sources: clients/js/README.md:23-25
API Reference
The client provides two core functions for reporting the state of a synthetic check.
Reporting Functions
ReportSuccess()
Signals to Kuberhealthy that the check has passed successfully. In a typical implementation, this is called at the end of the check logic if no errors were encountered.
Sources: clients/js/README.md:31-32
ReportFailure(messages)
Signals that the check has failed.
- Parameter:
messages(Array of Strings) - A list of error messages describing the failure. - Behavior: This sends a failure status to the Kuberhealthy API, which will then reflect the check as "unhealthy" in metrics and status pages.
Sources: clients/js/README.md:28-29, README.md:182-184
Implementation Example
try {
// Perform verification logic here
kh.ReportSuccess();
} catch (err) {
console.error("Error when reporting success: " + err.message);
kh.ReportFailure([err.message]);
process.exit(1);
}
process.exit(0);
Sources: clients/js/README.md:43-51
Deployment in Kubernetes
Checks written with the JavaScript client are deployed as containers within KuberhealthyCheck or KuberhealthyJob custom resources.
Check Resource Configuration
The custom resource definitions (CRDs) define how the Node.js container is executed by the Kuberhealthy operator.
| Field | Type | Description |
|---|---|---|
podSpec | Object | Standard Kubernetes Pod specification including the JS container image. |
runInterval | Duration String | How often the JS check should be executed (e.g., 15m). |
timeout | Duration String | Maximum allowed time for the JS check to run before being killed. |
Sources: scripts/generated/comcast.github.io_khchecks.yaml:52-56, scripts/generated/comcast.github.io_khchecks.yaml:2639-2642
Reporting Sequence
The sequence diagram illustrates the communication between the Node.js client and the Kuberhealthy operator.
Sources: README.md:133-142, clients/js/README.md:3-5
Conclusion
The JavaScript/Node.js client library is a lightweight tool for extending Kuberhealthy's synthetic monitoring capabilities. By abstracting the HTTP reporting protocol into simple ReportSuccess and ReportFailure functions, it enables rapid development of custom health checks tailored to Node.js applications and their dependencies.
Sources: clients/js/README.md:3-6, README.md:11-13