BS-558 feat: add load balancer docs

api-reference/origin-errors/index.mdx

@@ -42,4 +42,8 @@ The API returns logs with the following error codes:
 | `http_invalid_compression` | Invalid compression in response |
 | `network_socket_exception` | Network socket exception |
 | `network_io_error` | Network I/O error |
+| `ssl_error` | TLS handshake with the origin failed (invalid origin certificate) |
 | `notfound_localdb` | Not found in local database |
+| `origin_url_malformed` | The configured origin URL is malformed |
+| `loadbalanced_origin_failure` | A load balancer origin failed |
+| `error` | Unknown or unclassified origin error |

cdn/limits.mdx

@@ -37,6 +37,15 @@ All limits can be increased upon request by contacting support with details abou
 
 ---
 
+## Load Balancer Limits
+
+| Limit                                | Default |
+|--------------------------------------|--------|
+| Max Origin Groups per Load Balancer  | 10     |
+| Max Origins per Load Balancer (across all groups) | 50     |
+
+---
+
 <Note>
 If you require higher limits on any of the above, please contact support with your use case and expected scale. Most limits can be adjusted.
 </Note>

cdn/load-balancer/health-and-failover.mdx

@@ -0,0 +1,56 @@
+---
+title: Health and Failover
+description: How origin health is monitored and how the Load Balancer fails over when an origin becomes unavailable.
+---
+
+The Load Balancer combines two layers of protection: active health checks that remove failing origins from rotation globally, and passive failure detection that reacts to problems observed in live traffic. Together they route traffic around outages without any manual intervention.
+
+## Health checks
+
+Health checks are configured per origin group and are disabled by default.
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| Enabled | disabled | Turns active health monitoring on for all origins in the group. |
+| Path | `/` | The path probed on each origin, up to 500 characters. |
+
+When enabled, the bunny.net monitoring network periodically sends a `GET` request to the configured path on every origin in the group. Each origin is either **Healthy** or **Degraded**:
+
+- Healthy origins participate in routing normally.
+- Degraded origins are removed from rotation across the entire edge network until the health check passes again.
+
+The current health status of every origin is visible in your Load Balancer configuration and via the API.
+
+<Tip>
+  Point the health check path at a lightweight endpoint such as `/healthz` rather than a heavy page. A good health endpoint also verifies the services your application depends on, such as its database or cache, and returns an error when any of them is unavailable. This lets an origin that is still serving traffic but cannot function correctly pull itself out of rotation until it is fully healthy again.
+</Tip>
+
+<Note>
+  Disabling health checks on a group immediately resets all of its origins to Healthy, so any origin that was removed from rotation starts receiving traffic again.
+</Note>
+
+## Passive failure detection
+
+Independently of health checks, every edge server tracks failures it observes in live traffic. An origin that fails repeatedly in a short period is temporarily taken out of rotation on that edge server and automatically re-tested. A successful response puts the origin back into full rotation.
+
+This layer works even with health checks disabled, and reacts faster than any active probe can, but its view is local to each edge server.
+
+## Failover
+
+For every request, the routing methods produce a complete ordered list of eligible origins (see [Routing methods](/cdn/load-balancer/routing)). The request goes to the first origin; if that fails, the Load Balancer moves down the list:
+
+- **Connection-level failures** (DNS errors, refused connections, TLS failures, timeouts) always trigger failover to the next origin. Nothing reached your origin, so any request can be safely retried elsewhere.
+- **HTTP 5xx responses from the origin** trigger failover only for requests that are safe to replay: requests without a body, excluding `POST`, `PUT`, and `PATCH`. For non-replayable requests, the origin's own error response is returned to the client instead, so a state-changing request is never delivered to two origins.
+- Failover stops as soon as response data has been streamed to the client.
+
+The failover chain is time-limited, so a request fails fast rather than working through a long list of slow origins indefinitely. Your Pull Zone's own origin retry settings (retry count, delay, and conditions) apply to the final origin in the chain.
+
+### When everything is failing
+
+The Load Balancer prefers degraded service over no service. If no origin passes the health filters, a request is still attempted against unhealthy origins as a last resort rather than being failed outright. Only origins and groups you have explicitly disabled are never used.
+
+If every eligible origin has been tried and failed, the client receives a `502 Bad Gateway` response.
+
+## Logging failures
+
+Each failed origin attempt is recorded in your Pull Zone's [origin error logs](/cdn/logging/origin-errors) with the specific cause (such as `dns_lookup`, `http_timeout`, or `ssl_error`), or `loadbalanced_origin_failure` as a general fallback. Per-origin failure counts, broken down by status code, are also available in [statistics](/cdn/load-balancer/statistics).

cdn/load-balancer/index.mdx

