Skip to content

feat(apisixupstream): support healthcheck (#2574) #279

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 14, 2025
Merged

feat(apisixupstream): support healthcheck (#2574) #279

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion api/adc/types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -204,7 +204,7 @@ type UpstreamActiveHealthCheck struct {
Host string `json:"host,omitempty" yaml:"host,omitempty"`
Port int32 `json:"port,omitempty" yaml:"port,omitempty"`
HTTPPath string `json:"http_path,omitempty" yaml:"http_path,omitempty"`
HTTPSVerifyCert bool `json:"https_verify_certificate,omitempty" yaml:"https_verify_certificate,omitempty"`
HTTPSVerifyCert bool `json:"https_verify_cert,omitempty" yaml:"https_verify_cert,omitempty"`
HTTPRequestHeaders []string `json:"req_headers,omitempty" yaml:"req_headers,omitempty"`
Healthy UpstreamActiveHealthCheckHealthy `json:"healthy,omitempty" yaml:"healthy,omitempty"`
Unhealthy UpstreamActiveHealthCheckUnhealthy `json:"unhealthy,omitempty" yaml:"unhealthy,omitempty"`
Expand Down
23 changes: 19 additions & 4 deletions api/v2/apisixupstream_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,10 @@ type ApisixUpstreamExternalNode struct {
Weight *int `json:"weight,omitempty" yaml:"weight"`

// Port specifies the port number on which the external node is accepting traffic.
//
// +kubebuilder:validation:Optional
// +kubebuilder:validation:Minimum=1
// +kubebuilder:validation:Maximum=65535
Port *int `json:"port,omitempty" yaml:"port"`
}

Expand All @@ -118,7 +121,6 @@ type ApisixUpstreamConfig struct {
Timeout *UpstreamTimeout `json:"timeout,omitempty" yaml:"timeout,omitempty"`

// HealthCheck defines the active and passive health check configuration for the upstream.
// Deprecated: no longer supported in standalone mode.
// +kubebuilder:validation:Optional
HealthCheck *HealthCheck `json:"healthCheck,omitempty" yaml:"healthCheck,omitempty"`

Expand Down Expand Up @@ -160,6 +162,8 @@ type PortLevelSettings struct {
ApisixUpstreamConfig `json:",inline" yaml:",inline"`

// Port is a Kubernetes Service port.
// +kubebuilder:validation:Minimum=1
// +kubebuilder:validation:Maximum=65535
Port int32 `json:"port" yaml:"port"`
}

Expand Down Expand Up @@ -221,9 +225,11 @@ type Discovery struct {

// 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:Optional
// +kubebuilder:validation:Enum=http;https;tcp;
// Type is the health check type. Can be `http`, `https`, or `tcp`.
// +kubebuilder:default=http
Type string `json:"type,omitempty" yaml:"type,omitempty"`
// Timeout sets health check timeout in seconds.
Timeout time.Duration `json:"timeout,omitempty" yaml:"timeout,omitempty"`
Expand All @@ -232,9 +238,10 @@ type ActiveHealthCheck struct {
Concurrency int `json:"concurrency,omitempty" yaml:"concurrency,omitempty"`
// Host sets the upstream host.
Host string `json:"host,omitempty" yaml:"host,omitempty"`
// +kubebuilder:validation:Minimum=0
// +kubebuilder:validation:Maximum=65535
// Port sets the upstream port.
//
// +kubebuilder:validation:Minimum=1
// +kubebuilder:validation:Maximum=65535
Port int32 `json:"port,omitempty" yaml:"port,omitempty"`
// HTTPPath sets the HTTP probe request path.
HTTPPath string `json:"httpPath,omitempty" yaml:"httpPath,omitempty"`
Expand All @@ -254,6 +261,10 @@ type ActiveHealthCheck struct {
type PassiveHealthCheck struct {
// Type specifies the type of passive health check.
// Can be `http`, `https`, or `tcp`.
//
// +kubebuilder:validation:Optional
// +kubebuilder:validation:Enum=http;https;tcp;
// +kubebuilder:default=http
Type string `json:"type,omitempty" yaml:"type,omitempty"`
// Healthy defines the conditions under which an upstream node is considered healthy.
Healthy *PassiveHealthCheckHealthy `json:"healthy,omitempty" yaml:"healthy,omitempty"`
Expand Down Expand Up @@ -304,6 +315,10 @@ type PassiveHealthCheckUnhealthy struct {
// TCPFailures define the number of TCP failures to define an unhealthy target.
TCPFailures int `json:"tcpFailures,omitempty" yaml:"tcpFailures,omitempty"`
// Timeout sets health check timeout in seconds.
// https://github.com/apache/apisix/blob/0151d9e35bba63d7c316187272d88e19db0be634/apisix/schema_def.lua#L196
//
// +kubebuilder:validation:Minimum=1
// +kubebuilder:validation:Maximum=254
Timeouts int `json:"timeout,omitempty" yaml:"timeout,omitempty"`
}

Expand Down
56 changes: 42 additions & 14 deletions config/crd/bases/apisix.apache.org_apisixupstreams.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,8 @@ spec:
port:
description: Port specifies the port number on which the external
node is accepting traffic.
maximum: 65535
minimum: 1
type: integer
type:
description: Type indicates the kind of external node. Can be
Expand All @@ -95,9 +97,8 @@ spec:
minItems: 1
type: array
healthCheck:
description: |-
HealthCheck defines the active and passive health check configuration for the upstream.
Deprecated: no longer supported in standalone mode.
description: HealthCheck defines the active and passive health check
configuration for the upstream.
properties:
active:
description: Active health checks proactively send requests to
Expand Down Expand Up @@ -140,7 +141,7 @@ spec:
description: Port sets the upstream port.
format: int32
maximum: 65535
minimum: 0
minimum: 1
type: integer
requestHeaders:
description: RequestHeaders sets the request headers.
Expand All @@ -155,6 +156,7 @@ spec:
format: int64
type: integer
type:
default: http
description: Type is the health check type. Can be `http`,
`https`, or `tcp`.
enum:
Expand Down Expand Up @@ -190,7 +192,11 @@ spec:
minimum: 0
type: integer
timeout:
description: Timeout sets health check timeout in seconds.
description: |-
Timeout sets health check timeout in seconds.
https://github.com/apache/apisix/blob/0151d9e35bba63d7c316187272d88e19db0be634/apisix/schema_def.lua#L196
maximum: 254
minimum: 1
type: integer
type: object
type: object
Expand All @@ -217,9 +223,14 @@ spec:
type: integer
type: object
type:
default: http
description: |-
Type specifies the type of passive health check.
Can be `http`, `https`, or `tcp`.
enum:
- http
- https
- tcp
type: string
unhealthy:
description: Unhealthy defines the conditions under which
Expand All @@ -245,7 +256,11 @@ spec:
minimum: 0
type: integer
timeout:
description: Timeout sets health check timeout in seconds.
description: |-
Timeout sets health check timeout in seconds.
https://github.com/apache/apisix/blob/0151d9e35bba63d7c316187272d88e19db0be634/apisix/schema_def.lua#L196
maximum: 254
minimum: 1
type: integer
type: object
type: object
Expand Down Expand Up @@ -344,9 +359,8 @@ spec:
- type
type: object
healthCheck:
description: |-
HealthCheck defines the active and passive health check configuration for the upstream.
Deprecated: no longer supported in standalone mode.
description: HealthCheck defines the active and passive health
check configuration for the upstream.
properties:
active:
description: Active health checks proactively send requests
Expand Down Expand Up @@ -389,7 +403,7 @@ spec:
description: Port sets the upstream port.
format: int32
maximum: 65535
minimum: 0
minimum: 1
type: integer
requestHeaders:
description: RequestHeaders sets the request headers.
Expand All @@ -404,6 +418,7 @@ spec:
format: int64
type: integer
type:
default: http
description: Type is the health check type. Can be `http`,
`https`, or `tcp`.
enum:
Expand Down Expand Up @@ -439,8 +454,11 @@ spec:
minimum: 0
type: integer
timeout:
description: Timeout sets health check timeout in
seconds.
description: |-
Timeout sets health check timeout in seconds.
https://github.com/apache/apisix/blob/0151d9e35bba63d7c316187272d88e19db0be634/apisix/schema_def.lua#L196
maximum: 254
minimum: 1
type: integer
type: object
type: object
Expand All @@ -467,9 +485,14 @@ spec:
type: integer
type: object
type:
default: http
description: |-
Type specifies the type of passive health check.
Can be `http`, `https`, or `tcp`.
enum:
- http
- https
- tcp
type: string
unhealthy:
description: Unhealthy defines the conditions under
Expand All @@ -495,8 +518,11 @@ spec:
minimum: 0
type: integer
timeout:
description: Timeout sets health check timeout in
seconds.
description: |-
Timeout sets health check timeout in seconds.
https://github.com/apache/apisix/blob/0151d9e35bba63d7c316187272d88e19db0be634/apisix/schema_def.lua#L196
maximum: 254
minimum: 1
type: integer
type: object
type: object
Expand Down Expand Up @@ -559,6 +585,8 @@ spec:
port:
description: Port is a Kubernetes Service port.
format: int32
maximum: 65535
minimum: 1
type: integer
retries:
description: |-
Expand Down
10 changes: 5 additions & 5 deletions docs/en/latest/reference/api-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -661,7 +661,7 @@ UpstreamActiveHealthCheckHealthy defines the conditions used to actively determi
| `httpCodes` _integer array_ | HTTPCodes define a list of HTTP status codes that are considered unhealthy. |
| `httpFailures` _integer_ | HTTPFailures define the number of HTTP failures to define an unhealthy target. |
| `tcpFailures` _integer_ | TCPFailures define the number of TCP failures to define an unhealthy target. |
| `timeout` _integer_ | Timeout sets health check timeout in seconds. |
| `timeout` _integer_ | Timeout sets health check timeout in seconds. https://github.com/apache/apisix/blob/0151d9e35bba63d7c316187272d88e19db0be634/apisix/schema_def.lua#L196 |
| `interval` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#duration-v1-meta)_ | Interval defines the time interval for checking targets, in seconds. |


Expand Down Expand Up @@ -1320,7 +1320,7 @@ ApisixUpstreamConfig defines configuration for upstream services.
| `scheme` _string_ | Scheme is the protocol used to communicate with the upstream. Default is `http`. Can be `http`, `https`, `grpc`, or `grpcs`. |
| `retries` _integer_ | Retries defines the number of retry attempts APISIX should make when a failure occurs. Failures include timeouts, network errors, or 5xx status codes. |
| `timeout` _[UpstreamTimeout](#upstreamtimeout)_ | Timeout specifies the connection, send, and read timeouts for upstream requests. |
| `healthCheck` _[HealthCheck](#healthcheck)_ | HealthCheck defines the active and passive health check configuration for the upstream. Deprecated: no longer supported in standalone mode. |
| `healthCheck` _[HealthCheck](#healthcheck)_ | HealthCheck defines the active and passive health check configuration for the upstream. |
| `tlsSecret` _[ApisixSecret](#apisixsecret)_ | TLSSecret references a Kubernetes Secret that contains the client certificate and key for mutual TLS when connecting to the upstream. |
| `subsets` _[ApisixUpstreamSubset](#apisixupstreamsubset) array_ | Subsets defines labeled subsets of service endpoints, typically used for service versioning or canary deployments. |
| `passHost` _string_ | PassHost configures how the host header should be determined when a request is forwarded to the upstream. Default is `pass`. Can be `pass`, `node` or `rewrite`:<br /> • `pass`: preserve the original Host header<br /> • `node`: use the upstream node’s host<br /> • `rewrite`: set to a custom host via upstreamHost |
Expand Down Expand Up @@ -1380,7 +1380,7 @@ definitions and custom configuration.
| `scheme` _string_ | Scheme is the protocol used to communicate with the upstream. Default is `http`. Can be `http`, `https`, `grpc`, or `grpcs`. |
| `retries` _integer_ | Retries defines the number of retry attempts APISIX should make when a failure occurs. Failures include timeouts, network errors, or 5xx status codes. |
| `timeout` _[UpstreamTimeout](#upstreamtimeout)_ | Timeout specifies the connection, send, and read timeouts for upstream requests. |
| `healthCheck` _[HealthCheck](#healthcheck)_ | HealthCheck defines the active and passive health check configuration for the upstream. Deprecated: no longer supported in standalone mode. |
| `healthCheck` _[HealthCheck](#healthcheck)_ | HealthCheck defines the active and passive health check configuration for the upstream. |
| `tlsSecret` _[ApisixSecret](#apisixsecret)_ | TLSSecret references a Kubernetes Secret that contains the client certificate and key for mutual TLS when connecting to the upstream. |
| `subsets` _[ApisixUpstreamSubset](#apisixupstreamsubset) array_ | Subsets defines labeled subsets of service endpoints, typically used for service versioning or canary deployments. |
| `passHost` _string_ | PassHost configures how the host header should be determined when a request is forwarded to the upstream. Default is `pass`. Can be `pass`, `node` or `rewrite`:<br /> • `pass`: preserve the original Host header<br /> • `node`: use the upstream node’s host<br /> • `rewrite`: set to a custom host via upstreamHost |
Expand Down Expand Up @@ -1528,7 +1528,7 @@ UpstreamPassiveHealthCheckUnhealthy defines the conditions used to passively det
| `httpCodes` _integer array_ | HTTPCodes define a list of HTTP status codes that are considered unhealthy. |
| `httpFailures` _integer_ | HTTPFailures define the number of HTTP failures to define an unhealthy target. |
| `tcpFailures` _integer_ | TCPFailures define the number of TCP failures to define an unhealthy target. |
| `timeout` _integer_ | Timeout sets health check timeout in seconds. |
| `timeout` _integer_ | Timeout sets health check timeout in seconds. https://github.com/apache/apisix/blob/0151d9e35bba63d7c316187272d88e19db0be634/apisix/schema_def.lua#L196 |


_Appears in:_
Expand All @@ -1550,7 +1550,7 @@ them if they are set on the port level.
| `scheme` _string_ | Scheme is the protocol used to communicate with the upstream. Default is `http`. Can be `http`, `https`, `grpc`, or `grpcs`. |
| `retries` _integer_ | Retries defines the number of retry attempts APISIX should make when a failure occurs. Failures include timeouts, network errors, or 5xx status codes. |
| `timeout` _[UpstreamTimeout](#upstreamtimeout)_ | Timeout specifies the connection, send, and read timeouts for upstream requests. |
| `healthCheck` _[HealthCheck](#healthcheck)_ | HealthCheck defines the active and passive health check configuration for the upstream. Deprecated: no longer supported in standalone mode. |
| `healthCheck` _[HealthCheck](#healthcheck)_ | HealthCheck defines the active and passive health check configuration for the upstream. |
| `tlsSecret` _[ApisixSecret](#apisixsecret)_ | TLSSecret references a Kubernetes Secret that contains the client certificate and key for mutual TLS when connecting to the upstream. |
| `subsets` _[ApisixUpstreamSubset](#apisixupstreamsubset) array_ | Subsets defines labeled subsets of service endpoints, typically used for service versioning or canary deployments. |
| `passHost` _string_ | PassHost configures how the host header should be determined when a request is forwarded to the upstream. Default is `pass`. Can be `pass`, `node` or `rewrite`:<br /> • `pass`: preserve the original Host header<br /> • `node`: use the upstream node’s host<br /> • `rewrite`: set to a custom host via upstreamHost |
Expand Down
1 change: 0 additions & 1 deletion docs/en/latest/upgrade-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,6 @@ spec:
Due to current limitations in the [ADC](https://github.com/api7/adc) component, the following fields are not yet supported:

* `spec.discovery`: Service Discovery
* `spec.healthCheck`: Health Checking

More details: [ADC Backend Differences](https://github.com/api7/adc/blob/2449ca81e3c61169f8c1e59efb4c1173a766bce2/libs/backend-apisix-standalone/README.md#differences-in-upstream)

Expand Down
Loading
Loading