Overload protection

When an edge is asked for more than it can serve, it is better to refuse the surplus at once than to queue it until every request is slow. Overload protection does that, and it is configured per edge from central, so you can change it without redeploying. You need an edge that is already registered and an operator with edges:manage; edges:read shows the settings and nothing more.

What it protects

Two guards, each with its own mode and its own settings:

central is never limited by the outbound guard, so a service can still wait for its configuration at start-up, and nothing is enforced until the service has started.

The three modes

Priorities

Inbound admission does not treat requests alike. A request is admitted while the requests in flight are below its tier’s share of the limit, so the top of the limit stays free for work that matters more:

1. New login (the most expensive, work not yet started): refused first. It may use the start share of the limit, default 0.65.
2. Work already begun (code exchange, logout): refused next. It may use the continuation share, default 0.85.
3. Proxied calls to your API: refused last. They may use the whole limit.
4. Health and metrics, configuration sync and back-channel logout: never counted and never refused.

What the numbers mean

The limit is not a number someone guessed. The edge learns it from how long calls take and from how late its own executor runs a timer: it shrinks when calls slow down or the executor stalls, and grows back while calls are fast, between a lowest and a highest limit. It is learned whenever the inbound mode is not off; in shadow it is learned and nothing is refused. The starting limit is only where it begins (clamped into the bounds).

Every field is optional. A field left empty is not sent, and the edge uses its own deployment’s value: the HTTP_ADMISSION_* or HTTP_CLIENT_GUARD_* environment variable when the edge sets one, otherwise the built-in default. Setting one field does not pin the rest.

Inbound

A starting limit below minLimit or above maxLimit starts at the nearest bound.

Outbound

Queueing and timeouts apply in enforce only.

Set it in the console

Open Edges, open the edge, and use Edit on the Overload protection card. The editor opens in the side panel: an inbound section and an outbound section, each with a short note on how to tune it, the mode as a choice of Deployment default, Off, Shadow and Enforce, and every other field with the default (and its environment variable) written under it. The rarely changed tolerance, smoothing and lag target sit under Advanced.

×

×

The editor checks the ranges as you type, with the same messages central uses, and does not send a policy that fails them. Save overload protection sends only the fields you filled in. Reset to deployment defaults removes the policy after a confirmation, and the edge goes back to its own deployment’s values.

A change reaches the edge on its next configuration sync, inside the refresh interval (5 minutes by default). While central is unreachable the edge keeps the last policy it received. A policy that fails validation is refused by central and not applied by an edge.

Set it by API

PATCH /configuration/edges/policies?edgeId=<id> with an overload section replaces the policy as a whole; "overload": null removes it, and the other sections of the edge (accessLog, rateLimits) are left as they are. The section is the OverloadPolicy schema in the central OpenAPI file. Fields the schema does not know are ignored. expectedRevisions and dryRun are described on Rate limits.

{
  "overload": {
    "inbound": {
      "mode": "enforce",
      "adaptive": { "maxLimit": 1536 }
    },
    "outbound": { "mode": "shadow" }
  }
}

A value outside its range answers 400 with no body; the first problem found is in central’s log.

Roll it out

1. Leave shadow, the default, for at least a day of real traffic that includes a peak.
2. Read http_admission_refused_total{mode="shadow"}. Near zero while the edge has capacity means the limit is not in the way. Many shadow refusals at the peak mean enforce would shed that traffic: raise adaptive.maxLimit or add capacity first.
3. Set the inbound mode to enforce on one edge. Watch refusals, throughput and latency through a peak, then do the others.
4. Do the outbound guard one step later in the same way, and turn the circuit breaker on last.

What a client sees in enforce: 503 with Retry-After: <retryAfterSeconds>. A client should wait at least that long, add jitter, and retry a bounded number of times; an immediate retry loop makes the overload worse.

Read the metrics

Tune it

Next steps

• Rate limits — refusing a caller that sends more than its share, with 429
• Observability — the metrics endpoint and what else to alert on
• Edges — the screen this page adds a card to
• Edge configuration — the environment of an edge