Kuberhealthy项目：自定义健康检查(khcheck)开发指南

Kuberhealthy项目：自定义健康检查(khcheck)开发指南

前言

在Kubernetes集群监控领域，Kuberhealthy作为一个开源的Kubernetes健康检查框架，允许开发者创建自定义的健康检查机制。本文将详细介绍如何在Kuberhealthy项目中开发自定义检查(khcheck)，涵盖Go和JavaScript两种主流语言的实现方式，以及通用的检查规范。

检查机制基础原理

Kuberhealthy的检查机制基于以下几个核心概念：

1. 检查客户端：执行实际健康检查逻辑的程序
2. 报告机制：通过HTTP POST向Kuberhealthy报告检查结果
3. 资源定义：通过khcheck CRD定义检查的运行参数

检查程序需要在规定时间内完成并报告结果，否则将被视为失败。

Go语言实现方案

客户端库介绍

Kuberhealthy为Go语言提供了官方客户端库，大大简化了检查开发流程。该库主要提供两个关键功能：

• ReportSuccess()：报告检查成功
• ReportFailure([]string)：报告检查失败及错误信息

示例代码解析

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()
}

开发建议

1. 确保检查逻辑具有明确的超时处理
2. 为检查失败提供详细的错误信息
3. 考虑检查的资源消耗，避免影响集群性能

JavaScript实现方案

客户端选项

JavaScript开发者有两种选择：

1. 参考官方提供的JavaScript示例客户端
2. 使用社区维护的NPM包kuberhealthy

NPM包使用示例

const kh = require('kuberhealthy')

const report = async () => {
  try {
    let ok = await doCheckStuff()
    if (ok) {
      await kh.ReportSuccess()
    } else {
      await kh.ReportFailure()
    }
  } catch (err) {
    await kh.ReportFailure([err.message])
  }
}

report()

环境变量说明

JavaScript检查需要配置KH_REPORTING_URL环境变量，在Kubernetes环境中通常会自动注入。

通用检查规范（适用于所有语言）

基本要求

无论使用何种语言，自定义检查都需要遵循以下规范：

1. 读取KH_REPORTING_URL环境变量获取报告地址
2. 通过POST请求报告JSON格式的结果
3. 严格遵守KH_CHECK_RUN_DEADLINE规定的时间限制

报告数据结构

成功的报告：

{
  "OK": true,
  "Errors": []
}

失败的报告：

{
  "OK": false,
  "Errors": [
    "具体的错误信息1",
    "具体的错误信息2"
  ]
}

关键环境变量

检查容器中会自动注入以下环境变量：

• KH_REPORTING_URL：报告状态的目标URL
• KH_CHECK_RUN_DEADLINE：Unix时间戳格式的检查截止时间
• KH_RUN_UUID：检查运行的唯一标识符（需要在报告时作为HTTP头返回）
• KH_POD_NAMESPACE：检查Pod所在的命名空间

khcheck资源配置详解

最小化配置示例

apiVersion: comcast.github.io/v1
kind: KuberhealthyCheck
metadata:
  name: example-check 
spec:
  runInterval: 30s  # 检查运行间隔
  timeout: 2m      # 检查超时时间
  podSpec:         # 标准Pod定义
    containers:
    - name: main
      image: your-registry/your-check-image:tag
      imagePullPolicy: Always
      env:
        - name: CUSTOM_CONFIG
          value: "config_value"

关键配置项说明

1. runInterval：检查频率，建议根据检查性质合理设置
2. timeout：必须大于检查的实际执行时间
3. podSpec：支持完整的Pod定义，可以配置资源限制、卷挂载等

检查开发最佳实践

1. 日志记录：为检查添加适当的日志输出，便于故障排查
2. 资源限制：为检查容器设置合理的资源请求和限制
3. 配置分离：使用环境变量或ConfigMap管理检查配置
4. 优雅处理中断：正确处理SIGTERM信号，实现优雅退出
5. 指标暴露：考虑为检查添加Prometheus指标端点

检查部署流程

1. 构建检查程序容器镜像
2. 将镜像推送到集群可访问的镜像仓库
3. 创建khcheck资源配置
4. 应用配置到集群
5. 通过Kuberhealthy状态页面验证检查结果

结语

通过Kuberhealthy的自定义检查机制，开发者可以灵活扩展集群监控能力，覆盖各种特定的健康检查场景。无论是使用Go、JavaScript还是其他语言，只要遵循基本的报告规范，就能轻松集成到Kuberhealthy框架中。建议从简单的检查开始，逐步扩展功能，最终构建出适合自己集群环境的全面监控体系。