Skip to content

Commit 4958fbe

Browse files
ZPain8464ZPain8464
authored
Updates load balancing ref page (#1318)
* adds health check table to load balancing page * adds health checks parameters and definitions * runs prettier * fixes typo * updates reference file * moves examples to lb reference page * adds links
1 parent cb5373f commit 4958fbe

File tree

3 files changed

+165
-44
lines changed

3 files changed

+165
-44
lines changed

‎content/docs/capabilities/load-balancing.md

+2-37
Original file line numberDiff line numberDiff line change
@@ -28,44 +28,9 @@ In the presence of multiple upstream servers, make sure to specify either an act
2828
2929
## Active Health Checks
3030
31-
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.
31+
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.
3232
33-
### HTTP Example
34-
35-
```yaml
36-
routes:
37-
- from: https://myapp.localhost.pomerium.io
38-
to:
39-
- http://myapp-srv-1:8080
40-
- http://myapp-srv-2:8080
41-
health_checks:
42-
- timeout: 10s
43-
interval: 60s
44-
healthy_threshold: 1
45-
unhealthy_threshold: 2
46-
http_health_check:
47-
path: '/'
48-
```
49-
50-
### TCP Example
51-
52-
```yaml
53-
routes:
54-
- from: tcp+https://tcp-service.localhost.pomerium.io
55-
to:
56-
- tcp://tcp-1.local
57-
- tcp://tcp-2.local
58-
health_checks:
59-
- timeout: 1s
60-
interval: 5s
61-
unhealthy_threshold: 3
62-
healthy_threshold: 1
63-
tcp_health_check:
64-
send:
65-
text: '50494E47' #PING
66-
receive:
67-
text: '504F4E47' #PONG
68-
```
33+
For example configurations in Pomerium, see the [Load Balancing](/docs/reference/routes/load-balancing#health-checks) reference page.
6934
7035
## Passive Health Checks
7136

‎content/docs/reference/reference.json

+84
Original file line numberDiff line numberDiff line change
@@ -839,6 +839,90 @@
839839
"services": ["proxy"],
840840
"type": "array of objects"
841841
},
842+
"health-checks-timeout": {
843+
"id": "http-health-check-timeout",
844+
"title": "Health Checks Timeout",
845+
"path": "/routes/load-balancing#supported-health-checks-parameters",
846+
"description": "The total time to wait for a health check response. Required.",
847+
"type": "duration"
848+
},
849+
"health-checks-interval": {
850+
"id": "http-health-check-interval",
851+
"title": "Health Checks Interval",
852+
"path": "/routes/load-balancing#supported-health-checks-parameters",
853+
"description": "The interval between health checks. Required.",
854+
"type": "duration"
855+
},
856+
"health-checks-unhealthy-threshold": {
857+
"id": "http-health-check-unhealthy-threshold",
858+
"title": "Health Checks Unhealthy Threshold",
859+
"path": "/routes/load-balancing#supported-health-checks-parameters",
860+
"description": "The number of unhealthy health checks required before a host is marked unhealthy. Required.",
861+
"type": "UInt32Value"
862+
},
863+
"health-checks-healthy-threshold": {
864+
"id": "http-health-check-healthy-threshold",
865+
"title": "Health Checks Healthy Threshold",
866+
"path": "/routes/load-balancing#supported-health-checks-parameters",
867+
"description": "The number of healthy health checks required before a host is marked healthy. Required.",
868+
"type": "UInt32Value"
869+
},
870+
"http-health-check-host": {
871+
"id": "http-health-check-host",
872+
"title": "HTTP Health Check Host",
873+
"path": "/routes/load-balancing#http-healthcheck-overview",
874+
"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.",
875+
"type": "string"
876+
},
877+
"http-health-check-path": {
878+
"id": "http-health-check-path",
879+
"title": "HTTP Health Check Path",
880+
"description": "Specifies the HTTP path requested during a health check. Required.",
881+
"path": "/routes/load-balancing#http-healthcheck-overview",
882+
"type": "string"
883+
},
884+
"http-health-check-expected-statuses": {
885+
"id": "http-health-check-expected-statuses",
886+
"title": "HTTP Health Check Expected Statuses",
887+
"path": "/routes/load-balancing#http-healthcheck-overview",
888+
"description": "Defines a range of HTTP response statuses that are considered healthy. Optional.",
889+
"type": "Int64Range"
890+
},
891+
"http-health-check-codec-client-type": {
892+
"id": "http-health-check-codec-client-type",
893+
"title": "HTTP Health Check Codec Client Type",
894+
"path": "/routes/load-balancing#http-healthcheck-overview",
895+
"description": "Specifies which application protocol to use. Optional.",
896+
"type": "CodecClientType"
897+
},
898+
"tcp-health-check-send": {
899+
"id": "tcp-health-check-send",
900+
"title": "TCP Health Check Send",
901+
"path": "/routes/load-balancing#tcp-healthcheck-overview",
902+
"description": "Defines the payload, which must be one of text or binary. An empty payload results in a connect-only health check. Optional.",
903+
"type": "Payload"
904+
},
905+
"tcp-health-check-receive": {
906+
"id": "tcp-health-check-receive",
907+
"title": "TCP Health Check Receive",
908+
"path": "/routes/load-balancing#tcp-healthcheck-overview",
909+
"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.",
910+
"type": "Payload"
911+
},
912+
"grpc-health-check-receive": {
913+
"id": "grpc-health-check-authority",
914+
"title": "gRPC Health Check Receive",
915+
"path": "/routes/load-balancing#grpc-healthcheck-overview",
916+
"description": "The ':authority' header value in a gRPC health check request. Optional.",
917+
"type": "string"
918+
},
919+
"grpc-health-check-service-name": {
920+
"id": "grpc-health-check-service-name",
921+
"title": "gRPC Health Check Service Name",
922+
"path": "/routes/load-balancing#grpc-healthcheck-overview",
923+
"description": "An optional service name parameter sent to the gRPC service. Optional.",
924+
"type": "string"
925+
},
842926
"headers-settings": {
843927
"id": "headers-settings",
844928
"title": "Headers Settings",

‎content/docs/reference/routes/load-balancing.mdx

+79-7
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,6 @@ import TabItem from '@theme/TabItem';
1313

1414
# Load Balancing Settings
1515

16-
This reference covers all of Pomerium's **Load Balancing Settings**:
17-
18-
- [Load Balancing Policy](#load-balancing-policy)
19-
- [Health Checks](#health-checks)
20-
2116
## Load Balancing Policy {#load-balancing-policy}
2217

2318
**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
9388

9489
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.
9590

91+
### Supported health checks parameters
92+
93+
| **Config file keys** | **Definition** | **Type** | **Usage** |
94+
| :-- | :-- | :-- | :-- |
95+
| `timeout` | The total time to wait for a health check response. | [`Duration`](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration) | **required** |
96+
| `interval` | The interval between health checks. | [`Duration`](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration) | **required** |
97+
| `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** |
98+
| `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** |
99+
96100
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).
97101

98102
### How to configure {#how-to-configure-health-checks}
99103

100-
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.
104+
You may configure only one of the following options per `health_check` object definition:
105+
106+
- `http_health_check`
107+
- `tcp_health_check`
108+
- `grpc_health_check`
109+
110+
#### HTTP health check {#http-healthcheck-overview}
111+
112+
| **Config file keys** | **Definition** | **Type** | **Usage** |
113+
| :-- | :-- | :-- | :-- |
114+
| `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** |
115+
| `path` | Specifies the HTTP path requested during a health check. For example, `/healthcheck`. | `string` | **required** |
116+
| `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** |
117+
| `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** |
118+
119+
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.
120+
121+
#### TCP health check {#tcp-healthcheck-overview}
122+
123+
| **Config file keys** | **Definition** | **Type** | **Usage** |
124+
| :-- | :-- | :-- | :-- |
125+
| `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** |
126+
| `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** |
127+
128+
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.
129+
130+
#### gRPC health check {#grpc-healthcheck-overview}
131+
132+
| **Config file keys** | **Definition** | **Type** | **Usage** |
133+
| :-- | :-- | :-- | :-- |
134+
| `authority` | The `:authority` header value in a gRPC health check request. | `string` | **optional** |
135+
| `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** |
101136

102-
See [Load Balancing](/docs/capabilities/load-balancing.md) for example [configurations](/docs/capabilities/load-balancing.md#active-health-checks).
137+
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.
103138

104139
<Tabs>
105140
<TabItem value="Core" label="Core">
@@ -108,6 +143,43 @@ See [Load Balancing](/docs/capabilities/load-balancing.md) for example [configur
108143
| :------------------- | :----------------- | :----------- |
109144
| `health_checks` | `array of objects` | **optional** |
110145

146+
### HTTP example configuration
147+
148+
```yaml
149+
routes:
150+
- from: https://myapp.localhost.pomerium.io
151+
to:
152+
- http://myapp-srv-1:8080
153+
- http://myapp-srv-2:8080
154+
health_checks:
155+
- timeout: 10s
156+
interval: 60s
157+
healthy_threshold: 1
158+
unhealthy_threshold: 2
159+
http_health_check:
160+
path: '/'
161+
```
162+
163+
### TCP example configuration
164+
165+
```yaml
166+
routes:
167+
- from: tcp+https://tcp-service.localhost.pomerium.io
168+
to:
169+
- tcp://tcp-1.local
170+
- tcp://tcp-2.local
171+
health_checks:
172+
- timeout: 1s
173+
interval: 5s
174+
unhealthy_threshold: 3
175+
healthy_threshold: 1
176+
tcp_health_check:
177+
send:
178+
text: '50494E47' #PING
179+
receive:
180+
text: '504F4E47' #PONG
181+
```
182+
111183
</TabItem>
112184
<TabItem value="Enterprise" label="Enterprise">
113185

0 commit comments

Comments
 (0)