@@ -0,0 +1,77 @@
+---
+title: Load Balancer
+sidebarTitle: Overview
+description: Distribute Pull Zone traffic across multiple origins with configurable routing, health checks, and automatic failover.
+---
+
+The Load Balancer distributes uncached requests from your Pull Zones across multiple origin servers. Each request is routed using a configurable balancing method, origin health is monitored continuously, and traffic automatically fails over to healthy origins when a server becomes unavailable.
+
+A Load Balancer is a reusable routing policy that lives on your account. It does not have its own hostname. Instead, you attach it to one or more Pull Zones, and the CDN edge applies it whenever a request needs to be fetched from an origin. Requests served from the CDN cache never reach the Load Balancer.
+
+## How it works
+
+```mermaid
+flowchart LR
+    Client --> Edge[CDN edge]
+    Edge -->|cache MISS| LB[Load Balancer]
+    LB --> GroupA[Origin group A]
+    LB -.->|failover| GroupB[Origin group B]
+    GroupA --> O1[Origin 1]
+    GroupA --> O2[Origin 2]
+    GroupB --> O3[Origin 3]
+```
+
+When a request misses the cache, the edge server builds an ordered list of all eligible origins: it first orders your origin groups (by priority, then by the group balancing method), then orders the origins inside each group (by the group's origin balancing method). The first origin in the list receives the request, and the rest of the list is the failover order if it fails.
+
+## Concepts
+
+| Concept | Description |
+|---------|-------------|
+| Load Balancer | An account-level routing policy with a name, a group balancing method, and optional sticky sessions. Attachable to any number of Pull Zones. |
+| Origin group | A set of origins treated as one unit for balancing and failover. Each group has its own balancing method, weight, priority, and health check settings. |
+| Origin | A single backend: an HTTP(S) server, a Storage Zone, an Edge Script, or a Magic Containers endpoint. |
+
+## Connect a Pull Zone
+
+<Steps>
+  <Step title="Create a Load Balancer">
+    Create a Load Balancer with a unique name and choose how traffic is distributed between origin groups.
+  </Step>
+  <Step title="Add origin groups and origins">
+    Add at least one origin group, then add your origins to it. See [Origins and origin groups](/cdn/load-balancer/origins) for the available origin types and settings.
+  </Step>
+  <Step title="Attach it to a Pull Zone">
+    Set the Pull Zone's origin type to **Load Balancer** and select your Load Balancer. The Pull Zone's own origin URL is no longer used; each origin defines its own destination.
+  </Step>
+</Steps>
+
+A single Load Balancer can be attached to multiple Pull Zones, and all attached zones share the same routing policy. Switching a Pull Zone back to a different origin type detaches it again. A Load Balancer cannot be deleted while any Pull Zone still uses it as its origin.
+
+All configuration is also available through the API. See the [API reference](/api-reference/core) for the full endpoint documentation.
+
+## Explore
+
+<CardGroup cols={2}>
+  <Card title="Origins and origin groups" href="/cdn/load-balancer/origins">
+    Origin types, connection settings, and limits.
+  </Card>
+  <Card title="Routing methods" href="/cdn/load-balancer/routing">
+    How origin groups and origins are selected, weights, and priority tiers.
+  </Card>
+  <Card title="Sticky sessions" href="/cdn/load-balancer/sticky-sessions">
+    Pin returning visitors to the same origin using cookies.
+  </Card>
+  <Card title="Health and failover" href="/cdn/load-balancer/health-and-failover">
+    Health checks, failure detection, and automatic failover behavior.
+  </Card>
+  <Card title="Statistics" href="/cdn/load-balancer/statistics">
+    Per-origin traffic, latency, and failure metrics.
+  </Card>
+  <Card title="Pricing" href="/cdn/load-balancer/pricing">
+    Monthly fee, included requests, and overage billing.
+  </Card>
+</CardGroup>
+
+<Note>
+  Looking for DNS-level load balancing across multiple record values? That is a separate feature of Bunny DNS. See [DNS load balancing](/dns/records#load-balancing).
+</Note>

cdn/load-balancer/origins.mdx

@@ -0,0 +1,78 @@
+---
+title: Origins and Origin Groups
+description: Configure the origin groups and origins behind your Load Balancer, including origin types, connection settings, and limits.
+---
+
+A Load Balancer contains one or more origin groups, and each origin group contains one or more origins. Groups let you organize origins into units that are balanced and failed over together, for example a primary datacenter and a backup datacenter.
+
+## Origin groups
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| Name | required | Unique within the Load Balancer, up to 100 characters. |
+| Enabled | enabled | Disabled groups receive no traffic at all, including failover traffic. |
+| Weight | 100 | Relative share of traffic (1 to 255) when the group method is Weighted Random. |
+| Priority | 100 | Failover tier. Groups with a lower priority value are tried first; higher tiers only receive traffic when every origin in the lower tiers has failed. |
+| Balancing method | Round Robin | How origins inside this group are selected. See [Routing methods](/cdn/load-balancer/routing). |
+| Latitude / Longitude | 0, 0 | The group's geographic location, used by the Geo Location group balancing method. |
+| Health check | disabled | Active health monitoring for the group's origins. See [Health and failover](/cdn/load-balancer/health-and-failover). |
+
+## Origins
+
+Every origin has the following settings, plus type-specific configuration:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| Enabled | enabled | Disabled origins receive no traffic at all, including failover traffic. |
+| Weight | 100 | Relative share of traffic (1 to 255) when the group's method is Weighted Random. |
+| Type | Standard | One of the origin types below. |
+
+### Origin types
+
+| Type | Description |
+|------|-------------|
+| Standard | Any HTTP or HTTPS server, defined by an origin URL. |
+| Storage | A bunny.net [Storage Zone](/storage). |
+| Edge Script | A bunny.net [Edge Script](/scripting) of type CDN. |
+| Magic Containers | A [Magic Containers](/magic-containers) CDN endpoint. Anycast endpoints are not supported; add those as a Standard origin using the endpoint's IP address and port instead. |
+
+### Taking origins out of rotation
+
+Disable an origin to remove it from rotation without deleting its configuration. Typical reasons:
+
+- **Scheduled maintenance or deployments**: disable the origin before you start, so no new requests are routed to it while you work, then re-enable it when you are done.
+- **Incident response**: if you identify a problem with a server, disabling it removes it from rotation immediately while you investigate, without waiting for health checks to react.
+- **Staging a new server**: add the origin disabled, then enable it once the server is ready to receive traffic.
+
+Disabling an entire origin group works the same way and is useful for taking a whole location or datacenter offline at once. Disabled origins and groups receive no traffic under any circumstances, including failover.
+
+## Standard origin settings
+
+### Origin URL
+
+The origin URL must use HTTP or HTTPS, and can include a port and a path prefix that is prepended to every request path. For example, with an origin URL of `https://origin1.example.com:8443/api`, a client request for `/users` is fetched from `https://origin1.example.com:8443/api/users`.
+
+### Host header
+
+The `Host` header sent to a Standard origin is resolved in this order:
+
+1. If the Pull Zone has **Forward Host Header** enabled, the client's original host is forwarded.
+2. Otherwise, the origin's **Host Header** setting is used, if set.
+3. Otherwise, the hostname from the origin URL is used.
+
+### TLS verification
+
+When **Verify SSL** is enabled (the default), the edge validates the origin's TLS certificate and rejects the connection if validation fails. Disable it only if your origin uses a self-signed or otherwise invalid certificate.
+
+## Limits
+
+| Limit | Default |
+|-------|---------|
+| Origin groups per Load Balancer | 10 |
+| Origins per Load Balancer (across all groups) | 50 |
+
+Contact support if you need higher limits for your use case.
+
+## Updating configuration
+
+Configuration changes typically propagate to the edge network within seconds. Note that changing a Load Balancer can also reset active [sticky sessions](/cdn/load-balancer/sticky-sessions).

cdn/load-balancer/pricing.mdx

@@ -0,0 +1,34 @@
+---
+title: Load Balancer Pricing
+sidebarTitle: Pricing
+description: How Load Balancers are billed, including the monthly fee, included requests, and overage rates.
+---
+
+Each Load Balancer is billed a flat monthly fee that includes a generous request allowance, with a per-million rate for requests beyond it.
+
+| Item | Price |
+|------|-------|
+| Monthly fee, per Load Balancer | \$9.50 |
+| Included requests, per Load Balancer per month | 50 million |
+| Additional requests | \$0.65 per million |
+
+## What counts as a request
+
+Only requests that actually reach the Load Balancer are counted: cache misses and other requests that require an origin. Requests served from the CDN cache are not counted, so a well-cached zone typically sends only a small fraction of its total traffic through the Load Balancer.
+
+## How billing works
+
+- **Billing is per Load Balancer.** Attaching one Load Balancer to five Pull Zones incurs a single monthly fee, and requests from all attached zones share the same 50 million request allowance.
+- **The monthly fee is prorated.** You only pay for the time a Load Balancer exists: creating one mid-month charges the remainder of the month, and deleting one stops the charge immediately.
+- **The request allowance resets monthly.** Usage counts from the first of each calendar month (UTC), and every month starts with a fresh 50 million included requests. The allowance is per calendar month and unused requests do not roll over.
+- **Overage is exact.** Additional requests are billed at \$0.65 per million, prorated to the actual request count rather than rounded up to whole millions.
+
+For example, a Load Balancer that handles 62 million origin requests in a full month costs \$9.50 plus 12 million additional requests at \$0.65 per million, or \$17.30 in total.
+
+<Note>
+  The monthly fee applies from the moment a Load Balancer is created, even before it is attached to a Pull Zone. Delete Load Balancers you no longer use.
+</Note>
+
+## Tracking usage
+
+Month-to-date request usage against the included allowance is available per Load Balancer in the dashboard and through the usage API, including the exact time the allowance resets. See [Statistics](/cdn/load-balancer/statistics) for the full monitoring options.