feat: add HTTP health check API for Kubernetes integration #3047

solisamicus · 2025-10-10T06:33:18Z

feat: add HTTP health check API for Kubernetes integration

Add comprehensive HTTP health check support for liveness and readiness probes to enable
seamless Kubernetes deployment and container orchestration.

Background

Kubernetes requires HTTP endpoints for health probes to determine container lifecycle:

Liveness probes: detect if container should be restarted
Readiness probes: control traffic routing to healthy instances

This implementation provides a robust, extensible health check system that integrates
with dubbo-go's existing architecture while allowing users to define custom health logic.

Implementation

Core Components

HealthCheckConfig: YAML-configurable settings for ports, paths, and timeouts
HealthChecker Interface: Extensible interface for user-defined health logic
HealthCheckServer: HTTP server exposing /health/live and /health/ready endpoints
Built-in Checkers: Ready-to-use implementations for common scenarios
Global Registry: Thread-safe system for managing health checkers

Key Features

Configurable Endpoints: Customizable ports and paths via configuration
Extensible Logic: Users can implement HealthChecker interface for custom checks
Composite Support: Combine multiple health checkers with AND logic
Detailed Responses: JSON responses with status, timestamp, and detailed information
Timeout Protection: Configurable timeouts prevent hanging health checks
Graceful Integration: Seamless integration with dubbo-go lifecycle management
Thread Safety: Concurrent-safe health checker registry

Changes Made

Add HealthCheckConfig to MetricsConfig with port, paths, timeout settings
Implement HealthChecker interface for user-defined health check logic
Add HealthCheckServer with /health/live and /health/ready endpoints
Support CompositeHealthChecker for combining multiple checkers
Provide built-in checkers: Default, Dubbo, GracefulShutdown, Timeout
Integrate with metrics system for automatic server lifecycle management
Add thread-safe global health checker registry
Support detailed health results with JSON response format
Include graceful shutdown integration and timeout protection

Usage

Configuration

metrics:
  enable: true
  health-check:
    enabled: true
    port: "8080"
    live-path: "/health/live"
    ready-path: "/health/ready"
    timeout: "10s"

Custom Health Checker

type MyHealthChecker struct {
    db *sql.DB
}

func (m *MyHealthChecker) CheckLiveness(ctx context.Context) bool {
    return true // Process is alive
}

func (m *MyHealthChecker) CheckReadiness(ctx context.Context) bool {
    return m.db.Ping() == nil // Check database connection
}

func (m *MyHealthChecker) Name() string {
    return "MyApp"
}

// Register custom checker
server.SetHealthChecker(&MyHealthChecker{db: database})

Kubernetes Deployment

livenessProbe:
  httpGet:
    path: /health/live
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /health/ready
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5
  failureThreshold: 3

API Responses

Healthy Response (200 OK)

{
  "status": "UP",
  "timestamp": 1640995200000,
  "details": {
    "check": "readiness",
    "database": "connected",
    "services": "exported"
  }
}

Unhealthy Response (503 Service Unavailable)

{
  "status": "DOWN", 
  "timestamp": 1640995200000,
  "message": "Database connection failed",
  "details": {
    "check": "readiness",
    "database": "unavailable",
    "reason": "connection_timeout"
  }
}

Benefits

Cloud Native: Full Kubernetes compatibility with standard probe endpoints
Zero Downtime: Proper readiness checks enable rolling deployments
Fault Tolerance: Automatic unhealthy instance removal from load balancers
Observability: Detailed health status information for debugging
Extensibility: Plugin architecture for custom health logic
Production Ready: Timeout protection, graceful shutdown, error handling
Backward Compatible: Disabled by default, no impact on existing deployments

Testing

Health check endpoints can be tested using:

curl http://localhost:8080/health/live
curl http://localhost:8080/health/ready

Fixes: #2039
Enables: Kubernetes-native health monitoring and container lifecycle management

sonarqubecloud · 2025-10-10T06:34:14Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

Copilot

Pull Request Overview

This PR adds comprehensive HTTP health check API support for Kubernetes integration, enabling liveness and readiness probes for container orchestration. The implementation provides a configurable, extensible health check system that integrates seamlessly with dubbo-go's existing architecture.

Key changes:

Implements configurable HTTP health endpoints (/health/live and /health/ready) for Kubernetes probes
Provides extensible HealthChecker interface allowing custom health logic implementation
Adds built-in health checkers for common scenarios (Dubbo services, graceful shutdown, timeout protection)

Reviewed Changes

Copilot reviewed 8 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
server/health_checker.go	Core health checker interfaces and composite implementation
server/health.go	HTTP server implementation with JSON response handling
server/builtin_health_checkers.go	Built-in health checker implementations for common use cases
metrics/health/health_registry.go	Integration with metrics system for automatic server lifecycle
imports/imports.go	Import registration for health metrics collector
config/metric_config.go	Configuration structure for health check settings
common/constant/key.go	Configuration keys for health check parameters
common/constant/default.go	Default values for health check configuration

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-10-10T08:37:41Z

