Skip to main content

​
Overview

Open-source GoModel sends one provider through one proxy with proxy_url. That is enough for a single geo-restricted provider, but not for a fleet that must always leave through an allowlisted egress IP: when that one proxy goes down, every request behind it fails. Egress proxy pools add the missing pieces:
  • Pools of HTTP, HTTPS, SOCKS5, or SOCKS5h proxies, picked by failover (first healthy, in order) or round_robin.
  • Health checks that probe every proxy on a schedule and skip members that fail, then bring them back once they pass again.
  • Rules that assign providers to pools by name pattern or provider type, so a new provider is covered without touching its own configuration.
A provider’s own proxy_url still wins over any rule. Providers that no rule matches keep the gateway-wide HTTP_PROXY, HTTPS_PROXY, and NO_PROXY behaviour.
Like SSO, enabled egress fails closed: startup aborts when the egress entitlement is missing or the configuration is invalid. Traffic that was meant to leave through a proxy never silently leaves from the gateway’s own address instead.

​
Configure pools

Configure them under extensions.egress in the main GoModel YAML configuration:
Rules are evaluated in order and the first match wins. A pattern matches the provider name (openai-eu, openai*); with a type: prefix it matches the provider type instead (type:gemini). With a single pool and no rules every provider uses that pool. The same settings are available as environment variables, which override the YAML values. One pool per PRO_EGRESS_PROXY_<NAME>; the name becomes the pool name in lowercase with underscores as hyphens (EU_STATIC becomes eu-static):

​
Health checks and failover

Every member is probed before the gateway serves its first request, so a proxy that is already down never receives traffic. Without check_url a probe is a TCP connection to the proxy port. With check_url it is a HEAD request through the proxy; any relayed response counts as healthy, including 401 or 404 from the target, while a 5xx counts as failure because forward proxies answer 502, 503, and 504 themselves when they cannot reach the target. After the first probe a member needs failure_threshold consecutive failures to be skipped and one success to return. When every member of a pool is unhealthy the pool is still used, starting with its first member, and a warning is logged once per outage. A matched pool never falls back to a direct connection.

​
Inspect

Health transitions are logged with the pool name, member position, and the proxy URL with any password masked. Prometheus exposes:
  • gomodel_pro_egress_proxy_healthy{pool,member,proxy}: 1 while the member is in rotation.
  • gomodel_pro_egress_health_checks_total{pool,member,proxy,result}: probes by outcome.
  • gomodel_pro_egress_selections_total{pool,member,proxy}: requests each member was chosen for.
Alert on gomodel_pro_egress_proxy_healthy == 0 to learn about a dead proxy before the pool runs out of members.
Last modified on September 24, 2026