Skip to content
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

Updates load balancing ref page #1318

Merged
merged 7 commits into from
Mar 25, 2024
Merged

Updates load balancing ref page #1318

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
e7dba04
adds health check table to load balancing page
ZPain8464 Mar 20, 2024
944bf33
adds health checks parameters and definitions
ZPain8464 Mar 20, 2024
6a1ee0c
runs prettier
ZPain8464 Mar 20, 2024
dd121e3
fixes typo
ZPain8464 Mar 20, 2024
4b81fe1
updates reference file
ZPain8464 Mar 22, 2024
db5f13b
moves examples to lb reference page
ZPain8464 Mar 22, 2024
1b36e13
adds links
ZPain8464 Mar 22, 2024
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
39 changes: 2 additions & 37 deletions content/docs/capabilities/load-balancing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
84 changes: 84 additions & 0 deletions content/docs/reference/reference.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
86 changes: 79 additions & 7 deletions content/docs/reference/routes/load-balancing.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we move examples here for consistency with other topics? (and expand the configuration examples to cover both core, enterprise and IC?)

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.

<Tabs>
<TabItem value="Core" label="Core">
Expand All @@ -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
```

</TabItem>
<TabItem value="Enterprise" label="Enterprise">

Expand Down
Loading