Kubernetes Lifecycle Probe

Dubbo-Go Kubernetes Lifecycle Probe

Dubbo-Go provides a built-in Kubernetes HTTP Probe service that supports:

• ✅ liveness
• ✅ readiness
• ✅ startup

The probe service runs on an independent HTTP port and supports:

• Custom health check logic
• Optional alignment with Dubbo internal lifecycle state
• Controlled restart risk management

For a complete runnable example, see:

https://github.com/apache/dubbo-go-samples/tree/main/metrics

1. Design Goals

2. Default Behavior

When Probe is enabled, it exposes endpoints on:

Port: 22222

The following paths are available:

Response Rules

3. Configuration

Dubbo-Go supports both New API (recommended) and Old API (YAML) configuration styles.

1️⃣ New API Configuration (Recommended)

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

Available Options

2️⃣ Old API YAML Configuration

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

Configuration Fields

4. Internal Lifecycle State (UseInternalState)

When:

use-internal-state: true

Probe attaches Dubbo internal lifecycle checks.

Internal State Mechanism

Default Behavior

• When Server.Serve() executes successfully:

  • ready = true
  • startup = true

• During graceful shutdown:

  • ready = false

When Set to false

If:

use-internal-state: false

The probe result is fully determined by user-registered callbacks.

5. Custom Health Checks (Recommended)

You can extend probe logic by registering callbacks.

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

Execution Logic

• All registered checks will be executed.
• If any check returns an error,
• The probe returns HTTP 503.

6. Semantic Recommendations

Liveness

Recommended usage:

• Detect process crashes
• Detect fatal core dependency failure

⚠️ Failure will trigger Pod restart.

Readiness

May bind to:

• Service registry state
• Database
• Redis
• Downstream RPC
• Local cache

Controls whether traffic is routed to the Pod.

Startup

Suitable for:

• Cold start handling
• Warm-up logic
• Data loading
• Model initialization

Prevents premature restart during slow initialization.

7. Kubernetes Configuration Example

livenessProbe:
  httpGet:
    path: /live
    port: 22222
  initialDelaySeconds: 5
  periodSeconds: 5

readinessProbe:
  httpGet:
    path: /ready
    port: 22222
  initialDelaySeconds: 5
  periodSeconds: 5

startupProbe:
  httpGet:
    path: /startup
    port: 22222
  failureThreshold: 30
  periodSeconds: 10

8. Example Usage

Example path:

metrics/probe/

Run Locally

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

Monitor Probe Status in Real Time

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
'

Expected Behavior

9. Production Best Practices