pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-10-21 20:19:11 +02:00
Code Issues Packages Projects Releases Wiki Activity

add load balancing strategy

Browse Source
This commit is contained in:
miloschwartz
2026-10-20 12:20:43 -04:00
parent 28da1deb48
commit d58a2bc9cd
4 changed files with 35 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/docs/manage/blueprints.mdx
+4 -2
View File
@@ -285,7 +285,7 @@ When a resource is targets-only, `name` and `mode` are not required.
### Load Balancing Example
When a resource has more than one target, `load-balancing-strategy` controls how requests are spread across them.
When an HTTP resource has more than one target, `load-balancing-strategy` controls how requests are spread across them. The same options are available on the resource **Proxy** tab. See [Load Balancing Strategy](/manage/resources/public/targets#load-balancing-strategy).
```yaml
public-resources:
@@ -312,6 +312,8 @@ Strategy values:
- **`hrw`**: Client IP hash. The same client IP is consistently routed to the same target.
- **`leasttime`**: Least response time. Requests go to the target with the fastest response time and fewest active connections.
TCP/UDP (`mode: tcp` / `mode: udp`) resources ignore this field and always use round robin.
### Identity Headers Example
By default, Pangolin forwards the authenticated user's identity to the backend in the `Remote-User`, `Remote-Email`, `Remote-Name`, `Remote-Role`, and `Remote-User-Id` headers. Set `forward-identity-headers: false` to stop sending them, for example when the backend should not see user details. See [Forwarded Headers](/manage/access-control/forwarded-headers).
@@ -1017,7 +1019,7 @@ public-resources:
</ResponseField>
<ResponseField name="load-balancing-strategy" type="string">
How requests are distributed across the resource's targets.
How requests are distributed across the resource's targets. Applies to HTTP resources only; TCP/UDP always use round robin. See [Load Balancing Strategy](/manage/resources/public/targets#load-balancing-strategy).
- `wrr`: Round robin. Requests rotate evenly across targets.
- `p2c`: Power of two choices. Pick two random targets and send the request to the one with fewer active connections.
content/docs/manage/resources/public/http-https.mdx
+2 -2
View File
@@ -37,8 +37,8 @@ Pangolin acts as a front-door barrier: unauthenticated visitors are redirected t
HTTP/HTTPS resources use **[targets](/manage/resources/public/targets)** to define where traffic is sent on your remote network.
- Add one or more targets, each with an upstream address and port.
- Assign each target to a site. Targets on different sites enable [round-robin load balancing](/manage/resources/public/targets#multi-site-targets) and [automatic failover](/manage/resources/public/healthchecks-failover).
- Optionally configure path-based routing, path rewriting, custom host headers, and other proxy settings.
- Assign each target to a site. Targets on different sites enable [load balancing](/manage/resources/public/targets#load-balancing-strategy) and [automatic failover](/manage/resources/public/healthchecks-failover).
- Optionally configure path-based routing, path rewriting, a load balancing strategy, sticky sessions, custom host headers, and other proxy settings.
This multi-target model differs from SSH, RDP, and VNC public resources, which use site selection and a single host/port instead of discrete targets.
content/docs/manage/resources/public/raw-resources.mdx
+2 -2
View File
@@ -14,7 +14,7 @@ For workloads that do not need a public proxy, prefer a [private host or CIDR re
- Expose any TCP or UDP service, whatever the protocol, without opening ports on the backend network.
- The backend stays behind NAT or a firewall. Only the Pangolin server needs a public port.
- Players or users connect with their normal client software, with no Pangolin client to install.
- Multiple targets across sites give round-robin routing and failover.
- Multiple targets across sites give round-robin routing and failover. Unlike HTTP resources, TCP/UDP always use round robin (no strategy picker).
- Proxy Protocol can pass the original client IP through to backends that support it.
## Use Cases
@@ -36,7 +36,7 @@ Pangolin does not inspect or authenticate the traffic, so any security has to co
TCP and UDP resources use **[targets](/manage/resources/public/targets)** like HTTP/HTTPS resources:
- Add one or more targets with an upstream address and port.
- Assign targets to different sites for round-robin routing and failover.
- Assign targets to different sites for round-robin routing and failover. Load balancing strategy options on the Proxy tab apply to HTTP resources only; see [Targets](/manage/resources/public/targets#load-balancing-strategy).
## Self-Hosted Setup
content/docs/manage/resources/public/targets.mdx
+27 -6
View File
@@ -19,6 +19,27 @@ Targets function as destination endpoints for your resources:
In the public resource **Proxy** tab, Pangolin also provides additional proxy settings for how requests are sent to the upstream target.
### Load Balancing Strategy
When an [HTTP / HTTPS](/manage/resources/public/http-https) resource has more than one eligible target in the same routing group, Pangolin spreads requests across those targets. Choose the strategy on the resource **Proxy** tab (or with `load-balancing-strategy` in a [blueprint](/manage/blueprints#load-balancing-example)).
| Strategy | Behavior |
| --- | --- |
| Round Robin (default) | Rotate requests evenly across targets. |
| Power of Two Choices | Pick two random targets and send the request to the one with fewer active connections. |
| Client IP Hash | Hash the client IP so the same client is consistently routed to the same target. |
| Least Response Time | Send requests to the target with the fastest response time and fewest active connections. |
Notes:
- Strategy applies per routing group. Targets that share the same path match and path rewrite settings are load balanced together using the resource's strategy.
- Disabled targets, offline sites (when any peer site is online), and [unhealthy](/manage/resources/public/healthchecks-failover) targets are excluded from the pool.
- [TCP / UDP](/manage/resources/public/raw-resources) resources always use round robin. The strategy setting is HTTP-only.
### Sticky Sessions
Enable **Sticky Sessions** on the **Proxy** tab when clients should stay on the same target after the first request. For HTTP/HTTPS, Pangolin sets a sticky cookie (`p_sticky`). Sticky sessions work alongside the load balancing strategy: the strategy picks the first target, then sticky keeps follow-up requests on that target while it remains available.
### Custom Host Header
Use **Custom Host Header** when the upstream application expects a specific `Host` value instead of the public resource hostname.
@@ -52,14 +73,14 @@ Targets have sites associated with them. This provides significant benefits for
### Site-Distributed Resources
You can now configure targets across different sites for the same resource:
You can configure targets across different sites for the same resource:
<Card title="High Availability">
Distribute your resources across multiple sites so that if one site goes down, traffic automatically continues to be served from other available sites.
</Card>
<Card title="Load Balancing">
Set up load balancing across sites to distribute traffic in a round-robin fashion between all available targets.
Spread traffic across targets on one or more sites using the resource [load balancing strategy](#load-balancing-strategy).
</Card>
### Distributing Sites Load Across Servers
@@ -68,9 +89,9 @@ You can now configure targets across different sites for the same resource:
This is an [Enterprise Edition](/self-host/enterprise-edition)-only feature.
</Note>
On highly available clustered Enterprise Pangolin servers - lik the cloud platform - different sites can connect to different nodes. If one of the nodes goes down, the site moves to another node. This has implications for site-based load balancing, because DNS must can only route a FQDN to one Pangolin server node at a time.
On highly available clustered Enterprise Pangolin servers (like the cloud platform), different sites can connect to different nodes. If one of the nodes goes down, the site moves to another node. This has implications for site-based load balancing, because DNS can only route a FQDN to one Pangolin server node at a time.
Load balancing between different targets only works when sites are connected to the same Pangolin node. In Pangolin instances with multiple remote nodes, ensure load balancing occurs on the same node.
Load balancing between different targets only works when those sites are connected to the same Pangolin node. The strategy you choose still applies, but each node only sees targets for sites attached to it. In Pangolin instances with multiple remote nodes, pin the sites you want to load balance together to the same node.
To ensure effective load balancing in multi-node environments:
@@ -121,7 +142,7 @@ Example: Path `^/api/users/[0-9]+$` with regex match matches `/api/users/123` bu
### Load Balancing with Path-Based Routing
When multiple targets have the same path and match configuration, Pangolin will load balance between them using round-robin distribution.
When multiple targets have the same path and match configuration, Pangolin load balances between them using the resource [load balancing strategy](#load-balancing-strategy) (default: round robin).
**Example Scenario:**
- Target 1: Path `/api`, Match `prefix`, Address `10.0.1.10:8080`
@@ -212,7 +233,7 @@ Pangolin automatically normalizes paths to ensure correct routing:
### Load Balancing with Path Rewriting
All targets with identical path match and path rewrite configurations will be load balanced together.
All targets with identical path match and path rewrite configurations are load balanced together using the resource [load balancing strategy](#load-balancing-strategy).
**Example:**
- Target 1: Match `/api` (prefix), Rewrite `/v2` (prefix), Address `10.0.1.10:8080`