diff --git a/content/docs/capabilities/load-balancing.md b/content/docs/capabilities/load-balancing.md index 8a5ce35d2..e072b530b 100644 --- a/content/docs/capabilities/load-balancing.md +++ b/content/docs/capabilities/load-balancing.md @@ -28,44 +28,9 @@ In the presence of multiple upstream servers, make sure to specify either an act ## Active Health Checks -Active health checks issue periodic requests to each upstream to determine its health. See [Health Checking](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/health_checking) for a comprehensive overview. +Active health checks issue periodic requests to each upstream to determine its health. See the [Envoy Health Checking documentation](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/health_checking) for a comprehensive overview. -### HTTP Example - -```yaml -routes: - - from: https://myapp.localhost.pomerium.io - to: - - http://myapp-srv-1:8080 - - http://myapp-srv-2:8080 - health_checks: - - timeout: 10s - interval: 60s - healthy_threshold: 1 - unhealthy_threshold: 2 - http_health_check: - path: '/' -``` - -### TCP Example - -```yaml -routes: - - from: tcp+https://tcp-service.localhost.pomerium.io - to: - - tcp://tcp-1.local - - tcp://tcp-2.local - health_checks: - - timeout: 1s - interval: 5s - unhealthy_threshold: 3 - healthy_threshold: 1 - tcp_health_check: - send: - text: '50494E47' #PING - receive: - text: '504F4E47' #PONG -``` +For example configurations in Pomerium, see the [Load Balancing](/docs/reference/routes/load-balancing#health-checks) reference page. ## Passive Health Checks diff --git a/content/docs/reference/reference.json b/content/docs/reference/reference.json index a753ae688..d4cb64b68 100644 --- a/content/docs/reference/reference.json +++ b/content/docs/reference/reference.json @@ -837,6 +837,90 @@ "services": ["proxy"], "type": "array of objects" }, + "health-checks-timeout": { + "id": "http-health-check-timeout", + "title": "Health Checks Timeout", + "path": "/routes/load-balancing#supported-health-checks-parameters", + "description": "The total time to wait for a health check response. Required.", + "type": "duration" + }, + "health-checks-interval": { + "id": "http-health-check-interval", + "title": "Health Checks Interval", + "path": "/routes/load-balancing#supported-health-checks-parameters", + "description": "The interval between health checks. Required.", + "type": "duration" + }, + "health-checks-unhealthy-threshold": { + "id": "http-health-check-unhealthy-threshold", + "title": "Health Checks Unhealthy Threshold", + "path": "/routes/load-balancing#supported-health-checks-parameters", + "description": "The number of unhealthy health checks required before a host is marked unhealthy. Required.", + "type": "UInt32Value" + }, + "health-checks-healthy-threshold": { + "id": "http-health-check-healthy-threshold", + "title": "Health Checks Healthy Threshold", + "path": "/routes/load-balancing#supported-health-checks-parameters", + "description": "The number of healthy health checks required before a host is marked healthy. Required.", + "type": "UInt32Value" + }, + "http-health-check-host": { + "id": "http-health-check-host", + "title": "HTTP Health Check Host", + "path": "/routes/load-balancing#http-healthcheck-overview", + "description": "The Host header value in the HTTP health check request. If empty, the name of the cluster this health check is associated with will be used. Optional.", + "type": "string" + }, + "http-health-check-path": { + "id": "http-health-check-path", + "title": "HTTP Health Check Path", + "description": "Specifies the HTTP path requested during a health check. Required.", + "path": "/routes/load-balancing#http-healthcheck-overview", + "type": "string" + }, + "http-health-check-expected-statuses": { + "id": "http-health-check-expected-statuses", + "title": "HTTP Health Check Expected Statuses", + "path": "/routes/load-balancing#http-healthcheck-overview", + "description": "Defines a range of HTTP response statuses that are considered healthy. Optional.", + "type": "Int64Range" + }, + "http-health-check-codec-client-type": { + "id": "http-health-check-codec-client-type", + "title": "HTTP Health Check Codec Client Type", + "path": "/routes/load-balancing#http-healthcheck-overview", + "description": "Specifies which application protocol to use. Optional.", + "type": "CodecClientType" + }, + "tcp-health-check-send": { + "id": "tcp-health-check-send", + "title": "TCP Health Check Send", + "path": "/routes/load-balancing#tcp-healthcheck-overview", + "description": "Defines the payload, which must be one of text or binary. An empty payload results in a connect-only health check. Optional.", + "type": "Payload" + }, + "tcp-health-check-receive": { + "id": "tcp-health-check-receive", + "title": "TCP Health Check Receive", + "path": "/routes/load-balancing#tcp-healthcheck-overview", + "description": "Checks a response with 'fuzzy' matching to the extent that each payload block must be found, and in the specified order, but not necessarily contiguous. Optional.", + "type": "Payload" + }, + "grpc-health-check-receive": { + "id": "grpc-health-check-authority", + "title": "gRPC Health Check Receive", + "path": "/routes/load-balancing#grpc-healthcheck-overview", + "description": "The ':authority' header value in a gRPC health check request. Optional.", + "type": "string" + }, + "grpc-health-check-service-name": { + "id": "grpc-health-check-service-name", + "title": "gRPC Health Check Service Name", + "path": "/routes/load-balancing#grpc-healthcheck-overview", + "description": "An optional service name parameter sent to the gRPC service. Optional.", + "type": "string" + }, "headers-settings": { "id": "headers-settings", "title": "Headers Settings", diff --git a/content/docs/reference/routes/load-balancing.mdx b/content/docs/reference/routes/load-balancing.mdx index f51c7ca40..8bb673a32 100644 --- a/content/docs/reference/routes/load-balancing.mdx +++ b/content/docs/reference/routes/load-balancing.mdx @@ -13,11 +13,6 @@ import TabItem from '@theme/TabItem'; # Load Balancing Settings -This reference covers all of Pomerium's **Load Balancing Settings**: - -- [Load Balancing Policy](#load-balancing-policy) -- [Health Checks](#health-checks) - ## Load Balancing Policy {#load-balancing-policy} **Load Balancing Policy** defines the load balancing strategy between multiple upstream servers. @@ -93,13 +88,53 @@ When defined, **Health Checks** will issue periodic health check requests to ups See Envoy's [`outlier_detection`](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/outlier) for automatic upstream server health detection. In the presence of multiple upstream servers, it is recommended to set up either `health_checks`, `outlier_detection`, or both. +### Supported health checks parameters + +| **Config file keys** | **Definition** | **Type** | **Usage** | +| :-- | :-- | :-- | :-- | +| `timeout` | The total time to wait for a health check response. | [`Duration`](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration) | **required** | +| `interval` | The interval between health checks. | [`Duration`](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration) | **required** | +| `unhealthy_threshold` | The number of unhealthy health checks required before a host is marked unhealthy. | [`UInt32Value`](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#uint32value) | **required** | +| `healthy_threshold` | The number of healthy health checks required before a host is marked healthy. | [`UInt32Value`](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#uint32value) | **required** | + See the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/health_checking) for a list of [supported parameters](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/health_check.proto#envoy-v3-api-msg-config-core-v3-healthcheck). ### How to configure {#how-to-configure-health-checks} -Only one of [`http_health_check`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/health_check.proto#envoy-v3-api-msg-config-core-v3-healthcheck-httphealthcheck), [`tcp_health_check`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/health_check.proto#envoy-v3-api-msg-config-core-v3-healthcheck-tcphealthcheck), or [`grpc_health_check`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/health_check.proto#envoy-v3-api-msg-config-core-v3-healthcheck-grpchealthcheck) may be configured per `health_check` object definition. +You may configure only one of the following options per `health_check` object definition: + +- `http_health_check` +- `tcp_health_check` +- `grpc_health_check` + +#### HTTP health check {#http-healthcheck-overview} + +| **Config file keys** | **Definition** | **Type** | **Usage** | +| :-- | :-- | :-- | :-- | +| `host` | The Host header value in the HTTP health check request. If empty (default value), the name of the cluster this health check is associated with will be used. | `string` | **optional** | +| `path` | Specifies the HTTP path requested during a health check. For example, `/healthcheck`. | `string` | **required** | +| `expected_statuses` | Defines a range of HTTP response statuses that are considered healthy. | [`Int64Range`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/v3/range.proto#envoy-v3-api-msg-type-v3-int64range) | **optional** | +| `codec_client_type` | Specifies which application protocol to use: `HTTP1` or `HTTP2`. | [`CodecClientType`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/v3/http.proto#envoy-v3-api-enum-type-v3-codecclienttype) | **optional** | + +See the [Envoy HTTP health checks documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/health_check.proto#envoy-v3-api-msg-config-core-v3-healthcheck-httphealthcheck) for more information. + +#### TCP health check {#tcp-healthcheck-overview} + +| **Config file keys** | **Definition** | **Type** | **Usage** | +| :-- | :-- | :-- | :-- | +| `send` | Defines the payload, which must be one of [text](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/health_check.proto#envoy-v3-api-field-config-core-v3-healthcheck-payload-text) or [binary](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/health_check.proto#envoy-v3-api-field-config-core-v3-healthcheck-payload-binary). An empty payload results in a connect-only health check. | [`Payload`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/health_check.proto#envoy-v3-api-msg-config-core-v3-healthcheck-payload) | **optional** | +| `receive` | Checks a response with 'fuzzy' matching to the extent that each payload block must be found, and in the specified order, but not necessarily contiguous. | [`Payload`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/health_check.proto#envoy-v3-api-msg-config-core-v3-healthcheck-payload) | **optional** | + +See the [Envoy TCP health checks documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/health_check.proto#config-core-v3-healthcheck-tcphealthcheck) for more information. + +#### gRPC health check {#grpc-healthcheck-overview} + +| **Config file keys** | **Definition** | **Type** | **Usage** | +| :-- | :-- | :-- | :-- | +| `authority` | The `:authority` header value in a gRPC health check request. | `string` | **optional** | +| `service_name` | A service name parameter sent to the gRPC service. See [gRPC health checking](https://github.com/grpc/grpc/blob/master/doc/health-checking.md) for more information. | `string` | **optional** | -See [Load Balancing](/docs/capabilities/load-balancing.md) for example [configurations](/docs/capabilities/load-balancing.md#active-health-checks). +See the [Envoy gRPC health checks documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/health_check.proto#config-core-v3-healthcheck-grpchealthcheck) for more information. @@ -108,6 +143,43 @@ See [Load Balancing](/docs/capabilities/load-balancing.md) for example [configur | :------------------- | :----------------- | :----------- | | `health_checks` | `array of objects` | **optional** | +### HTTP example configuration + +```yaml +routes: + - from: https://myapp.localhost.pomerium.io + to: + - http://myapp-srv-1:8080 + - http://myapp-srv-2:8080 + health_checks: + - timeout: 10s + interval: 60s + healthy_threshold: 1 + unhealthy_threshold: 2 + http_health_check: + path: '/' +``` + +### TCP example configuration + +```yaml +routes: + - from: tcp+https://tcp-service.localhost.pomerium.io + to: + - tcp://tcp-1.local + - tcp://tcp-2.local + health_checks: + - timeout: 1s + interval: 5s + unhealthy_threshold: 3 + healthy_threshold: 1 + tcp_health_check: + send: + text: '50494E47' #PING + receive: + text: '504F4E47' #PONG +``` +