Client Library: Go

The Kuberhealthy Go client library, located in pkg/checks/external/checkclient, provides a set of standardized functions for external check containers to communicate their status back to the Kuberhealthy operator. By using this library, developers can easily integrate custom synthetic tests into the Kuberhealthy ecosystem, ensuring that results are reported via a consistent API.

The library handles the complexities of interacting with the Kuberhealthy status reporting endpoint, including environment variable discovery and JSON payload construction. This allows developers to focus on the logic of the check itself rather than the communication overhead.

Sources: README.md:167-172, pkg/checks/external/checkclient/main.go

Core Reporting Functions

The primary purpose of the Go client library is to report the final outcome of a synthetic check. It provides two main entry points for reporting: ReportSuccess and ReportFailure.

Reporting Success

When a check completes all its validation steps successfully, it calls ReportSuccess(). This function sends a POST request to the Kuberhealthy reporting URL with a payload indicating that the check is healthy and contains no error messages.

Sources: pkg/checks/external/checkclient/main.go:121-125, cmd/http-content-check/main.go:73-77

Reporting Failure

If any part of the check logic fails, ReportFailure([]string) is used. This function accepts a slice of strings, allowing the checker to provide detailed context about what went wrong. These errors are then surfaced in the Kuberhealthy status page and Prometheus metrics.

Sources: pkg/checks/external/checkclient/main.go:133-137, cmd/http-check/main.go:204-211

Reporting Flow

The following sequence diagram illustrates how an external check container uses the Go library to report results back to the Kuberhealthy operator.

The diagram shows the standard interaction where the library abstracts the HTTP POST request to the Kuberhealthy server.
Sources: pkg/checks/external/checkclient/main.go:121-155

Configuration and Environment

The library automatically configures itself by looking for specific environment variables injected into the checker pod by the Kuberhealthy operator.

Sources: pkg/checks/external/checkclient/main.go:23-28

Reporting Payload Structure

The library sends a specific JSON structure to the operator. While internal to the library's report function, understanding this structure is useful for debugging.

type reportPayload struct {
    Errors []string
    OK     bool
}

Sources: pkg/checks/external/checkclient/main.go:146-149

Deadline and Timeout Management

External checks are often subject to strict time constraints. The library provides a helper function to retrieve the check's deadline.

GetDeadline

The GetDeadline() function parses the KH_CHECK_RUN_DEADLINE environment variable and returns a time.Time object. Checker pods use this to calculate how much time they have left before they are terminated, allowing for graceful cleanup or early reporting of a timeout failure.

The flowchart demonstrates how the deadline is typically used in the main execution loop of a check.
Sources: pkg/checks/external/checkclient/main.go:87-105, cmd/resource-quota-check/input.go:68-75

Implementation Example

The following code snippet demonstrates the standard pattern for using the library within a custom check's main function.

package main

import (
    "github.com/kuberhealthy/kuberhealthy/v2/pkg/checks/external/checkclient"
    "log"
)

func main() {
    // Perform check logic...
    err := doWork()
    
    if err != nil {
        // Report failure with error details
        reportErr := checkclient.ReportFailure([]string{err.Error()})
        if reportErr != nil {
            log.Fatal(reportErr)
        }
        return
    }

    // Report success
    reportErr := checkclient.ReportSuccess()
    if reportErr != nil {
        log.Fatal(reportErr)
    }
}

Sources: README.md:175-188, cmd/image-download-check/main.go:42-55

Summary

The Go Client Library is a foundational component for building custom Kuberhealthy checks. It provides a simple, thread-safe, and standardized way to communicate check results (ReportSuccess, ReportFailure) and manage execution windows (GetDeadline). By abstracting the HTTP communication and environment variable parsing, it ensures that external checks remain portable and consistent across different cluster environments.

Sources: pkg/checks/external/checkclient/main.go, README.md