Kubernetes 生命周期探针

Dubbo-Go Kubernetes Probe (liveness / readiness / startup) user manual

Dubbo-Go Kubernetes 生命周期探针

Dubbo-Go 提供内置的 Kubernetes HTTP Probe 服务,用于支持:

  • liveness
  • readiness
  • startup

该模块通过独立 HTTP 端口暴露探针接口,并支持:

  • 自定义健康检查逻辑
  • 可选内部生命周期对齐
  • 可控的重启风险

以下是一个具体的使用示例,可查看 示例完整源码


一、设计目标

目标说明
可扩展支持注册自定义检查回调
可控风险liveness 默认不绑定内部复杂逻辑
生命周期对齐readiness / startup 可对齐 Dubbo 生命周期
独立端口与业务端口隔离

二、默认行为

启用 Probe 后,默认在:

端口: 22222

暴露以下路径:

Endpoint说明
GET /live进程存活检查
GET /ready服务就绪检查
GET /startup启动阶段检查

响应规则

条件HTTP 状态码
所有检查通过200
任意检查失败503

三、配置方式

Dubbo-Go 支持 New API(推荐)Old API(YAML) 两种配置方式。


3.1 New API 配置方式(推荐)

ins, err := dubbo.NewInstance(
  dubbo.WithMetrics(
    metrics.WithProbeEnabled(),
    metrics.WithProbePort(22222),
    metrics.WithProbeLivenessPath("/live"),
    metrics.WithProbeReadinessPath("/ready"),
    metrics.WithProbeStartupPath("/startup"),
    metrics.WithProbeUseInternalState(true),
  ),
)

可用 Option

Option说明
WithProbeEnabled()启用 Probe
WithProbePort(int)设置 Probe 端口
WithProbeLivenessPath(string)设置 liveness 路径
WithProbeReadinessPath(string)设置 readiness 路径
WithProbeStartupPath(string)设置 startup 路径
WithProbeUseInternalState(bool)是否启用内部状态检查

3.2 Old API YAML 配置方式

metrics:
  probe:
    enabled: true
    port: 22222
    liveness-path: "/live"
    readiness-path: "/ready"
    startup-path: "/startup"
    use-internal-state: true

配置项说明

配置项说明
enabled是否开启 probe 服务
portHTTP 端口
liveness-pathliveness 路径
readiness-pathreadiness 路径
startup-pathstartup 路径
use-internal-state是否启用内部生命周期状态

四、内部生命周期状态(UseInternalState)

当:

use-internal-state: true

Probe 会附加 Dubbo 内部状态判断。


内部状态机制

Probe 类型依赖状态
readinessprobe.SetReady(true/false)
startupprobe.SetStartupComplete(true/false)

默认行为

  • Server.Serve() 成功执行:

    • ready = true
    • startup = true
  • 优雅关闭时:

    • ready = false

当设置为 false

如果:

use-internal-state: false

则 Probe 结果 完全由用户注册的回调决定


五、自定义健康检查(推荐方式)

你可以注册回调扩展检查逻辑。

import "dubbo.apache.org/dubbo-go/v3/metrics/probe"

// Liveness example
probe.RegisterLiveness("db", func(ctx context.Context) error {
    // check database connectivity
    return nil
})

// Readiness example
probe.RegisterReadiness("cache", func(ctx context.Context) error {
    // check downstream dependency
    return nil
})

// Startup example
probe.RegisterStartup("warmup", func(ctx context.Context) error {
    // check warmup completion
    return nil
})

执行逻辑

  • 所有注册的检查函数都会执行
  • 只要有一个返回 error
  • Probe 返回 503

六、语义建议

Liveness

  • 建议仅用于:

    • 进程是否崩溃
    • 核心依赖是否彻底不可用

⚠️ 失败会触发 Pod 重启。


Readiness

  • 可绑定:

    • 注册中心状态
    • 数据库
    • Redis
    • 下游 RPC
    • 本地缓存

用于控制流量是否进入。


Startup

  • 用于:

    • 冷启动
    • 预热逻辑
    • 数据加载
    • 模型初始化

避免启动慢时被误判为失败。


七、Kubernetes 配置示例

livenessProbe:
  httpGet:
    path: /live
    port: 22222
  initialDelaySeconds: 15
  periodSeconds: 10
  timeoutSeconds: 2
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /ready
    port: 22222
  initialDelaySeconds: 5
  periodSeconds: 5
  timeoutSeconds: 2
  failureThreshold: 2

startupProbe:
  httpGet:
    path: /startup
    port: 22222
  periodSeconds: 5
  timeoutSeconds: 2
  failureThreshold: 25 # 120 秒启动预算 => ceil(120 / 5) + 1

八、示例运行说明

示例路径:

metrics/probe/

本地运行

go run ./metrics/probe/go-server/cmd/main.go

实时观察 Probe 状态

watch -n 1 '
for p in live ready startup; do
  url="http://127.0.0.1:22222/$p"

  body=$(curl -sS --max-time 2 "$url" 2>&1)
  code=$(curl -s -o /dev/null --max-time 2 -w "%{http_code}" "$url" 2>/dev/null)

  printf "%-8s [%s] %s\n" "$p" "$code" "$body"
done
'

预期行为

阶段/live/ready/startup
刚启动200503503
预热阶段200503503
预热完成200200200

九、生产最佳实践

推荐参数起点

Probe 类型推荐值说明
livenessinitialDelaySeconds: 10-30periodSeconds: 10timeoutSeconds: 1-3failureThreshold: 3仅用于进程存活和不可恢复故障,不检查数据库、注册中心、Redis 等波动依赖
readinessinitialDelaySeconds: 2-5periodSeconds: 5timeoutSeconds: 1-3failureThreshold: 2-3依赖异常时快速摘流,依赖恢复后尽快重新接流
startupperiodSeconds: 5-10timeoutSeconds: 1-3failureThreshold = ceil(maxStartupSeconds / periodSeconds) + 1预算要覆盖冷启动、预热、配置加载等最长路径

例如:如果应用最长启动耗时约为 120s,并设置 periodSeconds: 5,则建议:

failureThreshold = ceil(120 / 5) + 1 = 25

落地建议

  • liveness 保持简单,只检测“必须重启才能恢复”的故障
  • readiness 绑定注册中心、数据库、Redis、下游 RPC 等波动依赖
  • startup 单独承担慢启动保护,避免把大 initialDelaySeconds 堆到 liveness
  • 微服务集群建议开启 use-internal-state: true,再结合 probe.SetReady(...) 做主动摘流