Project: Kuberhealthy (Observability and Analysis / Observability)
File: CHECK_CREATION.md

If you are using Go, we have an easy to use client package: . example code: ```go package main import ( "github.com/kuberhealthy/kuberhealthy/v2/pkg/checks/external/checkclient" ) func main() { ok := doCheckStuff() if !ok { checkclient.ReportFailure([]string{"Test has failed!"}) return } checkclient.ReportSuccess() } ``` An example check with working Dockerfile is available to use as an example . If you would like to write a check in JavaScript, there is a sample client for checks found . Please see the under the same folder with a Dockerfile for reference. The kuberhealthy is conformant with the reference sample syntax but also supports async/await as well as arbitrary host and port. more info: get started: `npm i --save kuberhealthy` example code: ```javascript const kh = require('kuberhealthy') const report = async () => { let ok = await doCheckStuff() if (ok) { await kh.ReportSuccess() } else { await kh.ReportFailure() } } report() ``` NOTE: KHREPORTINGURL must be set in your env. This is usually done automatically if running as 'khcheck' on kubernetes. Your check only needs to do a few things: Read the `KHREPORTINGURL` environment variable. Send a `POST` to the `KHREPORTINGURL` with the following JSON body: Ensure that your check finishes before the deadline specified in the `KHCHECKRUNDEADLINE` environment variable. If `KHCHECKRUNDEADLINE` is not respected, your check may run into a `400` error when reporting its state to Kuberhealthy. This deadline is calculated by the `timeout:` setting in the `khcheck` resource. ```json { "Errors": [ "Error 1 here", "Error 2 here" ], "OK": false } ``` Never send `"OK": true` if `Errors` has values or you will be given a `400` return code. Simply build your program into a container, `docker push` it to somewhere your cluster has access and craft a `khcheck` resource to enable it in your cluster where Kuberhealthy is installed. Clients outside of Go can be found in the . The following environment variables are injected into every checker pod that Kuberhealthy

When writing your checker code, you can depend on these environment variables always being available to you, even if you do not specify them in your `khcheck` spec. ``` KHREPORTINGURL: The Kuberhealthy URL to send POST requests to for check statuses. KHCHECKRUN_DEADLINE: The Kuberhealthy deadline for checks as calculated by the check timeout given in Unix. KHRUNUUID: The UUID of the check run. This must be sent back as the header 'kh-run-uuid' when status is reported to KHREPORTINGURL. The Go checkClient package does this automatically. KHPODNAMESPACE: The namespace of the checker pod. ``` Every check needs a `khcheck` to enable and configure it. As soon as this resource is applied to the cluster, Kuberhealthy will begin running your check. Whenever you make a change, Kuberhealthy will automatically re-load the check and restart any checks currently in progress gracefully. Here is a minimal `khcheck` resource to start hacking with: ```yaml apiVersion: comcast.github.io/v1 kind: KuberhealthyCheck metadata: name: kh-test-check spec: runInterval: 30s # The interval that Kuberhealthy will run your check on timeout: 2m # After this much time, Kuberhealthy will kill your check and consider it "failed" podSpec: # The exact pod spec that will run. All normal pod spec is valid here. containers: env: # Environment variables are optional but a recommended way to configure check behavior name: MYOPTIONENV_VAR value: "optionsettinghere" image: quay.io/comcast/test-check:latest # The image of the check you just pushed imagePullPolicy: Always # During check development, it helps to set this to 'Always' to prevent on-node image caching. name: main ``` That's it! As soon as this `khcheck` is applied, Kuberhealthy will begin running your check, serving prometheus metrics for it, and displaying status JSON on the status page. You can see a list of checks that others have written on the . If you have a check that may be useful to others and want to contribute, consider adding it to the registry! Just fork this repository and send a PR. This is made easy by simply checking the `Edit` pencil on the check registry page.