server/builtin_health_checkers.go

+		result.Details["services"] = "none_exported"
+	} else {
+		result.Details["services"] = "exported"
+		result.Details["service_count"] = string(rune(serviceCount))


Converting integer to string via rune cast is incorrect and will produce unexpected results. Use strconv.Itoa(serviceCount) instead.

Copilot · 2025-10-10T08:37:41Z

server/health.go

+	handler := h.handler
+	h.mu.RUnlock()
+
+	ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)


The 5-second timeout is hardcoded in multiple places. Consider extracting this as a configurable constant or deriving it from the health check timeout configuration.

Copilot · 2025-10-10T08:37:41Z

server/health.go

+	handler := h.handler
+	h.mu.RUnlock()
+
+	ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)


The 5-second timeout is hardcoded in multiple places. Consider extracting this as a configurable constant or deriving it from the health check timeout configuration.

No-SilverBullet · 2025-10-10T08:17:09Z

server/health.go

+type DefaultHealthCheckHandler struct{}
+
+func (d *DefaultHealthCheckHandler) HandleLivenessCheck(w http.ResponseWriter, r *http.Request, result *HealthCheckResult) {
+	status := "UP"


change to const, same with 'DOWN'

No-SilverBullet · 2025-10-10T08:18:58Z

server/health.go

+		timeoutStr := h.url.GetParam(constant.HealthCheckTimeoutKey, constant.HealthCheckDefaultTimeout)
+		timeout, err := time.ParseDuration(timeoutStr)
+		if err != nil {
+			timeout = 10 * time.Second


I think it is better to return an error directly so that users can know that their configuration is wrong

No-SilverBullet · 2025-10-10T08:37:08Z

server/health_checker.go

+func (d *DefaultHealthChecker) CheckReadiness(ctx context.Context) bool {
+	// Basic readiness: assume ready
+	return true
+}


The default checker's survival check returns true by default, which is fine. The readiness check can do a little more, such as checking the current service registration status. you can refer https://www.bookstack.cn/read/dubbo-3.1-zh/3b6bb5d2b90f4b85.md

No-SilverBullet · 2025-10-10T08:37:52Z

server/health.go

+	handler := h.handler
+	h.mu.RUnlock()
+
+	ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)


why hard-code 5 seconds

No-SilverBullet · 2025-10-10T08:41:10Z

plz add unit test

Alanxtl · 2025-10-19T12:32:38Z

pls fix ci fail

feat: add HTTP health check API for Kubernetes integration

b2a8c20

AlexStocks requested a review from Copilot October 10, 2025 08:37

Copilot AI reviewed Oct 10, 2025

View reviewed changes

No-SilverBullet reviewed Oct 10, 2025

View reviewed changes

No-SilverBullet added the 3.3.1 label Oct 10, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add HTTP health check API for Kubernetes integration #3047

feat: add HTTP health check API for Kubernetes integration #3047

Uh oh!

solisamicus commented Oct 10, 2025

Uh oh!

sonarqubecloud bot commented Oct 10, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Oct 10, 2025

Uh oh!

Copilot AI Oct 10, 2025

Uh oh!

Copilot AI Oct 10, 2025

Uh oh!

No-SilverBullet Oct 10, 2025

Uh oh!

No-SilverBullet Oct 10, 2025

Uh oh!

No-SilverBullet Oct 10, 2025

Uh oh!

No-SilverBullet Oct 10, 2025

Uh oh!

No-SilverBullet commented Oct 10, 2025

Uh oh!

Alanxtl commented Oct 19, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat: add HTTP health check API for Kubernetes integration #3047

Are you sure you want to change the base?

feat: add HTTP health check API for Kubernetes integration #3047

Uh oh!

Conversation

solisamicus commented Oct 10, 2025

Background

Implementation

Core Components

Key Features

Changes Made

Usage

Configuration

Custom Health Checker

Kubernetes Deployment

API Responses

Healthy Response (200 OK)

Unhealthy Response (503 Service Unavailable)

Benefits

Testing

Uh oh!

sonarqubecloud bot commented Oct 10, 2025

Quality Gate passed

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 10, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 10, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 10, 2025

Choose a reason for hiding this comment

Uh oh!

No-SilverBullet Oct 10, 2025

Choose a reason for hiding this comment

Uh oh!

No-SilverBullet Oct 10, 2025

Choose a reason for hiding this comment

Uh oh!

No-SilverBullet Oct 10, 2025

Choose a reason for hiding this comment

Uh oh!

No-SilverBullet Oct 10, 2025

Choose a reason for hiding this comment

Uh oh!

No-SilverBullet commented Oct 10, 2025

Uh oh!

Alanxtl commented Oct 19, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants