feat: support upstream health checks in BackendTrafficPolicy (#414)

Author: AlinsRan

api/v1alpha1/backendtrafficpolicy_types.go

@@ -74,6 +74,13 @@ type BackendTrafficPolicySpec struct {
 	// UpstreamHost specifies the host of the Upstream request. Used only if
 	// passHost is set to `rewrite`.
 	Host Hostname `json:"upstreamHost,omitempty" yaml:"upstreamHost,omitempty"`
+
+	// HealthCheck defines active and passive health check configuration for
+	// the upstream backends. When configured, APISIX will probe backends
+	// (active) or monitor live traffic (passive) to detect and bypass
+	// unhealthy nodes.
+	// +optional
+	HealthCheck *HealthCheck `json:"healthCheck,omitempty" yaml:"healthCheck,omitempty"`
 }
 
 // LoadBalancer describes the load balancing parameters.
@@ -125,6 +132,139 @@ type BackendTrafficPolicyList struct {
 	Items           []BackendTrafficPolicy `json:"items"`
 }
 
+// HealthCheck defines the active and passive health check configuration for upstream nodes.
+type HealthCheck struct {
+	// Active health checks proactively send requests to upstream nodes to determine their availability.
+	// +kubebuilder:validation:Required
+	Active *ActiveHealthCheck `json:"active" yaml:"active"`
+	// Passive health checks evaluate upstream health based on observed traffic (timeouts, errors).
+	// +kubebuilder:validation:Optional
+	Passive *PassiveHealthCheck `json:"passive,omitempty" yaml:"passive,omitempty"`
+}
+
+// ActiveHealthCheck defines the active upstream health check configuration.
+type ActiveHealthCheck struct {
+	// Type is the health check type. Can be `http`, `https`, or `tcp`.
+	// +kubebuilder:validation:Enum=http;https;tcp;
+	// +kubebuilder:default=http
+	// +optional
+	Type string `json:"type,omitempty" yaml:"type,omitempty"`
+
+	// Timeout sets health check timeout.
+	// +optional
+	Timeout metav1.Duration `json:"timeout,omitempty" yaml:"timeout,omitempty"`
+
+	// Concurrency sets the number of targets to be checked at the same time.
+	// +kubebuilder:validation:Minimum=0
+	// +optional
+	Concurrency int `json:"concurrency,omitempty" yaml:"concurrency,omitempty"`
+
+	// Host sets the upstream host used in the health check request.
+	// +optional
+	Host string `json:"host,omitempty" yaml:"host,omitempty"`
+
+	// Port sets the port on the upstream node to probe.
+	// +kubebuilder:validation:Minimum=1
+	// +kubebuilder:validation:Maximum=65535
+	// +optional
+	Port int32 `json:"port,omitempty" yaml:"port,omitempty"`
+
+	// HTTPPath sets the HTTP path for the probe request.
+	// +optional
+	HTTPPath string `json:"httpPath,omitempty" yaml:"httpPath,omitempty"`
+
+	// StrictTLS controls whether TLS certificate validation is enforced.
+	// +optional
+	StrictTLS *bool `json:"strictTLS,omitempty" yaml:"strictTLS,omitempty"`
+
+	// RequestHeaders sets additional HTTP request headers for the probe.
+	// +optional
+	RequestHeaders []string `json:"requestHeaders,omitempty" yaml:"requestHeaders,omitempty"`
+
+	// Healthy configures the thresholds for marking a node healthy.
+	// +optional
+	Healthy *ActiveHealthCheckHealthy `json:"healthy,omitempty" yaml:"healthy,omitempty"`
+
+	// Unhealthy configures the thresholds for marking a node unhealthy.
+	// +optional
+	Unhealthy *ActiveHealthCheckUnhealthy `json:"unhealthy,omitempty" yaml:"unhealthy,omitempty"`
+}
+
+// PassiveHealthCheck defines passive health check configuration based on observed traffic.
+type PassiveHealthCheck struct {
+	// Type is the passive health check type. Can be `http`, `https`, or `tcp`.
+	// +kubebuilder:validation:Enum=http;https;tcp;
+	// +kubebuilder:default=http
+	// +optional
+	Type string `json:"type,omitempty" yaml:"type,omitempty"`
+
+	// Healthy defines conditions under which a node is considered healthy.
+	// +optional
+	Healthy *PassiveHealthCheckHealthy `json:"healthy,omitempty" yaml:"healthy,omitempty"`
+
+	// Unhealthy defines conditions under which a node is considered unhealthy.
+	// +optional
+	Unhealthy *PassiveHealthCheckUnhealthy `json:"unhealthy,omitempty" yaml:"unhealthy,omitempty"`
+}
+
+// ActiveHealthCheckHealthy defines thresholds for actively marking an upstream node healthy.
+type ActiveHealthCheckHealthy struct {
+	PassiveHealthCheckHealthy `json:",inline" yaml:",inline"`
+
+	// Interval defines the time between health check probes.
+	// Minimum is 1s.
+	Interval metav1.Duration `json:"interval,omitempty" yaml:"interval,omitempty"`
+}
+
+// ActiveHealthCheckUnhealthy defines thresholds for actively marking an upstream node unhealthy.
+type ActiveHealthCheckUnhealthy struct {
+	PassiveHealthCheckUnhealthy `json:",inline" yaml:",inline"`
+
+	// Interval defines the time between health check probes.
+	// Minimum is 1s.
+	Interval metav1.Duration `json:"interval,omitempty" yaml:"interval,omitempty"`
+}
+
+// PassiveHealthCheckHealthy defines conditions for passively marking a node healthy.
+type PassiveHealthCheckHealthy struct {
+	// HTTPCodes is the list of HTTP status codes considered healthy.
+	// +kubebuilder:validation:MinItems=1
+	// +optional
+	HTTPCodes []int `json:"httpCodes,omitempty" yaml:"httpCodes,omitempty"`
+
+	// Successes is the number of consecutive successful responses required to mark a node healthy.
+	// +kubebuilder:validation:Minimum=0
+	// +kubebuilder:validation:Maximum=254
+	// +optional
+	Successes int `json:"successes,omitempty" yaml:"successes,omitempty"`
+}
+
+// PassiveHealthCheckUnhealthy defines conditions for passively marking a node unhealthy.
+type PassiveHealthCheckUnhealthy struct {
+	// HTTPCodes is the list of HTTP status codes considered unhealthy.
+	// +kubebuilder:validation:MinItems=1
+	// +optional
+	HTTPCodes []int `json:"httpCodes,omitempty" yaml:"httpCodes,omitempty"`
+
+	// HTTPFailures is the number of HTTP failures to mark a node unhealthy.
+	// +kubebuilder:validation:Minimum=0
+	// +kubebuilder:validation:Maximum=254
+	// +optional
+	HTTPFailures int `json:"httpFailures,omitempty" yaml:"httpFailures,omitempty"`
+
+	// TCPFailures is the number of TCP failures to mark a node unhealthy.
+	// +kubebuilder:validation:Minimum=0
+	// +kubebuilder:validation:Maximum=254
+	// +optional
+	TCPFailures int `json:"tcpFailures,omitempty" yaml:"tcpFailures,omitempty"`
+
+	// Timeouts is the number of timeouts to mark a node unhealthy.
+	// +kubebuilder:validation:Minimum=1
+	// +kubebuilder:validation:Maximum=254
+	// +optional
+	Timeouts int `json:"timeouts,omitempty" yaml:"timeouts,omitempty"`
+}
+
 func init() {
 	SchemeBuilder.Register(&BackendTrafficPolicy{}, &BackendTrafficPolicyList{})
 }